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

API: Metafields (Custom Fields)

Chargify Metafields are used to add meaningful attributes to subscription and customer resources.
Metafield are the place where you will set up your resource to accept additional data. It is scoped to the site instead of a specific customer or subscription. Think of it as the key, and Metadata as the value on every record.

It is possible to create Metafields “on the fly” when you create your Metadata – if a non-existant name is passed when creating Metadata, a Metafield for that key will be automatically created. The Metafield API, however, gives you more control over your “keys”.

Metafield Limitations: Each site is limited to 200 unique Metafields (i.e. keys, or names) per-resource.

The following fields are returned from GET operations.

  • name – The name of the attribute that is added to the resource.
  • scope – This specifies where the metafield / metadata will visible
  • data_count – The number of metadata that are associated to this metafield.


For brevity sake in all example urls going forward <resource> can be either subscriptions or customers.


The scope field has four acceptable attributes: hosted, csv, invoices, and statements. If configured in the Admin UI or via the API be careful sending updates to metafields with the scope attribute – if a partial update is sent it will overwrite the current configuration.


The hosted field is an array of products which specifies which hosted pages that the metafield will appear on.
Supports a special value of “all” if you would like the field to be present on all hosted pages.

“hosted”: [“1”, “2”]
“hosted”: [“all”]


Can be “1” or “0” to include or exclude in csv exports.

“csv”: “1”


Can be “1” or “0” to include or exclude metadata on statements.

“statements”: “1”


Can be “1” or “0” to include or exclude metadata on invoices.

“invoices”: “1”

URL: https://<subdomain><resource>/metafields.<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 Metafields

Here’s an example metafield list response:

  "total_count": 1,
  "current_page": 1,
  "total_pages": 1,
  "per_page": 20,
  "metafields": [
        "name": "Shirt Size",
        "scope": {"hosted": ["all"], csv: "1", invoices: "1", statements: "1"},
        "data_count": 99


URL: https://<subdomain><resource>/metafields.<format>
Method: POST/PUT
Formats: JSON, XML
Parameters: name
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 Metafields

Here’s an example metafields create request:

    "metafields": {
      "name": "Color",
      "scope": {"hosted": ["1", "2", "3"], csv: "0", invoices: "1", statements: "1"}

Create a multipe metafields in one request:

    "metafields": [
      {"name": "Color"},
      {"name": "Brand"}

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

    "metafields": {
      "current_name": "Pant Style", "name": "Style"


URL: https://<subdomain><resource>/metafields.<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 metafield for customers named strength you would do:


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