Adding custom attributes

ChartMogul allows you to add custom attributes to customers, contacts, subscriptions, and opportunities using our API.

Custom attributes can be used with filtering, search, and segmentation. For example, a customer's last login, the marketing campaign used to acquire them or the name of their account manager.

There is no limit to the number of custom attributes you can add.

You can add and edit custom attributes using the API. For quick edits, update custom attributes using the app interface.

Here's what we cover in this tutorial:

Adding custom attributes to customers

There are three ways to add custom attributes to customers using the API:

1. Add custom attributes when creating the customer

The Create a Customer endpoint allows you to include custom attributes when importing customers into ChartMogul.

curl -X POST "https://api.chartmogul.com/v1/customers" \
     -u YOUR_API_KEY: \
     -H "Content-Type: application/json" \
     -d '{
            "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
            "external_id": "cus_0001",
            "name": "Adam Smith",
            "attributes": {
              "tags": ["important", "Prio1"],
              "custom": [
                {"type": "String", "key": "channel", "value": "Facebook", "source": "integration"},
                {"type": "Integer", "key": "age", "value": 18}
              ]
            }
        }'
ChartMogul::Customer.create!(
  data_source_uuid: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  external_id: "cus_0001",
  name: "Adam Smith",
  attributes: {
    custom: [
      { type: "String", key: "channel", value: "Facebook" },
      { type: "Integer", key: "age", value: 18, source: "clearbit" },
    ],
  },
)
ChartMogul.Customer.create(config, {
  data_source_uuid: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  external_id: "cus_0001",
  name: "Adam Smith",
  attributes: {
    custom: [
      { type: "String", key: "channel", value: "Facebook" },
      { type: "Integer", key: "age", value: 18, source: "clearbit" },
    ],
  },
});
ChartMogul\Customer::create([
  "data_source_uuid" => "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  "external_id" => "cus_0001",
  "name" => "Adam Smith",
  "attributes" => [
    "custom" => [
      ["type" => "String", "key" => "channel", "value" => "Facebook"],
      ["type" => "Integer", "key" => "age", "value" => 18, "source" => "clearbit"]
    ]
  ]
]);
api.CreateCustomer(&cm.NewCustomer{
  DataSourceUUID:     "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  ExternalID:         "cus_0001",
  Name:               "Adam Smith",
  Email:              "[email protected]",
  Country:            "US",
  City:               "New York",
  LeadCreatedAt:      "2015-10-14",
  FreeTrialStartedAt: "2015-11-01",
  Attributes: &cm.NewAttributes{
    Tags: []string{"important", "Prio1"},
    Custom: []*cm.CustomAttribute{
      {Key: "channel", Value: "Facebook", Type: "String"},
      {Key: "age", Value: 18, Type: "Integer", Source: "clearbit"},
    },
  },
})
ChartMogul.Customer.create(
  config,
  data={
    "data_source_uuid": "ds_9bb53a1e-edfd-11e6-bf83-af49e978cb11",
    "external_id": "cus_0001",
    "name": "Adam Smith",
    "attributes": {
      "custom": [
        {"type": "String", "key": "channel", "value": "Facebook"},
        {"type": "Integer", "key": "age", "value": 18, "source": "clearbit"},
      ]
    },
  },
)

2. Add custom attributes to an existing customer using their UUID

You can add custom attributes to a customer using their ChartMogul UUID once they have a customer record in ChartMogul. This is useful when you want to add custom attributes on an ongoing basis from one or several sources.

curl -X POST "https://api.chartmogul.com/v1/customers/cus_de305d54-75b4-431b-adb2-eb6b9e546012/attributes/custom" \
     -u YOUR_API_KEY: \
     -H "Content-Type: application/json" \
     -d '{
            "custom": [
              {"type": "String", "key": "channel", "value": "Facebook"},
              {"type": "Integer", "key": "age", "value": 8, "source": "clearbit"}
            ]
         }'
customer = ChartMogul::Customer.retrieve("cus_de305d54-75b4-431b-adb2-eb6b9e546012")
customer.add_custom_attributes!(
  { type: "String", key: "channel", value: "Facebook" },
  { type: "Integer", key: "age", value: 8, source: "clearbit" }
)
ChartMogul.CustomAttribute.add(
  config,
  "cus_de305d54-75b4-431b-adb2-eb6b9e546012",
  {
    custom: [
      { type: "String", key: "channel", value: "Facebook" },
      { type: "Integer", key: "age", value: 8, source: "clearbit" },
    ],
  }
);
$customer = ChartMogul\Customer::retrieve("cus_de305d54-75b4-431b-adb2-eb6b9e546012");

$custom = $customer->addCustomAttributes(
  ["type" => "String", "key" => "channel", "value" => "Facebook"],
  ["type" => "Integer", "key" => "age", "value" => 8, "source" => "clearbit"]
);
api.AddCustomAttributesToCustomer("cus_ec341fd8-ee01-11e6-b78e-9b6f6124979f",
  []*cm.CustomAttribute{
    &cm.CustomAttribute{
      Type:  "String",
      Key:   "channel",
      Value: "Facebook"},
    &cm.CustomAttribute{
      Type:   "Integer",
      Key:    "CAC",
      Value:  8,
      Source: "clearbit"},
  },
)
chartmogul.CustomAttributes.add(
  config,
  uuid="cus_c0dc8d74-edfd-11e6-a357-832dddba822f",
  data={
    "custom": [
      {"type": "String", "key": "channel", "value": "Facebook"},
      {"type": "Integer", "key": "CAC", "value": 8, "source": "clearbit"}
    ]
  }
)

3. Add custom attributes to existing customers using their email

You can also add custom attributes to customers with a specific email. This is useful when you only have a customer's email address, and not their ChartMogul UUID. For instance, customers imported using Zapier.

Custom attributes are added to all customers that have the specified email address in your account.

curl -X POST "https://api.chartmogul.com/v1/customers/cus_de305d54-75b4-431b-adb2-eb6b9e546012/attributes/custom" \
     -u YOUR_API_KEY: \
     -H "Content-Type: application/json" \
     -d '{
            "custom": [
              {"type": "String", "key": "channel", "value": "Facebook"},
              {"type": "Integer", "key": "age", "value": 8, "source": "clearbit"}
            ]
         }'
customers = ChartMogul::Customer.search("[email protected]")
customers.each do |c|
  c.add_custom_attributes!(
    { type: "String", key: "channel", value: "Facebook" },
    { type: "Integer", key: "age", value: 8, source: "clearbit" }
  )
end
ChartMogul.CustomAttribute.add(config, {
  email: "[email protected]",
  custom: [
    { type: "String", key: "channel", value: "Facebook" },
    { type: "Integer", key: "age", value: 8, source: "clearbit" },
  ],
});
$customers = ChartMogul\Customer::search("[email protected]");

foreach ($customers->entries as $customer) {
  $customer->addCustomAttributes(
    ["type" => "String", "key" => "channel", "value" => "Facebook"],
    ["type" => "Integer", "key" => "age", "value" => 8, "source" => "clearbit"]
  );
}
api.AddCustomAttributesWithEmail("[email protected]",
  []*cm.CustomAttribute{
    &cm.CustomAttribute{
      Type:  "String",
      Key:   "channel",
      Value: "Facebook"},
    &cm.CustomAttribute{
      Type:   "Integer",
      Key:    "CAC",
      Value:  8,
      Source: "clearbit"},
  },
)
chartmogul.CustomAttributes.add(
  config,
  data={
    "email": "[email protected]",
    "custom": [
      {"type": "String", "key": "channel", "value": "Facebook"},
      {"type": "Integer", "key": "CAC", "value": 8, "source": "clearbit"},
    ],
  },
)

Adding custom attributes to contacts

Add custom attributes when creating the contact

The Create a Contact endpoint allows you to include custom attributes when importing contacts to ChartMogul.

curl -X POST "https://api.chartmogul.com/v1/contacts" \
     -u YOUR_API_KEY: \
     -H "Content-Type: application/json" \
     -d '{
            "customer_uuid": "cus_00000000-0000-0000-0000-000000000000",
            "data_source_uuid": "ds_00000000-0000-0000-0000-000000000000",
            "first_name": "Adam",
            "last_name": "Smith",
            "position": 9,
            "title": "CEO",
            "email": "[email protected]",
            "phone": "+1234567890",
            "linked_in": "https://linkedin.com/linkedin",
            "twitter": "https://twitter.com/twitter",
            "notes": "Heading\nBody\nFooter",
            "custom": [
              { "key": "Facebook", "value": "https://www.facebook.com/adam.smith" },
              { "key": "date_of_birth", "value": "1985-01-22" }
            ]
         }'

Adding custom attributes to subscriptions and opportunities

Custom attributes are also supported on subscriptions and opportunities. See the API reference for the full request and response formats.

Subscriptions

Use the Add Custom Attributes to a Subscription endpoint to add custom attributes to an existing subscription. Each attribute takes the same type, key, and value properties as customer custom attributes. Retrieve a subscription's UUID using the List Customer Subscriptions endpoint.

Subscription custom attributes can also be added to subscription sets. Set-level attributes are inherited by all subscriptions in the set and persist when subscriptions change, for example on a plan switch.

Opportunities

Include custom attributes in the custom array when creating an opportunity or updating an opportunity. As with contacts, each attribute takes only a key and value, and the key must match an attribute defined under Settings > Custom Attributes > Opportunities.

Which custom attributes can I send to ChartMogul?

Add sales, marketing, and customer success data, such as:

Each custom attribute has three required properties:

type – A string indicating the data type of the custom attribute. Can be one of String, Integer, Decimal, Timestamp, or Boolean.

key – A string containing the name of the custom attribute. Accepts alphanumeric characters and underscores.

value – The value of the custom attribute. Should be of the data type and allowed values as specified above under type.

source – The source of the attribute data. This is an optional parameter for use in the UI. It can be updated, but doesn't appear in the response.

How do I update custom attributes using the API?

You can update custom attributes for customers, contacts, subscriptions, and opportunities using the API. This is useful when attributes change over time such as Total number of support requests or last active time.

Update custom attributes while updating a customer

The endpoint to update a customer is useful when you need to update many customer fields, including their custom attributes.

curl -X PATCH "https://api.chartmogul.com/v1/customers/cus_ab223d54-75b4-431b-adb2-eb6b9e234571" \
     -u YOUR_API_KEY: \
     -H  "Content-Type: application/json" \
     -d '{
            "state": "CA",
            "attributes": {
              "tags": ["high-value"],
              "custom": {
                "CAC": 25
              }
            }
        }'
customer = ChartMogul::Customer.retrieve("cus_ab223d54-75b4-431b-adb2-eb6b9e234571")

customer.state = "CA"

customer.attributes[:tags] = ["high-value"]

customer.attributes[:custom] = { "CAC": 25 }

customer.update!
const customerUuid = "cus_ab223d54-75b4-431b-adb2-eb6b9e234571";

const data = {
  state: "CA",
  attributes: {
    tags: ["high-value"],
    custom: {
      CAC: 25,
    },
  },
};

ChartMogul.Customer.modify(config, customerUuid, data);
ChartMogul\Customer::update(
  ["customer_uuid" => "cus_ab223d54-75b4-431b-adb2-eb6b9e234571"],
  [
    "state" => "CA",
    "attributes" => [
      "tags" => ["high-value"],
      "custom" => ["CAC" => 25]
    ]
  ]
);
api.UpdateCustomer(&cm.Customer{
  State: "CA",
  Attributes: &cm.Attributes{
    Tags: []string{"high-value"},
    Custom: map[string]interface{}{
      "CAC": 25,
    },
  },
}, "cus_ab223d54-75b4-431b-adb2-eb6b9e234571")
chartmogul.Customer.modify(
  config,
  uuid="cus_ab223d54-75b4-431b-adb2-eb6b9e234571",
  data={
    "state": "CA",
    "attributes": {
      "tags": ["high-value"],
      "custom": {"CAC": 25}
    }
  },
)

Update custom attributes for a specific customer

The endpoint to update custom attributes of a customer is useful when you only need to update custom attributes and keep all other customer data the same.

curl -X PUT "https://api.chartmogul.com/v1/customers/cus_de305d54-75b4-431b-adb2-eb6b9e546012/attributes/custom" \
     -u YOUR_API_KEY: \
     -H "Content-Type: application/json" \
     -d '{
            "custom":{
              "pro": true,
              "channel": "Twitter"
            }
         }'
customer = ChartMogul::Customer.retrieve("cus_de305d54-75b4-431b-adb2-eb6b9e546012")

customer.update_custom_attributes!(
  pro: true,
  channel: "Twitter",
)
ChartMogul.CustomAttribute.update(
  config,
  "cus_de305d54-75b4-431b-adb2-eb6b9e546012",
  {
    custom: {
      pro: true,
      channel: "Twitter",
    },
  }
);
$customer = ChartMogul\Customer::retrieve("cus_de305d54-75b4-431b-adb2-eb6b9e546012");

$customer->updateCustomAttributes(
  ["channel" => "Twitter"],
  ["pro" => true]
);
api.UpdateCustomAttributesOfCustomer(
  "cus_c0dc8d74-edfd-11e6-a357-832dddba822f",
  map[string]interface{}{
    "channel": "Twitter",
  },
)
chartmogul.CustomAttributes.update(
  config,
  uuid="cus_c0dc8d74-edfd-11e6-a357-832dddba822f",
  data={
    "custom": {
      "channel": "Twitter"
    }
  },
)

Update custom attributes while updating a contact

The Update a Contact endpoint allows you to include custom attributes when updating contacts in ChartMogul.

curl -X PATCH "https://api.chartmogul.com/v1/contacts/con_00000000-0000-0000-0000-000000000000" \
     -u YOUR_API_KEY: \
     -H "Content-Type: application/json" \
     -d '{
            "customer_external_id": "customer_002",
            "first_name": "Bill",
            "last_name": "Thompson",
            "position": 10,
            "title": "CTO",
            "email": "[email protected]",
            "phone": "+987654321",
            "linked_in": "https://linkedin.com/bill-linkedin",
            "twitter": "https://twitter.com/bill-twitter",
            "notes": "New Heading\nNew Body\nNew Footer",
            "custom": [
              { "key": "Facebook", "value": "https://www.facebook.com/bill.thompson" },
              { "key": "date_of_birth", "value": "1990-01-01" }
            ]
         }'

Update custom attributes of a subscription or opportunity

Use the Update Custom Attributes of a Subscription endpoint to change attribute values on a subscription or subscription set. For opportunities, pass the updated custom array to the Update an Opportunity endpoint.

It's also possible to remove custom attributes from a customer or subscription if they are no longer relevant.

To remove an attribute from all customers, archive it by navigating in-app to Settings > Custom Attributes.

How do I segment my customers using custom attributes?

Once you add custom attributes to your customers, you can use them for filtering, segmentation, and search. Learn more about segmentation.

If you're an Admin in ChartMogul account, manage custom attributes by navigating to Settings > Custom Attributes.