ChartMogul Developer Hub

Welcome to the ChartMogul Developer Hub. You'll find comprehensive guides and documentation to help you start working with ChartMogul as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Adding custom attributes to ChartMogul

ChartMogul lets you add custom attributes to customers. You can filter your customers using these attributes, create customer segments based on their values, and track the metrics of these segments over time.

For example, you can send the name of the sales rep associated with each customer from your CRM to ChartMogul, and compare how the customers of each sales rep perform over time. Similarly, you could send marketing data like acquisition channel, customer success data such as NPS score, or any other data that you want to store in ChartMogul and segment your metrics on.

Add custom attributes using the API

You can add and edit custom attributes using the API. You can also edit existing custom attributes through the user interface, this can be useful for quick edits.

Using the API to add custom attributes to customers

There are three ways in which you can 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. This is useful when you import customers into ChartMogul from your own billing system, and want to include custom attributes about them.

curl -X POST "https://api.chartmogul.com/v1/customers" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_KEY \
     -H "Content-Type: application/json" \
     -d '{
          "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"}
    ]
  }
)
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"}
      ]
    }
  }, function (err, res){
    // asynchronously called
});
<?php

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:     dsUUID,
  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 after they have been created in ChartMogul using their ChartMogul UUID. This is useful when you want to add custom attributes on an ongoing basis from one or several data sources.

curl -X POST "https://api.chartmogul.com/v1/customers/cus_de305d54-75b4-431b-adb2-eb6b9e546012/attributes/custom" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_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"}
   ]
}, function (err, res) {
   // asynchronously called
});
<?php

$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 address instead of the ChartMogul UUID. This is useful when you only have a customer's email address, and not their ChartMogul UUID. For instance, with automated integration services like Zapier.

curl -X POST "https://api.chartmogul.com/v1/customers/attributes/custom" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_KEY \
     -H "Content-Type: application/json" \
     -d '{
          "email": "[email protected]",
          "custom": [
            {"type": "String", "key": "channel", "value": "Facebook"},
            {"type": "Integer", "key": "age", "value": 8, "source":"clearbit"}
          ]
         }'
customers = ChartMogul::Customer.search('[email protected]')
customers.each |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"}
   ]
}, function (err, res) {
   // asynchronously called
});
<?php

$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"}
        ]
    }
)

It's important to note that the custom attributes will be added to all customers that have the specified email address in your account.

What custom attributes can I send to ChartMogul?

As you can see in the examples above, each custom attribute requires three properties.

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

    • String - Accepts alphanumeric characters. Maximum of 255 characters allowed.
    • Integer - Accepts only numeric characters.
    • Decimal - Accepts floating point numbers.
    • Timestamp - In the ISO 8601 format.
    • Boolean - Can be one of TRUE, true, t, 1, FALSE, false, f, or 0.
  2. key- A string containing the name of the custom attribute. Accepts alphanumeric characters and underscores.

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

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

We hope these provides the flexibility for you to add any custom attribute you like to ChartMogul. Typically, adding Sales, Marketing and Customer Success information adds a lot of value to the operations of these organizations within a company. For example:

  • Marketing campaign
  • Account manager
  • NPS score
  • Total number of support requests
  • Cost of acquisition
  • Last active timestamp

What else can I do with custom attributes using the API?

You can update custom attribute values using the API. This is useful for attributes that change over time. For example, attributes like Total number of support requests and last active time can change over a customer's lifetime. You can use one of two ways to update such custom attributes.

Update custom attributes while updating a Customer

The endpoint to update a customer is useful when you have to update many fields on a customer including custom attributes.

curl -X PATCH "https://api.chartmogul.com/v1/customers/cus_ab223d54-75b4-431b-adb2-eb6b9e234571" \
       -u <token>:<secret> \
       -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!
var customerUuid = "cus_ab223d54-75b4-431b-adb2-eb6b9e234571";

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

ChartMogul.Customer.modify(config, customerUuid, data);
<?php

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 just the custom attributes of a specific customer

The endpoint to update custom attributes of a customer is useful when you only have to update custom attributes and nothing else about the customer.

curl -X PUT "https://api.chartmogul.com/v1/customers/cus_de305d54-75b4-431b-adb2-eb6b9e546012/attributes/custom" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_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"
   }
}, function (err, res) {
   // asynchronously called
});
<?php

$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"
        }
    }
)

You can also remove custom attributes from a customer if they are no longer relevant to that customer. If you want to remove an attribute from all customers altogether, you can use the Archive feature under Admin > Custom attributes.

There is no limit to the number of custom attributes you can add in ChartMogul so feel free to add as many as you need to gain insight into your customer metrics.

How can I segment my customers using the custom attributes?

Once you add custom attributes to your customers in ChartMogul, you can use them to filter and segment your customers. Learn how to use Segmentation in our help center.

If you are an Admin of your ChartMogul account, you can also manage your custom attributes within the app under Admin > Custom attributes.

Adding custom attributes to ChartMogul