Chargify is happy to introduce a new set of API endpoints called “Metafields” and “Metadata”. These endpoints allow you to store additional data with subscriptions and customers. For now the feature that is being described is an API-only endpoint but we do plan to extend them into our Admin UI and Hosted pages in the months to come. That being said, let’s dive into what metafields / metadata are and what they aren’t. An analogy that might help better understand how they work is this: metafields and metadata, combined, act as a key/value pair to represent your additional data. (Metafields being the key and metadata being their values.)

Let’s talk about what they are and their intention first. A metafield is scoped to a site (so you will have to define the wanted keys per site) and they belong to customers or subscriptions. Notice that I am referencing customer and subscription in their plural form here – this is very important. Let’s discover what that means by the use of an example.

Say you want to keep track of the shirt size for a monthly subscription – previously you would have had to keep all of this data in your system and then you would have to join Chargify subscription IDs to IDs in your system – what a mess. What you can do now is the following:

POST https://fancy-tees.chargify.com/subscriptions/metafields


{
 "metafields": { "name": "Shirt Size" }
}

This will create a metafield “Shirt Size” for subscriptions for the site “fancy-tees”. If you have a large amount of fields that you would wish to define you can do it in batch as well!

POST https://fancy-tees.chargify.com/subscriptions/metafields


{
 "metafields": [
     { "name": "Shirt Size" },
     { "name": "Shirt Color" }
   ]
}

This will define “Shirt Size” and “Shirt Color” for the site “fancy-tees”

You may be asking yourself, “Well, that’s great, but what can I do with it?” – well, that is where metadata comes in. Say you have a subscription with ID 42 and you would like to store the shirt size and shirt color for that subscription. This is how you would do that:

POST https://fancy-tees.chargify.com/subscriptions/42/metadata


{
 "metadata":[
     {
       "name": "Shirt Color",
       "value": "Chargify Green"
     },
     {
       "name": "Shirt Size",
       "value": "Large"
     }
  ]
}

Now for subscription 42 you can fetch the same data with the API call:

GET https://fancy-tees.chargify.com/subscriptions/42/metadata

Another thing to note: If a metadata item named “A special field” doesn’t exist and you go to create a metadata item with that name for a subscription – it will create the metafield for you. This is out of convenience to allow mass imports of data. Please be aware that if you misspell a key name it will create it. Luckily, you can rename and delete fields and data easily!

This all being said, I urge you to read the documentation (http://docs.chargify.com/api-metafields and http://docs.chargify.com/api-metadata)

Now I would like to take a moment and talk about what metafields and metadata are not. Our plan is to keep the interface for metafields and metadata simple and fast. To do that we have designed these endpoints to be searched by “name” and not by “value”. It is your job to fetch this data and filter it to your heart’s content. We do not intend to create a metafield/metadata query syntax – as cool as that would be, it doesn’t really fit with what we are trying to achieve with this feature. If you need to do complex queries or create general purpose datasets, we urge you to store additional data in a database of your own and optimize your queries there. Another thing to note is that there are limits: each resource may have up to 200 metafield names, and each metadata value may contain up to 2kB. Please keep that in mind when using these endpoints.

To summarize, metafields and metadata are not intended to be a general-purpose datastore; instead they are a way to keep important additional data close to subscription and customer records. We hope you enjoy this additional set of endpoints – we are very excited about it! As we roll out the additional features revolving around metadata and metafields, we will be sure to let you know.

Hope you enjoy!