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 Cheddar 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 Cheddar 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, Cheddar stores the value as json encoded 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 Cheddar.

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}

Nested Meta Data

If a datum value is a complex type, Cheddar converts it to json for you when it's stored. You may, of course, alternatively set that value as a valid json string. When the complex value is assigned to your templates, all of the nesting in your complex value becomes native to the template. For example, with key named components with this json value:

[
    {
        "Component": "Toothbrushes",
        "Toothbrushes": [
            {
                "Size": "small",
                "Color": "lavender"
            },
            {
                "Size": "medium",
                "Color": "blue"
            }
        ]
    }
]

... in the template, you will have an embedded variable called $metaData.components which is an array type. You can then use it like any other array:

{if !empty($metaData.components)}
    {foreach from=$metaData.components item="component"}
        {$component.Component}<br>
        <ul>
            {foreach from=$component.{$component.Component} item="nested"}
                <li>
                    {$nested.Size}, {$nested.Color}
                </li>
            {/foreach}
        </ul>
    {/foreach}
{/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 Cheddar 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 Cheddar now →