This documentation site is deprecated. The latest up-to-date API reference is available at https://reference.chargify.com.
This site will remain available for historical reference until June 1, 2017

API: Metadata (Custom Field Data)

Chargify Metadata is used to add your own meaningful values to subscription or customer records.
Metadata is associated to a customer or subscription, and corresponds to a Metafield. When creating a new metadata object for a given record, if the metafield is not present it will be created.

Metadata values are limited to 2kB in size. Additonally, there are limits on the number of unique “names” available per resource. See Metafields documentation.

The following fields are returned from GET (read) operations.

  • name – The name of the attribute that is added to the resource.
  • value – The value of the attribute that was added to the resource
  • resource_id – The resource id that the metadata belongs to

Methods

note: <resource> applies to subscriptions and customers only at this time.

List

URL: https://<subdomain>.chargify.com/<resource>/metadata.<format>
Method: GET
Formats: JSON, XML
Optional Parameters: name – value must be an exact match of what you named your metafield previously
Response: An array of Metadata

Here’s an example metadata list response in JSON:

{
  "total_count": 1,
  "current_page": 1,
  "total_pages": 1,
  "per_page": 20,
  "metadata": [
    {
      "resource_id": 100000,
      "name": "Shirt Size"
      "value": "L"
    },
    {
      "resource_id": 100004,
      "name": "Shirt Size"
      "value": "S"
    },
    {
      "resource_id": 100000,
      "name": "Color",
      "value": "Blue"
    }    
  ]
}

And an example in XML:

<?xml version="1.0" encoding="UTF-8"?>
<results>
  <total-count type="integer">2</total-count>
  <current-page type="integer">1</current-page>
  <total-pages type="integer">1</total-pages>
  <per-page type="integer">20</per-page>
  <metadata type="array">
    <metadatum>
      <resource-id type="integer">11592482</resource-id>
      <value>large</value>
      <name>Size</name>
    </metadatum>
    <metadatum>
      <resource-id type="integer">11592482</resource-id>
      <value>blue</value>
      <name>Color</name>
    </metadatum>
  </metadata>
</results>

Read/Show

URL: https://<subdomain>.chargify.com/<resource>/<resource_id>/metadata.<format>
Method: GET
Formats: JSON, XML
Optional Parameters: name – If provided, returns only the metadata which match the field name.
Response: An array of Metadata

Here’s an example metadata show response:

{
  "total_count": 1,
  "current_page": 1,
  "total_pages": 1,
  "per_page": 20,
  "metadata": [
    {
      "resource_id": 100000,
      "name": "Shirt Size"
      "value": "L"
    },
    {
      "resource_id": 100000,
      "name": "Color",
      "value": "Blue"
    }    
  ]
}

Create / Update

URL: https://<subdomain>.chargify.com/<resource>/<resource_id>/metadata.<format>
Method: POST / PUT
Formats: JSON, XML
Parameters: name, value – can be a single item or a list of metadata
Optional Parameters: current_name – This only applies when you are updating an existing record and you wish to rename the field. Note you must supply name and current_name to rename the field
Response: An array of Metadata

Here’s an example metadata create request:

  { 
    "metadata": {
      "name": "Color",
      "value": "Blue"
    } 
  }

Create a multipe metadata in one request:

  {
    "metadata": [
      {"name": "Color", "value": "Blue"},
      {"name": "Something", "value": "Useful"}
    ]
  }

Say a record with the name “Color” exists and you wish to rename it to “Shirt Color” below is an example request:

  {
    "metadata": {
      "current_name": "Color", "name": "Shirt Color", "value": "Blue"
    }
  }

Here’s an example metadata create response:

[
    {
        "name": "Color",
        "resource_id": 100000,
        "value": "Blue"
    },
    {
        "name": "Something",
        "resource_id": 100000,
        "value": "Useful"
    }
]

Delete

URL: https://<subdomain>.chargify.com/<resource>/<resource_id>/metadata.<format>?name=<name>
Method: DELETE
Formats: JSON, XML
Query Parameter: name
Response: blank use response code 200 for successful, and 404 for unsuccessful

For instance if you wanted to delete the metadata for customer 99 named weight you would do:

https://my-subdomain.chargify.com/customers/99/metadata.json?name=weight

Pagination

Results are paginated and return 30 responses per page. Get additional pages by passing a `page` parameter:

https://[@subdomain].chargify.com/subscriptions/99/metadata.json?page=3