Customer Meta Data

  1. Overview
  2. Meta Data Enabled Calls
  3. Adding Meta Data
  4. Updating Meta Data
  5. Deleting Meta Data
  6. Using Meta Data in Email Templates
  7. Reasonable Use

1. Overview

The CheddarGetter API includes provisions for you to send arbitrary data fields along with your customer information. If you need to pass some additional billing-related information through CheddarGetter for whatever reason, you may use the meta data feature.

2. Meta Data Enabled Calls

Three API calls include the meta data feature:

  1. Create a New Customer
  2. Update a Customer and Subscription
  3. Update a Customer Only

3. Adding Meta Data

When using these API calls, if you include POST data in the following format:

metaData[meta1]=whatever1b&metaData[meta3]=whatever3&metaData[subarray][meta3]=whatever3

The data will be saved with the customer as meta data and returned in the customer XML. Here's a clipping:

<customers> 
  <customer id="005787be-9a18-102d-83a2-86fc5ee048c5" code="BMETADATA"> 
    <firstName>Bob</firstName> 
    <lastName>MetaData</lastName> 
    <company/> 
    <email>bobmetadata1271360888@example.com</email> 
    <notes>these are some notes for the customer</notes> 
    <gatewayToken>SIMULATED</gatewayToken> 
    <createdDatetime>2010-04-15T15:48:09-04:00</createdDatetime> 
    <modifiedDatetime>2010-04-15T15:48:09-04:00</modifiedDatetime> 
    <metaData> 
      <metaDatum> 
        <name>meta1</name> 
        <value>whatever1b</value> 
        <createdDatetime>2010-04-15T15:48:09-04:00</createdDatetime> 
        <modifiedDatetime>2010-04-15T15:48:13-04:00</modifiedDatetime> 
      </metaDatum> 
      <metaDatum> 
        <name>meta3</name> 
        <value>whatever3</value> 
        <createdDatetime>2010-04-15T15:48:13-04:00</createdDatetime> 
        <modifiedDatetime>2010-04-15T15:48:13-04:00</modifiedDatetime> 
      </metaDatum> 
      <metaDatum> 
        <name>subarray</name> 
        <value>{"meta3":"whatever3"}</value> 
        <createdDatetime>2010-04-15T15:48:09-04:00</createdDatetime> 
        <modifiedDatetime>2010-04-15T15:48:09-04:00</modifiedDatetime> 
      </metaDatum> 
    </metaData> 
    <subscriptions> 
      <subscription id="005b1a3c-9a18-102d-83a2-86fc5ee048c5">

As you can see, simple key->value pairs are stored. If the value passed in is a complex variable, CG stores the value as json encode text. If the value passed in is an empty string, the data field will be ignored.

4. Updating Meta Data

If a subsequent call to edit the customer information includes a POST key that is already stored as meta data, the value will be updated.

5. Deleting Meta Data

If a subsequent call to edit the customer information includes a POST key that is already stored as meta data and the value is an empty string, the data field will be purged from CG.

6. Using Meta Data in Email Templates

Using meta data in email templates is a bit odd since the meta data doesn't exist yet and it's possible for some customers to be missing some meta data. For this reason, you must write a little extra code when you introduce meta data in a template. You essentially just need to check if the field exists before including it, otherwise, you'll get an error like this:

Line 30: Undefined index: metaData

Do like this and you shouldn't have a problem:

{if !empty($metaData.meta1)}
    {$metaData.meta1}
{/if}

7. Reasonable Use

We recognize the need for this meta data feature in a billing capacity. Please be reasonable in your use of the feature. If CG staff determines that the feature is being abused, you may be asked to scale back your use of the feature or your account may be canceled per the subscription agreement.

View Plans and Pricing   or   Get Started with CheddarGetter now →