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    
Suggest Edits

Introduction to the Import API

The Import API allows any subscription business (or subscription billing platform) to connect with ChartMogul and leverage the powerful analytics that we deliver.

 

For a step-by-step guide to integrating with this API, you can follow this tutorial.

Suggest Edits

Endpoint Overview

 
Endpoint
Description

Creates a data_source object for importing data into ChartMogul.

Retrieves a data_source object from your ChartMogul account.

Deletes the specified data_source object and all its associated data.

Lists all data_source objects in your ChartMogul account.

Creates a customer object in ChartMogul under the specified data_source.

Retrieves a customer object from your ChartMogul account.

Updates certain modifiable attributes of a customer object in your ChartMogul account.

Deletes the specified customer object that was created using the Import API, and all its associated data.

Lists all customer objects in your ChartMogul account.

Creates a plan object in ChartMogul under the specified data_source.

Retrieves a plan object from your ChartMogul account.

Updates a plan object in your ChartMogul account.

Deletes a plan object from your ChartMogul account.

Returns a list of plan objects in your ChartMogul account.

Creates invoices for a given API customer. ChartMogul auto-generates subscription objects from these invoices.

Returns a list of invoice objects for a given customer.

Returns a list of invoice objects created using the API in your ChartMogul account.

Creates a transaction object for an invoice imported using the Import API.

Returns a list of subscription objects for a given customer. Subscriptions are auto-generated from invoice objects created using the Import API.

Cancels a subscription that was generated from an imported invoice.

Suggest Edits

Data Sources

Data sources represent sources of billing data for your ChartMogul account.

 

If you bill your customers using different systems, then you would want to create a separate data_source object for each system.

Suggest Edits

Create a Data Source

Creates a data_source object for importing data into ChartMogul.

 
posthttps://api.chartmogul.com/v1/data_sources

Form Data

name
string
required

A unique name for this source of customer billing data. eg. Our billing system

 

In the response, the JSON object contains the following data:

  • uuid - The UUID of the data_source object generated by ChartMogul.
  • name - The unique name of the data source as specified by you.
  • system - The type of system from which customer billing data is imported using this data source. For example, Stripe, Recurly, GoCardless, Chargify, Import API, and so on.
  • created_at - The time when this data source was created in the ChartMogul system.
  • status - The current status of the data import into ChartMogul. For data sources based on our native integrations (ie. Stripe, Braintree, etc.), if there is no data then status will be never_imported. If there is data that is being processed then status will be importing. If all data has been processed then status will be import_complete. For data sources based on our Import API, if data is currently being processed then status will be working and if there's no data being processed then status will be idle.

Creating data sources for native integrations

You can create data sources for our native integrations, ie. Stripe, Braintree, Recurly, Chargify and PayPal, directly within your ChartMogul account at Admin > Data load. You can use this endpoint only to create data sources that are based on our Import API.

Examples

curl -X POST "https://api.chartmogul.com/v1/data_sources" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_KEY \
     -H "Content-Type: application/json" \
     -d '{ 
          "name": "In-house billing"
         }'
ChartMogul::DataSource.create!(
  name: 'In-house billing'
)
ChartMogul.DataSource.create(config, {
   "name": "In-house billing"
}, function(err, res) {
   // asynchronously called
});
<?php

ChartMogul\DataSource::create([
    "name" => "In-house billing"
]);
?>
api.CreateDataSource("In-house billing")
chartmogul.DataSource.create(config, data={
    "name": "In-house billing"
})

Result Format

{
    "uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
    "name": "In-house billing",
    "system": "Import API",
    "created_at": "2016-01-10T15:34:05Z",
    "status": "idle"
}
#<ChartMogul::DataSource:0x007ff9f127d628 
@name="In-house billing", 
@uuid="ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
@system="Import API",
@status="idle", 
@created_at=2016-06-27 11:27:37 UTC
>
{
    "uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
    "name": "In-house billing",
    "system": "Import API",
    "created_at": "2016-01-10T15:34:05Z",
    "status": "idle"
}
ChartMogul\DataSource::__set_state(array(
   "uuid" => "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
   "status" => "idle",
   "system" => "Import API",
   "created_at" => "2016-12-27T07:55:08.585Z",
   "name" => "In-house billing"
));
(*chartmogul.DataSource)(0xc042048380)({
 UUID: (string) (len=39) "ds_d051800c-edf8-11e6-9a33-03ed88a413a7",
 Name: (string) (len=16) "In-house billing",
 CreatedAt: (string) (len=24) "2017-02-08T12:19:18.346Z",
 Status: (string) (len=4) "idle",
 System: (string) (len=10) "Import API"
})
<DataSource{
  created_at=datetime.datetime(2017, 2, 8, 11, 50, 40),
  name='abc',
  status='idle',
  uuid='ds_d0235fc8-edf4-11e6-af62-0b4bbe8d71a4',
  system='Import API'}>
Suggest Edits

Retrieve a Data Source

Retrieves a data_source object from your ChartMogul account.

 
gethttps://api.chartmogul.com/v1/data_sources/DATA_SOURCE_UUID

Path Params

data_source_uuid
string
required

The ChartMogul UUID of the data source to be retrieved.

 

In the response, data_sources contains an array of data_source objects that you've created, with the following data:

  • uuid - The UUID of the data_source object generated by ChartMogul.
  • name - The name of the data source as specified by you.
  • system - The type of system from which customer billing data is imported using this data source. For example, Stripe, Recurly, GoCardless, Chargify, Import API, and so on.
  • created_at - The time when this data source was created in the ChartMogul system.
  • status - The current status of the data import into ChartMogul. For data sources based on our native integrations (ie. Stripe, Braintree, etc.), if there is no data then status will be never_imported. If there is data that is being processed then status will be importing. If all data has been processed then status will be import_complete. For data sources based on our Import API, if data is currently being processed then status will be working and if there's no data being processed then status will be idle.

Examples

curl -X GET "https://api.chartmogul.com/v1/data_sources/ds_fef05d54-47b4-431b-aed2-eb6b9e545430" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_KEY \
     -H "Content-Type: application/json"
ChartMogul::DataSource.retrieve(
  uuid: 'ds_fef05d54-47b4-431b-aed2-eb6b9e545430'
)
ChartMogul.DataSource.retrieve(config, "ds_fef05d54-47b4-431b-aed2-eb6b9e545430", function(err, res) {
   // asynchronously called
});
<?php

ChartMogul\DataSource::retrieve("ds_fef05d54-47b4-431b-aed2-eb6b9e545430");
?>
api.RetrieveDataSource("ds_fef05d54-47b4-431b-aed2-eb6b9e545430")
chartmogul.DataSource.retrieve(config, uuid='ds_fef05d54-47b4-431b-aed2-eb6b9e545430')

Result Format

{
  "uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  "name": "In-house billing",
  "system": "Import API",
  "created_at": "2016-01-10 15:34:05",
  "status": "idle"
}
#<ChartMogul::DataSource:0x007ff9f127d628 
@uuid="ds_fef05d54-47b4-431b-aed2-eb6b9e545430", 
@name="In-house billing", 
@system="Import API",
@status="idle", 
@created_at=2016-06-27 11:27:37 UTC
>
{
  "uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  "name": "In-house billing",
  "system": "Import API",
  "created_at": "2016-01-10 15:34:05",
  "status": "idle"
}
ChartMogul\DataSource::__set_state(array(
   "uuid" => "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
   "status" => "idle",
   "system" => "Import API",
   "created_at" => "2016-12-27T07:55:08.585Z",
   "name" => "In-house billing"
));
(*chartmogul.DataSource)(0xc042048380)({
 UUID: (string) (len=39) "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
 Name: (string) (len=16) "In-house billing",
 CreatedAt: (string) (len=24) "2017-02-08T12:19:18.346Z",
 Status: (string) (len=4) "idle",
 System: (string) (len=10) "Import API"
})
<DataSource{
  created_at=datetime.datetime(2017, 2, 8, 11, 50, 40),
  name='abc',
  status='idle',
  uuid='ds_fef05d54-47b4-431b-aed2-eb6b9e545430',
  system='Import API'}>
Suggest Edits

Delete a Data Source

Deletes the specified data_source object and all its associated data.

 
deletehttps://api.chartmogul.com/v1/data_sources/DATA_SOURCE_UUID

Path Params

data_source_uuid
string
required

The ChartMogul UUID of the data source that needs to be deleted.

 

Impact of this action

This request will permanently delete the specified data source and all associated data. Data deleted includes all the customers, plans, customer's invoices, subscriptions, transactions and any customer attributes created under this data source. This action cannot be undone.

Examples

curl -X DELETE "https://api.chartmogul.com/v1/data_sources/ds_ade45e52-47a4-231a-1ed2-eb6b9e541213" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_KEY
data_sources = ChartMogul::DataSource.all
ds = data_sources.last
ds.destroy!
ChartMogul.DataSource.destroy(config, "ds_ade45e52-47a4-231a-1ed2-eb6b9e541213", function (err, res) {
   // aysnchronously called
});
<?php

ChartMogul\DataSource::all()->last()->destroy();
?>
api.DeleteDataSource("ds_ade45e52-47a4-231a-1ed2-eb6b9e541213")
chartmogul.DataSource.destroy(config, uuid='ds_dc5e3618-edfa-11e6-9e29-f709b6341791')

Result Format

{ }
true
{ }
true
nil
None
Suggest Edits

List Data Sources

Lists all data_source objects in your ChartMogul account.

 
gethttps://api.chartmogul.com/v1/data_sources

Query Params

name
string

The name of the data source. eg. My data source

system
string

The type of system of the data sources. For example, Stripe, Recurly, Chargify, or Import API.

 

In the response, data_sources contains an array of data_source objects that you've created, with the following data:

  • uuid - The UUID of the data_source object generated by ChartMogul.
  • name - The name of the data source as specified by you.
  • system - The type of system from which customer billing data is imported using this data source. For example, Stripe, Recurly, GoCardless, Chargify, Import API, and so on.
  • created_at - The time when this data source was created in the ChartMogul system.
  • status - The current status of the data import into ChartMogul. For data sources based on our native integrations (ie. Stripe, Braintree, etc.), if there is no data then status will be never_imported. If there is data that is being processed then status will be importing. If all data has been processed then status will be import_complete. For data sources based on our Import API, if data is currently being processed then status will be working and if there's no data being processed then status will be idle.

Examples

curl -X GET "https://api.chartmogul.com/v1/data_sources" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_KEY
ChartMogul::DataSource.all
ChartMogul.DataSource.all(config, function (err, res) {
   // asynchronously called
});
<?php

ChartMogul\DataSource::all();
?>
api.ListDataSources()
chartmogul.DataSource.all(config)

Result Format

{
  "data_sources": [
    {
      "uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
      "name": "In-house billing",
      "system": "Import API",
      "created_at": "2016-01-10 15:34:05",
      "status": "idle"
    },
    {
      "uuid": "ds_ade45e52-47a4-231a-1ed2-eb6b9e541213",
      "name": "Enterprise billing connection",
      "system": "Import API",
      "created_at": "2016-01-09 10:14:15",
      "status": "idle"
    }
  ]
}
#<ChartMogul::DataSources:0x00000003ed9d58
 @data_sources=[
  #<ChartMogul::DataSource:0x007ff9f237ba88
  @name="In-house billing", 
  @uuid="ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  @system="Import API",
  @status="idle", 
  @created_at=2016-01-10 15:34:05 UTC,
  >, 
  #<ChartMogul::DataSource:0x007ff9f2379b20 
  @name="Enterprise billing connection", 
  @uuid="ds_ade45e52-47a4-231a-1ed2-eb6b9e541213", 
  @system="Import API",
  @status="idle", 
  @created_at=2016-01-09 10:14:15 UTC
  >
]>
{
  "data_sources": [
    {
      "uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
      "name": "In-house billing",
      "system": "Import API",
      "created_at": "2016-01-10 15:34:05",
      "status": "idle"
    },
    {
      "uuid": "ds_ade45e52-47a4-231a-1ed2-eb6b9e541213",
      "name": "Enterprise billing connection",
      "system": "Import API",
      "created_at": "2016-01-09 10:14:15",
      "status": "idle"
    }
  ]
}
<?php

Doctrine\Common\Collections\ArrayCollection::__set_state(array(
   "elements" => 
  array (
    0 => 
    ChartMogul\DataSource::__set_state(array(
       "uuid" => "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
       "status" => "idle",
       "system" => "Import API",
       "created_at" => "2016-01-10 15:34:05",
       "name" => "In-house billing",
    )),
    1 => 
    ChartMogul\DataSource::__set_state(array(
       "uuid" => "ds_ade45e52-47a4-231a-1ed2-eb6b9e541213",
       "status" => "idle",
       "system" => "Import API",
       "created_at" => "2016-01-09 10:14:15",
       "name" => "Enterprise billing connection",
    ))
)));
?>
(*chartmogul.DataSources)(0xc0420c8ba0)({
 DataSources: ([]*chartmogul.DataSource) (len=1) {
  (*chartmogul.DataSource)(0xc042008440)({
   UUID: (string) (len=39) "ds_dc5e3618-edfa-11e6-9e29-f709b6341791",
   Name: (string) (len=16) "In-house billing",
   CreatedAt: (string) (len=24) "2017-02-08T12:33:57.571Z",
   Status: (string) (len=4) "idle",
   System: (string) (len=10) "Import API"
  })
 }
})
DataSources(data_sources=[
    <DataSource{created_at=datetime.datetime(2017, 2, 8, 12, 33, 57),
                name='In-house billing',
                status='idle',
                uuid='ds_dc5e3618-edfa-11e6-9e29-f709b6341791',
                system='Import API'}>
  	])
Suggest Edits

Customers

This object represents one of your customers in ChartMogul.

 

You can create customer objects for both paying and non-paying customers (e.g. leads, free trials, freemium users, etc.)

Suggest Edits

Create a Customer

Creates a customer object in ChartMogul under the specified data_source.

 
posthttps://api.chartmogul.com/v1/customers

Form Data

data_source_uuid
string
required

The ChartMogul UUID of the data source that this customer comes from.

external_id
string
required

A unique identifier specified by you for the customer. Typically an identifier from your internal system. Accepts alphanumeric characters.

name
string
required

Name of the customer for display purposes. Accepts alphanumeric characters.

email
string

Email address of the customer.

company
string

The customer's company or organisation.

country
string

Country code of customer's location as per ISO-3166 alpha-2 standard.

state
string

State code of customer's location as per ISO-3166 alpha-2 standard.

city
string

City of the customer's location.

zip
string

Zip code of the customer's location.

lead_created_at
date-time

Time at which this customer was established as a lead. Must be an ISO 8601 formatted time in the past. The timezone defaults to UTC unless otherwise specified.

free_trial_started_at
date-time

Time at which this customer started a free trial of your product or service. Must be an ISO 8601 formatted time in the past. The timezone defaults to UTC unless otherwise specified. This is expected to be the same as, or after the lead_created_at value.

attributes
object

A JSON object containing additional attributes of the customer in the form of tags and custom attributes as described below.

tags
array of strings

An Array of tags to be added to the customer.

custom
array

An Array containing the custom attributes to be added to the customer. If sending custom attributes, each custom attribute must have a type, key, and value as described below.

type
string

The data type of the custom attribute. Required for each custom attribute. Can be one of String, Integer, Decimal, Timestamp or Boolean.

key
string

The name of the custom attribute. Required for each custom attribute. Accepts alphanumeric characters and underscores.

value
mixed type

The value of the custom attribute. Required for each custom attribute. Should be of the data type as specified in type.

source
string

Optional parameter for UI use. Can be updated, doesn't show in response.

 

In the response, the JSON object contains the following data:

  • id - The internal ChartMogul ID of the customer object.
  • uuid - The UUID of the customer object generated by ChartMogul.
  • external_id - The unique external identifier for this customer, if any.
  • external_ids - An array containing the unique external identifiers of all customer records that have been merged into this customer.
  • data_source_uuid - The ChartMogul UUID of the data source of this customer.
  • data_source_uuids - An array containing the ChartMogul UUIDs of all data sources that contribute data to this customer. This is most relevant for merged customers.
  • name - The name of this customer.
  • email - This customer's email address.
  • company - This customer's company name.
  • status - The status of this customer. One of Lead, Active or Cancelled.
  • lead_created_at - The time at which this customer was established as a lead, as specified by you.
  • free_trial_started_at - The time at which this customer started a free trial of your product or service, as specified by you.
  • customer-since - An RFC3339 formatted datetime attribute indicating when the customer first started paying for a subscription.
  • country - The country from the customer's address.
  • state - The state from the customer's address.
  • city - The city from the customer's address.
  • zip - The zip code from the customer's address.
  • attributes - A JSON object representing this customer's attributes containing the following data:
    • tags - An Array of tags that you have added to this customer.
    • stripe - A JSON object representing any metadata on this customer object in your Stripe account.
    • clearbit - A JSON object representing publicly available information about this customer retrieved from Clearbit.
    • custom - A JSON object representing custom attributes that you have added to this customer.
  • address - A JSON object representing this customer's address containing the following data:
    • address_zip - The zip code from this customer's address.
    • city - The city from this customer's address.
    • state - The state from this customer's address.
    • country - The country code from this customer's address as per the ISO-3166 alpha-2 standard.
  • mrr - The current monthly recurring revenue for this customer, expressed in the currency selected for your account, as an integer number of cents. Divide by 100 to obtain the actual amount.
  • arr - The current annual run rate for this customer, also expressed as an integer number of cents in your account's selected currency.
  • billing-system-url - A URL for this customer's data in your billing system, if available.
  • chartmogul-url - The URL for this customer's ChartMogul page. This is only accessible to a user logged in to your ChartMogul account.
  • billing-system-type - The type of the billing system from where the customer was imported to ChartMogul. For example, Stripe, Recurly, Chargify, or Import API.
  • currency - The currency of the MRR readings for this customer.
  • currency-sign - Text representation to display the currency. E.g. $, or €.

Examples

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",
          "email": "[email protected]",
          "country": "US",
          "state": "NY",
          "city": "New York",
          "lead_created_at": "2015-10-14 00:00:00",
          "free_trial_started_at": "2015-11-01 00:00:00",
          "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",
  email: "[email protected]",
  country: "US",
  city: "New York",
  lead_created_at: Time.utc(2015, 10, 14),
  free_trial_started_at: Time.utc(2015, 11, 1),
  attributes: {
		tags: ["important", "Prio1"],
		custom: [
			{type: "String", key: "channel", value: "Facebook", source: "integration"},
			{type: "Integer", key: "age", value: 18}
		]
	}
)
ChartMogul.Customer.create(config, {
    "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
    "external_id": "cus_0001",
    "name": "Adam Smith",
    "email": "[email protected]",
    "country": "US",
    "city": "New York",
    "lead_created_at": "2015-10-14",
    "free_trial_started_at": "2015-11-01",
    "attributes": {
			"tags": ["important", "Prio1"],
			"custom": [
				{"type": "String", "key": "channel", "value": "Facebook", "source": "integration"},
				{"type": "Integer", "key": "age", "value": 18}
			]
     }
    }, 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",
    "email" => "[email protected]",
    "country" => "US",
    "city" => "New York",
    "lead_created_at" => "2015-10-14",
    "free_trial_started_at" => "2015-11-01",
		"attributes" => [
			"tags" => ["important", "Prio1"],
			"custom" => [
				["type" => "String", "key" => "channel", "value" => "Facebook", "source" => "integration"],
				["type" => "Integer", "key" => "age", "value" => 18]
			]
		]
]);
?>
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", Source: "integration"},
      {Key: "age", Value: 18, Type: "Integer"},
    }
  }})
ChartMogul.Customer.create(
    config,
    data={
        "data_source_uuid": "ds_9bb53a1e-edfd-11e6-bf83-af49e978cb11",
        "external_id": "cus_0001",
        "name": "Adam Smith",
        "email": "[email protected]",
        "country": "US",
        "city": "New York",
        "lead_created_at": "2015-10-14",
        "free_trial_started_at": "2015-11-01",
    		"attributes": {
					"tags": ["important", "Prio1"],
					"custom": [
						{"type": "String", "key": "channel", "value": "Facebook", "source": "integration"},
						{"type": "Integer", "key": "age", "value": 18}
					]
				}
    })

Result Format

{
  "id": 74596,
  "uuid": "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
  "external_id": "cus_0001",
  "name": "Adam Smith",
  "email": "[email protected]",
  "status": "Lead",
  "customer-since": null,
  "attributes": {
    "custom": {
      "channel": "Facebook",
      "age": 18
    },
    "clearbit": {},
    "stripe": {},
    "tags": [
      "important",
      "Prio1"
    ]
  },
  "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  "data_source_uuids": [
    "ds_fef05d54-47b4-431b-aed2-eb6b9e545430"
  ],
  "external_ids": [
    "cus_0001"
  ],
  "company": "",
  "country": "US",
  "state": null,
  "city": "New York",
  "zip": null,
  "lead_created_at": "2015-10-14T00:00:00Z",
  "free_trial_started_at": "2015-11-01T00:00:00Z",
  "address": {
    "country": "United States",
    "state": null,
    "city": "New York",
    "address_zip": null
  },
  "mrr": 0,
  "arr": 0,
  "billing-system-url": null,
  "chartmogul-url": "https://app.chartmogul.com/#customers/74596-Adam_Smith",
  "billing-system-type": "Import API",
  "currency": "USD",
  "currency-sign": "$"
}
#<ChartMogul::Customer:0x000000006615e8
 @address=
  {:country=>"United States",
   :state=>nil,
   :city=>"New York",
   :address_zip=>nil},
 @arr=0,
 @attributes=
  {:custom=>{:channel=>"Facebook", :age=>18},
   :clearbit=>{},
   :stripe=>{},
   :tags=>["important", "Prio1"]},
 @billing_system_type="Import API",
 @billing_system_url=nil,
 @chartmogul_url="https://app.chartmogul.com/#customers/6354002-Adam_Smith",
 @city="New York",
 @company="",
 @country="US",
 @currency="USD",
 @currency_sign="$",
 @customer_since=nil,
 @data_source_uuid="ds_e7d1b08e-0276-11e7-9af7-138812f19424",
 @data_source_uuids=["ds_e7d1b08e-0276-11e7-9af7-138812f19424"],
 @email="[email protected]",
 @external_id="cus_0001",
 @external_ids=["cus_0001"],
 @free_trial_started_at=2015-11-01 00:00:00 UTC,
 @id=6354002,
 @lead_created_at=2015-10-14 00:00:00 UTC,
 @mrr=0,
 @name="Adam Smith",
 @state=nil,
 @status="Lead",
 @uuid="cus_e814c4a0-0276-11e7-b154-dbf8b45871a1",
 @zip=nil>
{ 
  "id": 6195369,
  "uuid": "cus_eaa30dc2-025c-11e7-9b58-5b5a8ca7dc6a",
  "external_id": "cus_0001",
  "name": "Adam Smith",
  "email": "[email protected]",
  "status": "Lead",
  "customer-since": null,
  "attributes": { 
    "custom": { 
      "channel": "Facebook", 
      "age": 18 
    },
    "clearbit": {},
    "stripe": {},
    "tags": [ 'important', 'Prio1' ]
  },
  "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  "data_source_uuids": [ 'ds_fef05d54-47b4-431b-aed2-eb6b9e545430' ],
  "external_ids": [ 'cus_0001' ],
  "company": "",
  "country": "US",
  "state": null,
  "city": "New York",
  "zip": null,
  "lead_created_at": "2015-10-14T00:00:00.000Z",
  "free_trial_started_at": "2015-11-01T00:00:00.000Z",
  "address": { 
    "country": "United States",
    "state": null,
    "city": "New York",
    "address_zip": null
  },
  "mrr": 0,
  "arr": 0,
  "billing-system-url": null,
  "chartmogul-url": "https://app.chartmogul.com/#customers/6195369-Adam_Smith",
  "billing-system-type": "Import API",
  "currency": "USD",
  "currency-sign": "$"
}
<?php
ChartMogul\Customer::__set_state(array(
   'id' => 6262350,
   'uuid' => 'cus_721eb496-026b-11e7-aa36-5f20dd128faa',
   'external_id' => 'cus_0001',
   'name' => 'Adam Smith',
   'email' => [email protected]',
   'company' => '',
   'status' => 'Lead',
   'customer_since' => NULL,
   'attributes' =>
  array (
    'custom' =>
    array (
      'channel' => 'Facebook',
      'age' => 18,
    ),
    'clearbit' =>
    array (
    ),
    'stripe' =>
    array (
    ),
    'tags' =>
    array (
      0 => 'important',
      1 => 'Prio1',
    ),
  ),
   'address' =>
  array (
    'country' => 'United States',
    'state' => NULL,
    'city' => 'New York',
    'address_zip' => NULL,
  ),
   'mrr' => 0,
   'arr' => 0,
   'billing_system_url' => NULL,
   'chartmogul_url' => 'https://app.chartmogul.com/#customers/6262350-Adam_Smith',
   'billing_system_type' => 'Import API',
   'currency' => 'USD',
   'currency_sign' => '$',
   'data_source_uuid' => 'ds_fef05d54-47b4-431b-aed2-eb6b9e545430',
   'data_source_uuids' =>
  array (
    0 => 'ds_fef05d54-47b4-431b-aed2-eb6b9e545430',
  ),
   'external_ids' =>
  array (
    0 => 'cus_0001',
  ),
   'city' => 'New York',
   'country' => 'US',
   'state' => NULL,
   'zip' => NULL,
   'lead_created_at' => '2015-10-14T00:00:00.000Z',
   'free_trial_started_at' => '2015-11-01T00:00:00.000Z',
  )),
))
?>
(*chartmogul.Customer)(0xc0420706e0)({
 ID: (uint32) 4861688,
 DataSourceUUID: (string) (len=39) "ds_9bb53a1e-edfd-11e6-bf83-af49e978cb11",
 UUID: (string) (len=40) "cus_c0dc8d74-edfd-11e6-a357-832dddba822f",
 ExternalID: (string) (len=8) "cus_0001",
 Name: (string) (len=10) "Adam Smith",
 Email: (string) (len=14) "[email protected]",
 Status: (string) (len=4) "Lead",
 CustomerSince: (string) "",
Attributes: (*chartmogul.Attributes)(0xc04221a3c0)({
  Tags: ([]string) (len=2 cap=4) {
   (string) (len=9) "important",
   (string) (len=5) "Prio1"
  },
  Stripe: (*chartmogul.Stripe)(0xc042213440)({
   UID: (uint64) 0,
   Coupon: (bool) false
  }),
  Clearbit: (*chartmogul.Clearbit)(0xc0421fc060)({
   ID: (string) "",
   Name: (string) "",
   LegalName: (string) "",
   Domain: (string) "",
   URL: (string) "",
   Metrics: (map[string]interface {}) <nil>,
   Category: (*chartmogul.Category)(<nil>)
  }),
  Custom: (map[string]interface {}) (len=2) {
   (string) (len=7) "channel": (string) (len=8) "Facebook",
   (string) (len=3) "age": (float64) 18
  }
 }),
 Address: (*chartmogul.Address)(0xc0421e4000)({
  AddressZIP: (string) "",
  City: (string) (len=8) "New York",
  State: (string) "",
  Country: (string) (len=13) "United States"
 }),
 Mrr: (float64) 0,
 Arr: (float64) 0,
 BillingSystemURL: (string) "",
 ChartmogulURL: (string) (len=56) "https://app.chartmogul.com/#customers/4861688                   -Adam_Smith",
 BillingSystemType: (string) (len=10) "Import API",
 Currency: (string) (len=3) "USD",
 CurrencySign: (string) (len=1) "$",
 Company: (string) "",
 Country: (string) (len=2) "US",
 State: (string) "",
 City: (string) (len=8) "New York",
 LeadCreatedAt: (string) (len=24) "2015-10-14T00:00:00.000Z",
 FreeTrialStartedAt: (string) (len=24) "2015-11-01T00:00:00.000Z",
 Errors: (chartmogul.Errors) chartmogul: map[]
})
<Customer{
    address=<Address{
        address_zip=None,
        city='New York',
        country='United States',
        state=None}>,
    arr=0.0,
    attributes=<Attributes{
        clearbit=<Clearbit{
        }>,
        custom={
        },
        stripe=<Stripe{
        }>,
        tags=[]}>,
    billing_system_type='Import API',
    billing_system_url=None,
    chartmogul_url='https://app.chartmogul.com/#customers/4868653-Adam_Smith',
    city='New York',
    company='',
    country='US',
    currency='USD',
    currency_sign='$',
    customer_since=None,
    data_source_uuid='ds_9bb53a1e-edfd-11e6-bf83-af49e978cb11',
    data_source_uuids=['ds_9bb53a1e-edfd-11e6-bf83-af49e978cb11'],
    email=[email protected]',
    external_id='cus_0008',
    external_ids=['cus_0008'],
    free_trial_started_at=datetime.datetime(2015, 11, 1, 0, 0),
    id=4868653,
    lead_created_at=datetime.datetime(2015, 10, 14, 0, 0),
    mrr=0.0,
    name='Adam Smith',
    state=None,
    status='Lead',
    uuid='cus_6a75dd6a-ee01-11e6-9c15-9fa749e4d3b1',
    zip=None}>
Suggest Edits

Retrieve a Customer

Retrieves a customer object from your ChartMogul account.

 
gethttps://api.chartmogul.com/v1/customers/CUSTOMER_UUID

Path Params

customer_uuid
string
required

The ChartMogul UUID of the customer you are retrieving.

 

In the response, the JSON object contains the following data:

  • id - The internal ChartMogul ID of the customer object.
  • uuid - The UUID of the customer object generated by ChartMogul.
  • external_id - The unique external identifier for this customer, if any.
  • external_ids - An array containing the unique external identifiers of all customer records that have been merged into this customer.
  • data_source_uuid - The ChartMogul UUID of the data source of this customer.
  • data_source_uuids - An array containing the ChartMogul UUIDs of all data sources that contribute data to this customer. This is most relevant for merged customers.
  • name - The name of this customer.
  • email - This customer's email address.
  • status - The status of this customer. One of Lead, Active or Cancelled.
  • lead_created_at - The time at which this customer was established as a lead, as specified by you.
  • free_trial_started_at - The time at which this customer started a free trial of your product or service, as specified by you.
  • customer-since - An RFC3339 formatted datetime attribute indicating when the customer first started paying for a subscription.
  • country - The country from the customer's address.
  • state - The state from the customer's address.
  • city - The city from the customer's address.
  • zip - The zip code from the customer's address.
  • attributes - A JSON object representing this customer's attributes containing the following data:
    • tags - An Array of tags that you have added to this customer.
    • stripe - A JSON object representing any metadata on this customer object in your Stripe account.
    • clearbit - A JSON object representing publicly available information about this customer retrieved from Clearbit.
    • custom - A JSON object representing custom attributes that you have added to this customer.
  • address - A JSON object representing this customer's address containing the following data:
    • address_zip - The zip code from this customer's address.
    • city - The city from this customer's address.
    • state - The state from this customer's address.
    • country - The country code from this customer's address as per the ISO-3166 alpha-2 standard.
  • mrr - The current monthly recurring revenue for this customer, expressed in the currency selected for your account, as an integer number of cents. Divide by 100 to obtain the actual amount.
  • arr - The current annual run rate for this customer, also expressed as an integer number of cents in your account's selected currency.
  • billing-system-url - A URL for this customer's data in your billing system, if available.
  • chartmogul-url - The URL for this customer's ChartMogul page. This is only accessible to a user logged in to your ChartMogul account.
  • billing-system-type - The type of the billing system from where the customer was imported to ChartMogul. For example, Stripe, Recurly, Chargify, or Import API.
  • currency - The currency of the MRR readings for this customer.
  • currency-sign - Text representation to display the currency. E.g. $, or €.

Examples

curl -X GET "https://api.chartmogul.com/v1/customers/cus_de305d54-75b4-431b-adb2-eb6b9e546012" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_KEY
ChartMogul::Customer.retrieve('cus_de305d54-75b4-431b-adb2-eb6b9e546012')
ChartMogul.Customer.retrieve(config, "cus_de305d54-75b4-431b-adb2-eb6b9e546012", function(err, res) {
   // asynchronously called
});
<?php

ChartMogul\Customer::retrieve("cus_de305d54-75b4-431b-adb2-eb6b9e546012");
?>
api.RetrieveCustomer("cus_c0dc8d74-edfd-11e6-a357-832dddba822f")
chartmogul.Customer.retrieve(
    config,
    uuid="cus_c0dc8d74-edfd-11e6-a357-832dddba822f"
)

Result Format

{
  "id": 25647,
  "uuid": "cus_de305d54-75b4-431b-adb2-eb6b9e546012",
  "external_id": "34916129",
  "name": "Example Company",
  "email": "[email protected]",
  "status": "Active",
  "customer-since": "2015-06-09T13:16:00-04:00",
  "attributes": {
    "tags": ["engage", "unit loss", "discountable"],
    "stripe": {
      "uid": 7,
      "coupon": true
    }, 
    "clearbit": {
      "id": "027b0d40-016c-40ea-8925-a076fa640992",
      "name": "Acme",
      "legalName": "Acme Inc.",
      "domain": "acme.com",
      "url": "http://acme.com",
      "metrics": {
        "raised": 1502450000,
        "employees": 1000,
        "googleRank": 7,
        "alexaGlobalRank": 2319,
        "marketCap": null
      },
      "category": {
        "sector": "Information Technology",
        "industryGroup": "Software and Services",
        "industry": "Software",
        "subIndustry": "Application Software"
      }
    },
    "custom": {
      "CAC": 213,
      "utmCampaign": "social media 1",
      "convertedAt": "2015-09-08 00:00:00",
      "pro": false,
      "salesRep": "Gabi"
    }
  },
  "address": {
    "address_zip": "0185128",
    "city": "Nowhereville",
    "state": "Alaska",
    "country": "US"
  },
  "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  "data_source_uuids": ["ds_fef05d54-47b4-431b-aed2-eb6b9e545430"],
  "external_ids": ["34916129"],
  "company": "",
  "country": "US",
  "state": "Alaska",
  "city": "Nowhereville",
  "zip": "0185128",
  "lead_created_at": null,
  "free_trial_started_at": null,
  "mrr": 3000,
  "arr": 36000,
  "billing-system-url": "https:\/\/dashboard.stripe.com\/customers\/cus_4Z2ZpyJFuQ0XMb",
  "chartmogul-url": "https:\/\/app.chartmogul.com\/#customers\/25647-Example_Company",
  "billing-system-type": "Stripe",
  "currency": "USD",
  "currency-sign": "$"
}
#<ChartMogul::Customer:0x007faf03b02d68 
@id=25647, 
@uuid="cus_de305d54-75b4-431b-adb2-eb6b9e546012",
@data_source_uuid="ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
@data_source_uuids=["ds_fef05d54-47b4-431b-aed2-eb6b9e545430"],
@external_id="34916129",
@external_ids=["34916129"],
@name="Example Company", 
@email="[email protected]", 
@status="Active",
@lead_created_at=null,
@free_trial_started_at=null,
@customer_since=2015-06-09 13:16:00 -04:00:00,
@country="US",
@state="Alaska",
@city="Nowhereville",
@zip="0185128",
@attributes={
  :tags=>["engage", "unit loss", "discountable"], 
  :stripe=>{
    :uid=>7,
    :coupon=>true
  },
  :clearbit=>{
    :id=>"027b0d40-016c-40ea-8925-a076fa640992",
    :name=>"Acme",
    :legalName=> "Acme Inc.",
    :domain=> "acme.com",
    :url=> "http://acme.com",
    :metrics=>{
      :raised=> 1502450000,
      :employees=> 1000,
      :googleRank=> 7,
      :alexaGlobalRank=> 2319,
      :marketCap=> null
    },
    :category=>{
      :sector=> "Information Technology",
      :industryGroup=> "Software and Services",
      :industry=> "Software",
      :subIndustry=> "Application Software"
    }
  },
  :custom=>{
    :CAC=> 213,
    :utmCampaign=> "social media 1",
    :convertedAt=> "2015-09-08 00:00:00",
    :pro=> false,
    :salesRep=> "Gabi"
  }
}, 
@address={
  :address_zip=>"0185128",
  :city=>"Nowhereville",
  :state=>"Alaska", 
  :country=>"US"
}, 
@mrr=3000, 
@arr=36000, 
@billing_system_url="https:\/\/dashboard.stripe.com\/customers\/cus_4Z2ZpyJFuQ0XMb", 
@chartmogul_url="https:\/\/app.chartmogul.com\/#customers\/25647-Example_Company", 
@billing_system_type="Stripe", 
@currency="USD", 
@currency_sign="$"
>
{
  "id": 25647,
  "uuid": "cus_de305d54-75b4-431b-adb2-eb6b9e546012",
  "external_id": "34916129",
  "name": "Example Company",
  "email": "[email protected]",
  "status": "Active",
  "customer-since": "2015-06-09T13:16:00-04:00",
  "attributes": {
    "tags": ["engage", "unit loss", "discountable"],
    "stripe": {
      "uid": 7,
      "coupon": true
    }, 
    "clearbit": {
      "id": "027b0d40-016c-40ea-8925-a076fa640992",
      "name": "Acme",
      "legalName": "Acme Inc.",
      "domain": "acme.com",
      "url": "http://acme.com",
      "metrics": {
        "raised": 1502450000,
        "employees": 1000,
        "googleRank": 7,
        "alexaGlobalRank": 2319,
        "marketCap": null
      },
      "category": {
        "sector": "Information Technology",
        "industryGroup": "Software and Services",
        "industry": "Software",
        "subIndustry": "Application Software"
      }
    },
    "custom": {
      "CAC": 213,
      "utmCampaign": "social media 1",
      "convertedAt": "2015-09-08 00:00:00",
      "pro": false,
      "salesRep": "Gabi"
    }
  },
  "address": {
    "address_zip": "0185128",
    "city": "Nowhereville",
    "state": "Alaska",
    "country": "US"
  },
  "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  "data_source_uuids": ["ds_fef05d54-47b4-431b-aed2-eb6b9e545430"],
  "external_ids": ["34916129"],
  "company": "",
  "country": "US",
  "state": "Alaska",
  "city": "Nowhereville",
  "zip": "0185128",
  "lead_created_at": null,
  "free_trial_started_at": null,
  "mrr": 3000,
  "arr": 36000,
  "billing-system-url": "https:\/\/dashboard.stripe.com\/customers\/cus_4Z2ZpyJFuQ0XMb",
  "chartmogul-url": "https:\/\/app.chartmogul.com\/#customers\/25647-Example_Company",
  "billing-system-type": "Stripe",
  "currency": "USD",
  "currency-sign": "$"
}
<?php

ChartMogul\Customer::__set_state(array(
   "id" => 25647,
   "uuid" => "cus_de305d54-75b4-431b-adb2-eb6b9e546012",
   "external_id" => "34916129",
   "name" => "Example Company",
   "email" => "[email protected]",
   "status" => "Active",
   "customer_since" => "2015-06-09T13:16:00-04:00",
   "attributes" =>
  array (
    "custom" =>
    array (
      "CAC" => 213,
      "utmCampaign" => "social media 1",
      "convertedAt" => "2015-09-08 00 =>00 =>00",
      "pro" => false,
      "salesRep" => "Gabi"
    ),
    "clearbit" =>
    array (
      "id" => "027b0d40-016c-40ea-8925-a076fa640992",
      "name" => "Acme",
      "legalName" => "Acme Inc.",
      "domain" => "acme.com",
      "url" => "http =>//acme.com",
      "metrics" => array (
        "raised" => 1502450000,
        "employees" => 1000,
        "googleRank" => 7,
        "alexaGlobalRank" => 2319,
        "marketCap" => null
      ),
      "category" => array (
        "sector" => "Information Technology",
        "industryGroup" => "Software and Services",
        "industry" => "Software",
        "subIndustry" => "Application Software"
      )
    ),
    "stripe" =>
    array (
      "uid" => 7,
      "coupon" => true
    ),
    "tags" =>
    array (
      0 => "engage",
      1 => "unit loss",
      2 => "discountable"
    ),
  ),
   "address" =>
  array (
    "address_zip" => "0185128",
    "city" => "Nowhereville",
    "state" => "Alaska",
    "country" => "US"
  ),
   "mrr" => 3000,
   "arr" => 36000,
   "billing_system_url" => "https:\/\/dashboard.stripe.com\/customers\/cus_4Z2ZpyJFuQ0XMb",
   "chartmogul_url" => "https:\/\/app.chartmogul.com\/#customers\/25647-Example_Company",
   "billing_system_type" => "Stripe",
   "currency" => "USD",
   "currency_sign" => "$",
   "data_source_uuid" => "ds_80686670-cc45-11e6-b9da-ff67b9895fe3",
   "data_source_uuids" =>
  array (
    0 => "ds_80686670-cc45-11e6-b9da-ff67b9895fe3",
  ),
   "external_ids" =>
  array (
    0 => "cus_0001",
  ),
   "city" => "Nowhereville",
   "country" => "US",
   "state" => "Alaska",
   "zip" => "0185128",
   "lead_created_at" => "2015-10-14T00:00:00.000Z",
   "free_trial_started_at" => "2015-11-01T00:00:00.000Z",
   "company" => ""
));
?>
(*chartmogul.Customer)(0xc04207e6e0)({
 ID: (uint32) 4861688,
 DataSourceUUID: (string) (len=39) "ds_9bb53a1e-edfd-11e6-bf83-af49e978cb11",
 DataSourceUUIDs: ([]string) {
  (len=39) "ds_9bb53a1e-edfd-11e6-bf83-af49e978cb11"
 },
 UUID: (string) (len=40) "cus_c0dc8d74-edfd-11e6-a357-832dddba822f",
 ExternalID: (string) (len=8) "cus_0001",
 ExternalIDs: ([]string) {
  (len=8) "cus_0001"
 },
 Name: (string) (len=10) "Adam Smith",
 Email: (string) (len=14) "[email protected]",
 Status: (string) (len=6) "Active",
 CustomerSince: (string) (len=25) "2015-11-01T00:00:00+00:00",
 Attributes: (*chartmogul.Attributes)(0xc042132b10)({
  Tags: ([]string) {
  },
  Stripe: (*chartmogul.Stripe)(0xc04212f5d0)({
   UID: (uint64) 0,
   Coupon: (bool) false
  }),
  Clearbit: (*chartmogul.Clearbit)(0xc0420f8cc0)({
   ID: (string) "",
   Name: (string) "",
   LegalName: (string) "",
   Domain: (string) "",
   URL: (string) "",
   Metrics: (map[string]interface {}) <nil>,
   Category: (*chartmogul.Category)(<nil>)
  }),
  Custom: (map[string]interface {}) {
  }
 }),
 Address: (*chartmogul.Address)(0xc042009800)({
  AddressZIP: (string) "",
  City: (string) (len=8) "New York",
  State: (string) "",
  Country: (string) (len=13) "United States"
 }),
 Mrr: (float64) 4100,
 Arr: (float64) 49200,
 BillingSystemURL: (string) "",
 ChartmogulURL: (string) (len=56) "https://app.chartmogul.com/#customers/4861688-Adam_Smith",
 BillingSystemType: (string) (len=10) "Import API",
 Currency: (string) (len=3) "USD",
 CurrencySign: (string) (len=1) "$",
 Company: (string) "",
 Country: (string) (len=2) "US",
 State: (string) "",
 City: (string) (len=8) "New York",
 Zip: (string) "",
 LeadCreatedAt: (string) (len=24) "2015-10-14T00:00:00.000Z",
 FreeTrialStartedAt: (string) (len=24) "2015-11-01T00:00:00.000Z",
 Errors: (chartmogul.Errors) chartmogul: map[]
})
<Customer{
    address=<Address{
        address_zip=None, 
        city='New York', 
        country='United States', 
        state=None}>, 
    arr=49200.0, 
    attributes=<Attributes{
        clearbit=<Clearbit{
        }>, 
        custom={
        }, 
        stripe=<Stripe{
        }>, 
        tags=[]}>, 
    billing_system_type='Import API', 
    billing_system_url=None, 
    chartmogul_url='https://app.chartmogul.com/#customers/4861688-Adam_Smith', 
    city='New York', 
    company='', 
    country='US', 
    currency='USD', 
    currency_sign='$', 
    customer_since=datetime.datetime(2015, 11, 1, 0, 0), 
    data_source_uuid='ds_9bb53a1e-edfd-11e6-bf83-af49e978cb11', 
    data_source_uuids=['ds_9bb53a1e-edfd-11e6-bf83-af49e978cb11'], 
    email=[email protected]', 
    external_id='cus_0001', 
    external_ids=['cus_0001'], 
    free_trial_started_at=datetime.datetime(2015, 11, 1, 0, 0), 
    id=4861688, 
    lead_created_at=datetime.datetime(2015, 10, 14, 0, 0), 
    mrr=4100.0, 
    name='Adam Smith', 
    state=None, 
    status='Active', 
    uuid='cus_c0dc8d74-edfd-11e6-a357-832dddba822f', 
    zip=None}>
Suggest Edits

Update a Customer

Updates certain modifiable attributes of a customer object in your ChartMogul account.

 
patchhttps://api.chartmogul.com/v1/customers/CUSTOMER_UUID

Form Data

name
string

Name of the customer for display purposes. Accepts alphanumeric characters.

email
string

Email address of the customer.

company
string

The customer's company or organisation.

country
string

Country code of customer's location as per ISO-3166 alpha-2 standard.

state
string

State code of customer's location as per ISO-3166 alpha-2 standard.

city
string

City of the customer's location.

lead_created_at
date-time

Time at which this customer was established as a lead. Must be an ISO 8601 formatted time in the past. The timezone defaults to UTC unless otherwise specified.

free_trial_started_at
date-time

Time at which this customer started a free trial of your product or service. Must be an ISO 8601 formatted time in the past. The timezone defaults to UTC unless otherwise specified. This is expected to be the same as, or after the lead_created_at value.

attributes
object

A JSON object containing additional attributes of the customer in the form of tags and custom attributes as described below.

attributes.tags
array of strings

An Array of all tags of the customer. All the customer's tags will be replaced with what is specified in this attribute.

attributes.custom
object

Contains the custom attributes to be updated. Each custom attribute must have a key and value. You can update the source by making the value another object as in examples.

 

In the response, the JSON object contains the following data:

  • id - The internal ChartMogul ID of the customer object.
  • uuid - The UUID of the customer object generated by ChartMogul.
  • data_source_uuid - The UUID of the data source that this customer belongs to. If this is a merged customer, then this will show the external identifier for the customer you chose to merge into.
  • data_source_uuids - An Array of the UUIDs of all data sources that contribute data to this customer.
  • external_id - The unique external identifier for this customer, as specified by you. If this is a merged customer, then this will show the external identifier for the customer you chose to merge into.
  • external_ids - An Array of the external identifiers of all customers that have been merged into this customer.
  • name - Name of this customer, as specified by you.
  • email - This customer's email address, as specified by you.
  • company - This customer's company name, as specified by you.
  • country - The country of the customer, as specified by you.
  • state - The state from the customer's address, as specified by you.
  • city - The city of the customer, as specified by you.
  • zip - The zip code of the customer, as specified by you.
  • lead_created_at - The time at which this customer was established as a lead, as specified by you.
  • free_trial_started_at - The time at which this customer started a free trial of your product or service, as specified by you.
  • customer-since - An RFC3339 formatted datetime attribute indicating when the customer first started paying for a subscription.
  • status - The status of this customer. One of Lead, Active or Cancelled.
  • address - A JSON object representing this customer's address containing the following data:
    • address_zip - The zip code of this customer's address.
    • city - The city of this customer's address.
    • state - The state from this customer's address.
    • country - The country code of this customer's address as per the ISO-3166 alpha-2 standard.
  • attributes - A JSON object representing this customer's attributes containing the following data:
    • tags - An Array of tags that you have added to this customer.
    • stripe - A JSON object representing any metadata on this customer object in your Stripe account.
    • clearbit - A JSON object representing publicly available information about this customer retrieved from Clearbit.
    • custom - A JSON object representing custom attributes that you have added to this customer.
  • mrr - The current monthly recurring revenue for this customer, expressed in the currency selected for your account, as an integer number of cents. Divide by 100 to obtain the actual amount.
  • arr - The current annual run rate for this customer, also expressed as an integer number of cents in your account's selected currency.
  • billing-system-url - A URL for this customer's data in your billing system, if available.
  • chartmogul-url - The URL for this customer's ChartMogul page. This is only accessible to a user logged in to your ChartMogul account.
  • billing-system-type - The type of the billing system from where the customer was imported to ChartMogul. For example, Stripe, Recurly, Chargify, or Import API.
  • currency - The currency of the MRR readings for this customer.
  • currency-sign - Text representation to display the currency. E.g. $, or €.

Examples

curl -X PATCH "https://api.chartmogul.com/v1/customers/cus_ab223d54-75b4-431b-adb2-eb6b9e234571" \
       -u <token>:<secret> \
       -H  "Content-Type: application/json" \
       -d '{
            "lead_created_at": "2015-01-01 00:00:00",
            "free_trial_started_at": "2015-06-13 15:45:13",
            "city": "San Francisco",
            "country": "US",
            "state": "CA",
            "attributes": {
              "tags": ["high-value"],
              "custom": {
                "CAC": 25,
                "channel": {"value": "Twitter", "source": "integration2"}
              }
             }
           }'
customer = ChartMogul::Customer.retrieve("cus_ab223d54-75b4-431b-adb2-eb6b9e234571")

customer.lead_created_at = Time.utc(2015,1,1)
customer.free_trial_started_at = Time.utc(2015,6,13,15,45,13)
customer.city = "San Francisco"
customer.country = "US"
customer.state = "CA"
customer.attributes[:tags] = ["high-value"]
customer.attributes[:custom] = {"CAC": 25, "channel": {"value": "Twitter", "source": "integration2"}}

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

var data = {
    "lead_created_at": "2015-01-01 00:00:00",
    "free_trial_started_at": "2015-06-13 15:45:13",
    "city": "San Francisco",
    "country": "US",
    "state": "CA",
    "attributes": {
        "tags": ["high-value"],
        "custom": {
            "CAC": 25,
          	"channel": {"value": "Twitter", "source": "integration2"}
        }
    }
};

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

ChartMogul\Customer::update([
    'customer_uuid' => "cus_ab223d54-75b4-431b-adb2-eb6b9e234571"
        ], [
    "lead_created_at" => "2015-01-01 00:00:00",
    "free_trial_started_at" => "2015-06-13 15:45:13",
    "city" => "San Francisco",
    "country" => "US",
    "state" => "CA",
    "attributes" => [
        "tags" => ["high-value"],
        "custom" => [
            "CAC" => 25,
          	"channel" => ["value" => "Twitter", "source" => "integration2"]
        ]
    ]
]);
?>
api.UpdateCustomer(&cm.Customer{
		LeadCreatedAt:      "2015-01-01 00:00:00",
		FreeTrialStartedAt: "2015-06-13 15:45:13",
		City:               "San Francisco",
		Country:            "US",
		State:              "CA",
		Attributes: &cm.Attributes{
			Tags: []string{"high-value"},
			Custom: map[string]interface{}{
				"CAC": 25,
        "channel": cm.AttributeWithSource{
          Value: "Twitter",
          Source: "integration2",
        },
			}}}, "cus_ab223d54-75b4-431b-adb2-eb6b9e234571")
chartmogul.Customer.modify(
    config,
    uuid="cus_ab223d54-75b4-431b-adb2-eb6b9e234571",
    data={
      "lead_created_at": "2015-01-01 00:00:00",
      "free_trial_started_at": "2015-06-13 15:45:13",
      "city": "San Francisco",
      "country": "US",
      "state": "CA",
      "attributes": {
        "tags": ["high-value"],
        "custom": {
          "CAC": 25,
          "channel": {"value": "Twitter", "source": "integration2"}
        }
      }
    })

Result Format

{
    "id": 12150249,
    "uuid": "cus_ab223d54-75b4-431b-adb2-eb6b9e234571",
    "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
    "data_source_uuids": ["ds_fef05d54-47b4-431b-aed2-eb6b9e545430"],
    "external_id": "34916129",
    "external_ids": ["34916129"],
    "name": "Ben",
    "email": "[email protected]",
    "company": "Example Company",
    "city": "San Francisco",
    "country": "US",
    "state": "CA",
    "zip": "99801",
    "lead_created_at": "2015-01-01T00:00:00.000Z",
    "free_trial_started_at": "2015-06-13T15:45:13.000Z",
    "customer-since": "2015-06-19T13:16:00-04:00",
    "status": "Active",
    "address": {
      "address_zip": "99801",
      "city": "San Francisco",
      "country": "US",
      "state": "CA"
     },
    "attributes": {
      "custom": {
        "CAC": 25,
        "SalesRep": "Mike",
      },
      "clearbit": {},
      "stripe": {},
      "tags": ["high-value"]
    },
    "mrr": 3000,
    "arr": 36000,
    "billing-system-url": "",
    "chartmogul-url": "https:\/\/app.chartmogul.com\/#customers\/12150249-Example_Company",
  	"billing-system-type": "Import API",
  	"currency": "USD",
  	"currency-sign": "$"
}
#<ChartMogul::Customer:0x0000000349d6a0
 @address=
  {:country=>"United States",
   :state=>"California",
   :city=>"San Francisco",
   :address_zip=>"99801"},
 @arr=36000,
 @attributes=
  {:custom=>{:CAC=>25, :SalesRep=>"Mike"},
   :clearbit=>{},
   :stripe=>{},
   :tags=>["high-value"]},
 @billing_system_type="Import API",
 @billing_system_url=nil,
 @chartmogul_url="https://app.chartmogul.com/#customers/12150249-Example_Company",
 @city="San Francisco",
 @company="Example Company",
 @country="US",
 @currency="USD",
 @currency_sign="$",
 @customer_since=2017-01-19 15:29:46 +0000,
 @data_source_uuid="ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
 @data_source_uuids=["ds_fef05d54-47b4-431b-aed2-eb6b9e545430"],
 @email="[email protected]",
 @external_id="34916129",
 @external_ids=["34916129"],
 @free_trial_started_at=2015-06-13 15:45:13 UTC,
 @id=12150249,
 @lead_created_at=2015-01-01 00:00:00 UTC,
 @mrr=3000,
 @name="Ben",
 @state="CA",
 @status="Active",
 @uuid="cus_ab223d54-75b4-431b-adb2-eb6b9e234571",
 @zip="99801">
{
    "id": 12150249,
    "uuid": "cus_ab223d54-75b4-431b-adb2-eb6b9e234571",
    "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
    "data_source_uuids": ["ds_fef05d54-47b4-431b-aed2-eb6b9e545430"],
    "external_id": "34916129",
    "external_ids": ["34916129"],
    "name": "Ben",
    "email": "[email protected]",
    "company": "Example Company",
    "city": "San Francisco",
    "country": "US",
    "state": "CA",
    "zip": "99801",
    "lead_created_at": "2015-01-01T00:00:00.000Z",
    "free_trial_started_at": "2015-06-13T15:45:13.000Z",
    "customer-since": "2015-06-19T13:16:00-04:00",
    "status": "Active",
    "address": {
      "address_zip": "99801",
      "city": "San Francisco",
      "country": "US",
      "state": "CA"
     },
    "attributes": {
      "custom": {
        "CAC": 25,
        "SalesRep": "Mike",
      },
      "clearbit": {},
      "stripe": {},
      "tags": ["high-value"]
    },
    "mrr": 3000,
    "arr": 36000,
    "billing-system-url": "",
    "chartmogul-url": "https:\/\/app.chartmogul.com\/#customers\/12150249-Example_Company",
  	"billing-system-type": "Import API",
  	"currency": "USD",
  	"currency-sign": "$"
}
<?php
ChartMogul\Customer::__set_state(array(
   'id' => 12150249,
   'uuid' => 'cus_ab223d54-75b4-431b-adb2-eb6b9e234571',
   'external_id' => '34916129',
   'name' => 'Ben',
   'email' => [email protected]',
   'company' => 'Example Company',
   'status' => 'Active',
   'customer_since' => '2017-01-19T15:29:46.000Z',
   'attributes' =>
  array (
    'custom' =>
    array (
      'CAC' => 25,
      'channel' => 'Facebook',
    ),
    'clearbit' =>
    array (
    ),
    'stripe' =>
    array (
    ),
    'tags' =>
    array (
      0 => 'high-value',
    ),
  ),
   'address' =>
  array (
    'country' => 'United States',
    'state' => 'California',
    'city' => 'San Francisco',
    'address_zip' => '99801',
  ),
   'mrr' => 3000,
   'arr' => 36000,
   'billing_system_url' => NULL,
   'chartmogul_url' => 'https://app.chartmogul.com/#customers/12150249-Example_Company',
   'billing_system_type' => 'Import API',
   'currency' => 'USD',
   'currency_sign' => '$',
   'data_source_uuid' => 'ds_fef05d54-47b4-431b-aed2-eb6b9e545430',
   'data_source_uuids' =>
  array (
    0 => 'ds_fef05d54-47b4-431b-aed2-eb6b9e545430',
  ),
   'external_ids' =>
  array (
    0 => '34916129',
  ),
   'city' => 'San Francisco',
   'country' => 'US',
   'state' => 'CA',
   'zip' => '99801',
   'lead_created_at' => '2015-01-01T00:00:00.000Z',
   'free_trial_started_at' => '2015-06-13T15:45:13.000Z',
 ));
?>
(*chartmogul.Customer)(0xc04207e840)({
 ID: (uint32) 12150249,
 DataSourceUUID: (string) (len=39) "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
 UUID: (string) (len=40) "cus_ab223d54-75b4-431b-adb2-eb6b9e234571",
 ExternalID: (string) (len=8) "34916129",
 Name: (string) (len=3) "Ben",
 Email: (string) (len=29) "[email protected]",
 Status: (string) (len=6) "Active",
 CustomerSince: (string) (len=25) "2015-06-19T13:16:00-04:00",
 Attributes: (*chartmogul.Attributes)(0xc042089950)({
  Tags: ([]string) (len=1) {
   (string) (len=10) "high-value"
  },
  Stripe: (*chartmogul.Stripe)(0xc042041ec0)({
  }),
  Clearbit: (*chartmogul.Clearbit)(0xc04203ec00)({
  }),
  Custom: (map[string]interface {}) (len=2) {
   (string) (len=3) "CAC": (float64) 25,
   (string) (len=8) "SalesRep": (string) (len=4) "Mike"
  }
 }),
 Address: (*chartmogul.Address)(0xc0420485c0)({
  AddressZIP: (string) (len=6) "99801",
  City: (string) (len=13) "San Francisco",
  State: (string) (len=2) "CA",
  Country: (string) (len=2) "US"
 }),
 Mrr: (float64) 3000,
 Arr: (float64) 36000,
 BillingSystemURL: (string) "",
 ChartmogulURL: (string) (len=62) "https://app.chartmogul.com/#customers/12150249-Example_Company",
 BillingSystemType: (string) (len=10) "Import API",
 Currency: (string) (len=3) "USD",
 CurrencySign: (string) (len=1) "$",
 Company: (string) "Example Company",
 Country: (string) (len=2) "US"
 State: (string) (len=2) "CA",
 City: (string) (len=13) "San Francisco",
 Zip: (string) (len=6) "99801",
 LeadCreatedAt: (string) (len=24) "2015-01-01T00:00:00.000Z",
 FreeTrialStartedAt: (string) (len=24) "2015-06-13T15:45:13.000Z",
 Errors: (chartmogul.Errors) chartmogul: map[]
})
<Customer{
    address=<Address{
        address_zip='99801', 
        city='San Francisco', 
        country='US', 
        state='CA'}>, 
    arr=36000.0, 
    attributes=<Attributes{
        clearbit=<Clearbit{
        }>, 
        custom={
            'CAC': 25, 
            'SalesRep': 'Mike'}, 
        stripe=<Stripe{
        }>, 
        tags=['high-value']}>, 
    billing_system_type='Import API', 
    billing_system_url=None, 
    chartmogul_url='https://app.chartmogul.com/#customers/12150249-Example_Company', 
    city='San Francisco', 
    company='Example Company', 
    country='US', 
    currency='USD', 
    currency_sign='$', 
    customer_since=datetime.datetime(2015, 11, 1, 0, 0), 
    data_source_uuid='ds_fef05d54-47b4-431b-aed2-eb6b9e545430', 
    data_source_uuids=['ds_fef05d54-47b4-431b-aed2-eb6b9e545430'], 
    email=[email protected]', 
    external_id='34916129', 
    external_ids=['34916129'], 
    free_trial_started_at=datetime.datetime(2015, 6, 13, 15, 45, 13), 
    id=12150249, 
    lead_created_at=datetime.datetime(2015, 1, 1, 0, 0), 
    mrr=3000.0, 
    name='Ben', 
    state='CA', 
    status='Active', 
    uuid='cus_ab223d54-75b4-431b-adb2-eb6b9e234571', 
    zip='99801'}>
Suggest Edits

Delete a Customer

Deletes the specified customer object and all its associated data.

 
deletehttps://api.chartmogul.com/v1/customers/CUSTOMER_UUID

Path Params

customer_uuid
string
required

The ChartMogul UUID of the customer that needs to be deleted. Specified as part of the URL.

 

Impact of this action

This request will permanently delete the customer and all associated data. Data deleted includes the customer's invoices, subscriptions, transactions and any customer attributes. The customer will also be removed from all reports in ChartMogul. This action cannot be undone.

Customers from pre-built integrations

You can only delete customers imported using the Import API with this endpoint. If you are using one of our pre-built integrations with Stripe, Braintree, Recurly, Chargify or PayPal and want to delete a customer imported from these systems, you can do so from within your ChartMogul account.

Examples

curl -X DELETE "https://api.chartmogul.com/v1/customers/cus_ee325d54-7ab4-421b-cdb2-eb6b9e546034" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_KEY
customers = ChartMogul::Customer.all
customer = customers.last
customer.destroy!
ChartMogul.Customer.destroy(config, 
 "cus_ee325d54-7ab4-421b-cdb2-eb6b9e546034",
 function (err, res) {
 // asynchronously called
});
<?php

ChartMogul\Customer::all()->last()->destroy();
?>
api.DeleteCustomer("cus_99529720-edfe-11e6-8773-13ec140c2da5")
chartmogul.Customer.destroy(
    config,
    uuid='cus_07c827b0-edff-11e6-a223-377902df0e32')

Result Format

{ }
true
{ }
true
nil
None
Suggest Edits

List Customers

Returns a list of all customer objects in your ChartMogul account.

 
gethttps://api.chartmogul.com/v1/customers

Query Params

data_source_uuid
string

The ChartMogul UUID of the data source with which you want to filter this customer list.

external_id
string

A unique external identifier of the customer that you want to retrieve.

status
string

The current status of the customers you want to retrieve. One of Lead, Active, or Cancelled.

system
string

The billing system that the customers belong to. For example, Stripe, Recurly, Chargify, or Import API. Returns all customers that have billing data from the specified system.

page
int32

The page number for pagination of results.

per_page
int32

A limit on number of customers to return per page. The default and maximum value is 200.

 

In the response, entries contains an array of customer objects with the following data:

  • id - The internal ChartMogul ID of the customer object.
  • uuid - The UUID of the customer object generated by ChartMogul.
  • external_id - The unique external identifier for this customer, if any.
  • external_ids - An array containing the unique external identifiers of all customer records that have been merged into this customer.
  • data_source_uuid - The ChartMogul UUID of the data source of this customer.
  • data_source_uuids - An array containing the ChartMogul UUIDs of all data sources that contribute data to this customer. This is most relevant for merged customers.
  • name - The name of this customer.
  • email - This customer's email address.
  • company - This customer's company name.
  • status - The status of this customer. One of Lead, Active or Cancelled.
  • lead_created_at - The time at which this customer was established as a lead, as specified by you.
  • free_trial_started_at - The time at which this customer started a free trial of your product or service, as specified by you.
  • customer-since - An RFC3339 formatted datetime attribute indicating when the customer first started paying for a subscription.
  • country - The country from the customer's address.
  • state - The state from the customer's address.
  • city - The city from the customer's address.
  • zip - The zip code from the customer's address.
  • attributes - A JSON object representing this customer's attributes containing the following data:
    • tags - An Array of tags that you have added to this customer.
    • stripe - A JSON object representing any metadata on this customer object in your Stripe account.
    • clearbit - A JSON object representing publicly available information about this customer retrieved from Clearbit.
    • custom - A JSON object representing custom attributes that you have added to this customer.
  • address - A JSON object representing this customer's address containing the following data:
    • address_zip - The zip code from this customer's address.
    • city - The city from this customer's address.
    • state - The state from this customer's address.
    • country - The country code from this customer's address as per the ISO-3166 alpha-2 standard.
  • mrr - The current monthly recurring revenue for this customer, expressed in the currency selected for your account, as an integer number of cents. Divide by 100 to obtain the actual amount.
  • arr - The current annual run rate for this customer, also expressed as an integer number of cents in your account's selected currency.
  • billing-system-url - A URL for this customer's data in your billing system, if available.
  • chartmogul-url - The URL for this customer's ChartMogul page. This is only accessible to a user logged in to your ChartMogul account.
  • billing-system-type - The type of the billing system from where the customer was imported to ChartMogul. For example, Stripe, Recurly, Chargify, or Import API.
  • currency - The currency of the MRR readings for this customer.
  • currency-sign - Text representation to display the currency. E.g. $, or €.

The other keys represent pagination attributes:

  • has_more - One of true or false depending on whether there are more pages with results for this request.
  • per_page - The number of results in this response.
  • page - The page number of this response.
  • total_pages - The total number of pages with results for this request.
  • current_page - The page number of this response.

Retrieving customers created using the API

You can use one of two filters to retrieve a list of customers created using the API.

  • use the data_source_uuid filter to retrieve customers belonging to a specific Import API data source, or
  • use the system filter and specify the value as Import API to retrieve customers belonging to all Import API data sources.

Examples

curl -X GET "https://api.chartmogul.com/v1/customers?per_page=50" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_KEY
ChartMogul::Customer.all(page: 1, per_page: 50)
ChartMogul.Customer.all(config, {
   per_page: 50
   }, function (err, res) {
   // asynchronously called
});
<?php

ChartMogul\Customer::all([
    'per_page' => 50
]);
?>
api.ListCustomers(&cm.ListCustomersParams{Cursor: cm.Cursor{PerPage: 2}})
chartmogul.Customer.all(config, per_page=2)

Result Format

{
  "entries":[
    {
      "id": 25647,
      "uuid": "cus_de305d54-75b4-431b-adb2-eb6b9e546012",
      "external_id": "34916129",
      "external_ids": ["34916129"],
      "data_source_uuid": "ds_610b7a84-c50f-11e6-8aab-97d6db98913a",
      "data_source_uuids": ["ds_610b7a84-c50f-11e6-8aab-97d6db98913a"],
      "name": "Example Company",
      "company": "",
      "email": "[email protected]",
      "status": "Active",
      "lead_created_at": "2015-01-01T10:00:00-04:00",
      "free_trial_started_at": "2015-01-09T10:00:00-04:00",
      "customer-since": "2015-06-09T13:16:00-04:00",
      "city": "Nowhereville",
      "state": "Alaska",
      "country": "US",
      "zip": "0185128",
      "attributes":{
        "tags": ["engage", "unit loss", "discountable"],
        "stripe":{
          "uid": 7,
          "coupon": true
        },
        "clearbit":{
          "company":{
            "name": "Example Company",
            "legalName": "Example Company Inc.",
            "domain": "examplecompany.com",
            "url": "http://examplecompany.com",
            "category":{
              "sector": "Information Technology",
              "industryGroup": "Software and Services",
              "industry": "Software",
              "subIndustry": "Application Software"
            },
            "metrics":{
              "raised": 1502450000,
              "employees": 1000,
              "googleRank": 7,
              "alexaGlobalRank": 2319,
              "marketCap": null
            },
          },
          "person":{
            "name":{
              "fullName": "Bob Kramer"
            },
            "employment":{
              "name": "Example Company"
            }
          }
        },
        "custom":{
          "CAC": 213,
          "utmCampaign": "social media 1",
          "convertedAt": "2015-09-08 00:00:00",
          "pro": false,
          "salesRep": "Gabi"
        }
      },
      "address":{
        "address_zip": "0185128",
        "city": "Nowhereville",
        "country": "US",
        "state": "Alaska"
      },
      "mrr": 3000,
      "arr": 36000,
      "billing-system-url": "https:\/\/dashboard.stripe.com\/customers\/cus_4Z2ZpyJFuQ0XMb",
      "chartmogul-url": "https:\/\/app.chartmogul.com\/#customers\/25647-Example_Company",
      "billing-system-type": "Stripe",
      "currency": "USD",
      "currency-sign": "$"
    },
    {"...49 more...": "...entries..."}
  ],
  "has_more": true,
  "per_page": 50,
  "page": 1,
  "current_page": 1,
  "total_pages": 4
}
#<ChartMogul::Customers:0x007fe7e09ca7c8 
@entries=[
  #<ChartMogul::Customer:0x007fe7e09ca408 
  @id=21064118, 
  @uuid="cus_2f9cfa3f-92d3-4801-9c9e-315fc2b61121", 
  @external_id="cus_0001", 
  @name="Adam Smith", 
  @email="[email protected]", 
  @status="Active", 
  @customer_since=2015-11-01 03:00:00 +0300, 
  @attributes={:tags=>[], :custom=>{}}, 
  @address={:country=>"United States", :state=>nil, :city=>"New York", :address_line1=>nil, :address_line2=>nil, :address_zip=>""}, 
  @mrr=4100, 
  @arr=49200, 
  @billing_system_url=nil, 
  @chartmogul_url="https://app.chartmogul.com/#customers/21064118-Adam_Smith", 
  @billing_system_type="ImportApi", 
  @currency="USD", 
  @currency_sign="$"
  >,
  # ... 49 more entries here ...
], 
@has_more=false, 
@per_page=50, 
@page=1
>
{
  "entries":[
    {
      "id": 25647,
      "uuid": "cus_de305d54-75b4-431b-adb2-eb6b9e546012",
      "external_id": "34916129",
      "name": "Example Company",
      "email": "[email protected]",
      "status": "Active",
      "customer-since": "2015-06-09T13:16:00-04:00",
      "attributes":{
        "tags": ["engage", "unit loss", "discountable"],
        "stripe":{
          "uid": 7,
          "coupon": true
        },
        "clearbit":{
      		"company":{
            "name": "Example Company",
            "legalName": "Example Company Inc.",
            "domain": "examplecompany.com",
            "url": "http://examplecompany.com",
            "category":{
              "sector": "Information Technology",
              "industryGroup": "Software and Services",
              "industry": "Software",
              "subIndustry": "Application Software"
            },
            "metrics":{
              "raised": 1502450000,
              "employees": 1000,
              "googleRank": 7,
              "alexaGlobalRank": 2319,
              "marketCap": null
            },
          },
          "person":{
            "name":{
              "fullName": "Bob Kramer"
            },
            "employment":{
              "name": "Example Company"
            }
          }
        },
        "custom":{
          "CAC": 213,
          "utmCampaign": "social media 1",
          "convertedAt": "2015-09-08 00:00:00",
          "pro": false,
          "salesRep": "Gabi"
        }
      },
      "address":{
        "address_line1": "First line of address",
        "address_line2": "Second line of address",
        "address_zip": "0185128",
        "city": "Nowhereville",
        "country": "US",
        "state": "Alaska"
      },
      "mrr": 3000,
      "arr": 36000,
      "billing-system-url": "https:\/\/dashboard.stripe.com\/customers\/cus_4Z2ZpyJFuQ0XMb",
      "chartmogul-url": "https:\/\/app.chartmogul.com\/#customers\/25647-Example_Company",
      "billing-system-type": "Stripe",
      "currency": "USD",
      "currency-sign": "$"
    },
    {"...49 more...": "...entries..."}
  ],
  "has_more": true,
  "per_page": 50,
  "page": 1
}
<?php
ChartMogul\Customers::__set_state(array(
    "current_page" => 1,
    "total_pages" => 3,
    "has_more" => true,
    "per_page" => 50,
    "page" => 1,
    "entries" =>
  Doctrine\Common\Collections\ArrayCollection::__set_state(array(
     "elements" =>
    array (
      0 =>
      ChartMogul\Customer::__set_state(array(
         "id" => 25647,
         "uuid" => "cus_de305d54-75b4-431b-adb2-eb6b9e546012",
         "external_id" => "34916129",
         "name" => "Example Company",
         "email" => "[email protected]",
         "status" => "Active",
         "customer_since" => "2015-06-09T13:16:00-04:00",
         "attributes" =>
        array (
          "custom" =>
          array (
            "CAC" => 213,
            "utmCampaign" => "social media 1",
            "convertedAt" => "2015-09-08 00 =>00 =>00",
            "pro" => false,
            "salesRep" => "Gabi"
          ),
          "clearbit" =>
          array (
            "id" => "027b0d40-016c-40ea-8925-a076fa640992",
            "name" => "Acme",
            "legalName" => "Acme Inc.",
            "domain" => "acme.com",
            "url" => "http =>//acme.com",
            "metrics" => array (
              "raised" => 1502450000,
              "employees" => 1000,
              "googleRank" => 7,
              "alexaGlobalRank" => 2319,
              "marketCap" => null
            ),
            "category" => array (
              "sector" => "Information Technology",
              "industryGroup" => "Software and Services",
              "industry" => "Software",
              "subIndustry" => "Application Software"
            )
          ),
          "stripe" =>
          array (
            "uid" => 7,
            "coupon" => true
          ),
          "tags" =>
          array (
            0 => "engage",
            1 => "unit loss",
            2 => "discountable"
          ),
        ),
         "address" =>
        array (
          "address_line1" => "First line of address",
          "address_line2" => "Second line of address",
          "address_zip" => "0185128",
          "city" => "Nowhereville",
          "state" => "Alaska",
          "country" => "US"
        ),
         "mrr" => 3000,
         "arr" => 36000,
         "billing_system_url" => "https:\/\/dashboard.stripe.com\/customers\/cus_4Z2ZpyJFuQ0XMb",
         "chartmogul_url" => "https:\/\/app.chartmogul.com\/#customers\/25647-Example_Company",
         "billing_system_type" => "Stripe",
         "currency" => "USD",
         "currency_sign" => "$",
         "data_source_uuid" => "ds_80686670-cc45-11e6-b9da-ff67b9895fe3",
         "data_source_uuids" =>
        array (
          0 => "ds_80686670-cc45-11e6-b9da-ff67b9895fe3",
        ),
         "external_ids" =>
        array (
          0 => "cus_0001",
        ),
         "city" => "Nowhereville",
         "country" => "US",
         "state" => "Alaska",
         "zip" => "0185128",
         "lead_created_at" => "2015-10-14T00:00:00.000Z",
         "free_trial_started_at" => "2015-11-01T00:00:00.000Z",
         "company" => "",
    )),
    "many more" => "..."
  )))
));
?>
(*chartmogul.Customers)(0xc042088b40)({
 Entries: ([]*chartmogul.Customer) (len=2) {
  (*chartmogul.Customer)(0xc0421e6160)({
   ID: (uint32) 4861688,
   DataSourceUUID: (string) (len=39) "ds_9bb53a1e-edfd-11e6-bf83-af49e978cb11",
   UUID: (string) (len=40) "cus_c0dc8d74-edfd-11e6-a357-832dddba822f",
   ExternalID: (string) (len=8) "cus_0001",
   Name: (string) (len=10) "Adam Smith",
   Email: (string) (len=14) "[email protected]",
   Status: (string) (len=4) "Lead",
   CustomerSince: (string) "",
   Attributes: (*chartmogul.Attributes)(0xc042006600)({
    Tags: ([]string) {
    },
    Stripe: (*chartmogul.Stripe)(0xc04200c4c0)({
     UID: (uint64) 0,
     Coupon: (bool) false
    }),
    Clearbit: (*chartmogul.Clearbit)(0xc042110060)({
     ID: (string) "",
     Name: (string) "",
     LegalName: (string) "",
     Domain: (string) "",
     URL: (string) "",
     Metrics: (map[string]interface {}) <nil>,
     Category: (*chartmogul.Category)(<nil>)
    }),
    Custom: (map[string]interface {}) {
    }
   }),
   Address: (*chartmogul.Address)(0xc042008440)({
    AddressZIP: (string) "",
    City: (string) (len=8) "New York",
    State: (string) "",
    Country: (string) (len=13) "United States"
   }),
   Mrr: (float64) 0,
   Arr: (float64) 0,
   BillingSystemURL: (string) "",
   ChartmogulURL: (string) (len=56) "https://app.chartmogul.com/#customers/4861688-Adam_Smith",
   BillingSystemType: (string) (len=10) "Import API",
   Currency: (string) (len=3) "USD",
   CurrencySign: (string) (len=1) "$",
   Company: (string) "",
   Country: (string) (len=2) "US",
   State: (string) "",
   City: (string) (len=8) "New York",
   LeadCreatedAt: (string) (len=24) "2015-10-14T00:00:00.000Z",
   FreeTrialStartedAt: (string) (len=24) "2015-11-01T00:00:00.000Z",
   Errors: (chartmogul.Errors) chartmogul: map[]
  }),
  (*chartmogul.Customer)(0xc0421e66e0)({
   ID: (uint32) 4863286,
   DataSourceUUID: (string) (len=39) "ds_9bb53a1e-edfd-11e6-bf83-af49e978cb11",
   UUID: (string) (len=40) "cus_99529720-edfe-11e6-8773-13ec140c2da5",
   ExternalID: (string) (len=8) "cus_0002",
   Name: (string) (len=10) "Adam Smith",
   Email: (string) (len=14) "[email protected]",
   Status: (string) (len=4) "Lead",
   CustomerSince: (string) "",
   Attributes: (*chartmogul.Attributes)(0xc0420068d0)({
    Tags: ([]string) {
    },
    Stripe: (*chartmogul.Stripe)(0xc04200c5c0)({
     UID: (uint64) 0,
     Coupon: (bool) false
    }),
    Clearbit: (*chartmogul.Clearbit)(0xc0421100c0)({
     ID: (string) "",
     Name: (string) "",
     LegalName: (string) "",
     Domain: (string) "",
     URL: (string) "",
     Metrics: (map[string]interface {}) <nil>,
     Category: (*chartmogul.Category)(<nil>)
    }),
    Custom: (map[string]interface {}) {
    }
   }),
   Address: (*chartmogul.Address)(0xc0420084c0)({
    AddressZIP: (string) "",
    City: (string) (len=8) "New York",
    State: (string) "",
    Country: (string) (len=13) "United States"
   }),
   Mrr: (float64) 0,
   Arr: (float64) 0,
   BillingSystemURL: (string) "",
   ChartmogulURL: (string) (len=56) "https://app.chartmogul.com/#customers/4863286-Adam_Smith",
   BillingSystemType: (string) (len=10) "Import API",
   Currency: (string) (len=3) "USD",
   CurrencySign: (string) (len=1) "$",
   Company: (string) "",
   Country: (string) (len=2) "US",
   State: (string) "",
   City: (string) (len=8) "New York",
   LeadCreatedAt: (string) (len=24) "2015-10-14T00:00:00.000Z",
   FreeTrialStartedAt: (string) (len=24) "2015-11-01T00:00:00.000Z",
   Errors: (chartmogul.Errors) chartmogul: map[]
  })
 },
 Page: (uint32) 1,
 PerPage: (uint32) 2,
 HasMore: (bool) true,
 CurrentPage: (int32) 1,
 TotalPages: (int32) 7
})
Customers(entries=[<Customer{
    address=<Address{
        address_zip=None,
        city='New York',
        country='United States',
        state=None}>,
    arr=0.0,
    attributes=<Attributes{
        clearbit=<Clearbit{
        }>,
        custom={
        },
        stripe=<Stripe{
        }>,
        tags=[]}>,
    billing_system_type='Import API',
    billing_system_url=None,
    chartmogul_url='https://app.chartmogul.com/#customers/4861688-Adam_Smith',
    city='New York',
    company='',
    country='US',
    currency='USD',
    currency_sign='$',
    customer_since=None,
    data_source_uuid='ds_9bb53a1e-edfd-11e6-bf83-af49e978cb11',
    data_source_uuids=['ds_9bb53a1e-edfd-11e6-bf83-af49e978cb11'],
    email=[email protected]',
    external_id='cus_0001',
    external_ids=['cus_0001'],
    free_trial_started_at=datetime.datetime(2015, 11, 1, 0, 0),
    id=4861688,
    lead_created_at=datetime.datetime(2015, 10, 14, 0, 0),
    mrr=0.0,
    name='Adam Smith',
    state=None,
    status='Lead',
    uuid='cus_c0dc8d74-edfd-11e6-a357-832dddba822f',
    zip=None}>,
<Customer{
    address=<Address{
    address_zip=None,
    city='New York',
    country='United States',
    state=None}>,
    arr=0.0,
    attributes=<Attributes{
        clearbit=<Clearbit{
        }>,
        custom={
        },
        stripe=<Stripe{
        }>,
        tags=[]}>,
    billing_system_type='Import API',
    billing_system_url=None,
    chartmogul_url='https://app.chartmogul.com/#customers/4863286-Adam_Smith',
    city='New York',
    company='',
    country='US',
    currency='USD',
    currency_sign='$',
    customer_since=None,
    data_source_uuid='ds_9bb53a1e-edfd-11e6-bf83-af49e978cb11',
    data_source_uuids=['ds_9bb53a1e-edfd-11e6-bf83-af49e978cb11'],
    email=[email protected]',
    external_id='cus_0002',
    external_ids=['cus_0002'],
    free_trial_started_at=datetime.datetime(2015, 11, 1, 0, 0),
    id=4863286,
    lead_created_at=datetime.datetime(2015, 10, 14, 0, 0),
    mrr=0.0,
    name='Adam Smith',
    state=None,
    status='Lead',
    uuid='cus_99529720-edfe-11e6-8773-13ec140c2da5',
    zip=None}>],
has_more=True,
per_page=2,
page=1,
current_page=1,
total_pages=7)
Suggest Edits

Plans

This object represents a subscription billing plan for products or services that you offer your customers.

 

For example, you might have a $50 monthly plan with a set of features, and a $500 annual plan.

If you are unfamiliar with the concept of a subscription plan, think of it as any product or service that has a specific recurring billing period. For example, you may offer Custom branding as an add-on feature in your SaaS product at $25/month. In this case, you would create a plan object with the name "Custom branding" in ChartMogul, and a billing interval of 1 month.

Suggest Edits

Create a Plan

Creates a plan object in ChartMogul under the specified data_source.

 
posthttps://api.chartmogul.com/v1/plans

Form Data

data_source_uuid
string
required

The ChartMogul UUID of the data source for this subscription plan.

name
string
required

Display name of the plan. Accepts alphanumeric characters.

interval_count
int32
required

The frequency of billing interval. Accepts integers greater than 0. eg. 6 for a half-yearly plan.

interval_unit
string
required

The unit of billing interval. One of day, month, or year. eg. month for the above half-yearly plan.

external_id
string

A unique identifier specified by you for the plan. Typically an identifier from your internal system. Accepts alphanumeric characters.

 

In the response, the JSON object contains the following data:

  • uuid - The UUID of the plan object generated by ChartMogul.
  • data_source_uuid - The UUID of the data source that this subscription plan belongs to.
  • name - Name of this plan, as specified by you.
  • interval_count - The number of intervals (specified in the interval_unit attribute) between each billing date.
  • interval_unit - The frequency with which a subscription for this plan is billed. For example, if you bill your customer every 3 months for a subscription with this plan, then interval_count would be 3 and interval_unit would be month.
  • external_id - The unique external identifier for this plan, as specified by you.

Examples

curl -X POST "https://api.chartmogul.com/v1/plans" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_KEY \
     -H "Content-Type: application/json" \
     -d '{ 
           "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
           "name": "Bronze Plan",
           "interval_count": 1,
           "interval_unit": "month",
           "external_id": "plan_0001"
         }'
ChartMogul::Plan.create!(
  data_source_uuid: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  name: "Bronze Plan",
  interval_count: 1,
  interval_unit: "month",
  external_id: "plan_0001"
)
ChartMogul.Plan.create(config, { 
      "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
      "name": "Bronze Plan",
      "interval_count": 1,
      "interval_unit": "month",
      "external_id": "plan_0001"
    }, function (err, res) {
    // asynchronously called
});
<?php

ChartMogul\Plan::create([
    "data_source_uuid" => "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
    "name" => "Bronze Plan",
    "interval_count" => 1,
    "interval_unit" => "month",
    "external_id" => "plan_0001"
]);
?>
api.CreatePlan(&cm.Plan{
  DataSourceUUID: "ds_9bb53a1e-edfd-11e6-bf83-af49e978cb11",
  Name:           "Bronze Plan",
  IntervalCount:  1,
  IntervalUnit:   "month",
  ExternalID:     "plan_0001",
})
chartmogul.Plan.create(
  config,
  data={
    "data_source_uuid": "ds_9bb53a1e-edfd-11e6-bf83-af49e978cb11",
    "name": "Awesome Plan",
    "interval_count": 1,
    "interval_unit": "month",
    "external_id": "plan_0004"
  })

Result Format

{
   "uuid": "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
   "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
   "name": "Bronze Plan",
   "interval_count": 1,
   "interval_unit": "month",
   "external_id": "plan_0001"
}
#<ChartMogul::Plan:0x007fb4993f25a0 
@uuid="pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
@data_source_uuid="ds_fef05d54-47b4-431b-aed2-eb6b9e545430", 
@name="Bronze Plan", 
@interval_count=1, 
@interval_unit="month", 
@external_id="plan_0001"
>
{
   "uuid": "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
   "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
   "name": "Bronze Plan",
   "interval_count": 1,
   "interval_unit": "month",
   "external_id": "plan_0001"
}
<?php

ChartMogul\Plan::__set_state(array(
   "uuid" => "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
   "name" => "Bronze Plan",
   "interval_count" => 1,
   "interval_unit" => "month",
   "external_id" => "plan_0001",
   "data_source_uuid" => "ds_7f38c0d0-cc2f-11e6-91c9-5b7dd3da2e7a"
));
?>
(*chartmogul.Plan)(0xc04203e5a0)({
 UUID: (string) (len=39) "pl_9599eaf6-ee09-11e6-ae39-c7c8fe81e14e",
 DataSourceUUID: (string) (len=39) "ds_9bb53a1e-edfd-11e6-bf83-af49e978cb11",
 ExternalID: (string) (len=9) "plan_0001",
 Name: (string) (len=11) "Bronze Plan",
 IntervalCount: (uint32) 1,
 IntervalUnit: (string) (len=5) "month"
})
<Plan{
    data_source_uuid='ds_9bb53a1e-edfd-11e6-bf83-af49e978cb11',
    external_id='plan_0004',
    interval_count=1,
    interval_unit='month',
    name='Awesome Plan',
    uuid='pl_86382dae-ee0c-11e6-ba5f-d71bf57a88d3'}>
Suggest Edits

Retrieve a Plan

Retrieves a plan object from your ChartMogul account.

 
gethttps://api.chartmogul.com/v1/plans/PLAN_UUID

Path Params

plan_uuid
string
required

The ChartMogul UUID of the plan to be retrieved.

 

In the response, the JSON object contains the following data:

  • uuid - The UUID of the plan object generated by ChartMogul.
  • data_source_uuid - The UUID of the data source that this subscription plan belongs to.
  • name - Name of this plan, as specified by you.
  • interval_count - The number of intervals (specified in the interval_unit attribute) between each billing date.
  • interval_unit - The frequency with which a subscription for this plan is billed. For example, if you bill your customer every 3 months for a subscription with this plan, then interval_count would be 3 and interval_unit would be month.
  • external_id - The unique external identifier for this plan, as specified by you.

Examples

curl -X GET "https://api.chartmogul.com/v1/plans/pl_eed05d54-75b4-431b-adb2-eb6b9e543206" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_KEY \
     -H "Content-Type: application/json"
ChartMogul::Plan.retrieve('pl_eed05d54-75b4-431b-adb2-eb6b9e543206')
ChartMogul.Plan.retrieve(config, "pl_eed05d54-75b4-431b-adb2-eb6b9e543206", function(err, res) {
   // asynchronously called
});
<?php

ChartMogul\Plan::retrieve("pl_eed05d54-75b4-431b-adb2-eb6b9e543206");

?>
api.RetrievePlan("pl_eed05d54-75b4-431b-adb2-eb6b9e543206")
chartmogul.Plan.retrieve(config, uuid='pl_eed05d54-75b4-431b-adb2-eb6b9e543206')

Result Format

{
   "uuid": "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
   "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
   "name": "Bronze Plan",
   "interval_count": 1,
   "interval_unit": "month",
   "external_id": "plan_0001"
}
#<ChartMogul::Plan:0x007fb4993f25a0 
@uuid="pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
@data_source_uuid="ds_fef05d54-47b4-431b-aed2-eb6b9e545430", 
@name="Bronze Plan", 
@interval_count=1, 
@interval_unit="month", 
@external_id="plan_0001"
>
{
   "uuid": "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
   "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
   "name": "Bronze Plan",
   "interval_count": 1,
   "interval_unit": "month",
   "external_id": "plan_0001"
}
<?php

ChartMogul\Plan::__set_state(array(
   "uuid" => "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
   "name" => "Bronze Plan",
   "interval_count" => 1,
   "interval_unit" => "month",
   "external_id" => "plan_0001",
   "data_source_uuid" => "ds_7f38c0d0-cc2f-11e6-91c9-5b7dd3da2e7a"
));
?>
(*chartmogul.Plan)(0xc04203e5a0)({
 UUID: (string) (len=39) "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
 DataSourceUUID: (string) (len=39) "ds_7f38c0d0-cc2f-11e6-91c9-5b7dd3da2e7a",
 ExternalID: (string) (len=9) "plan_0001",
 Name: (string) (len=11) "Bronze Plan",
 IntervalCount: (uint32) 1,
 IntervalUnit: (string) (len=5) "month"
})
<Plan{
    data_source_uuid='ds_9bb53a1e-edfd-11e6-bf83-af49e978cb11',
    external_id='plan_0004',
    interval_count=1,
    interval_unit='month',
    name='Awesome Plan',
    uuid='pl_eed05d54-75b4-431b-adb2-eb6b9e543206'}>
Suggest Edits

Update a Plan

Updates a plan object in your ChartMogul account.

 
patchhttps://api.chartmogul.com/v1/plans/PLAN_UUID

Path Params

plan_uuid
string
required

The ChartMogul UUID of the plan to be updated.

Form Data

name
string

Display name of the plan. Accepts alphanumeric characters.

interval_count
int32

The frequency of billing interval. Accepts integers greater than 0. eg. 6 for a half-yearly plan. Modifiable only if not already referenced by a subscription and/or invoice.

interval_unit
string

The unit of billing interval. One of day, month, or year. eg. month for the above half-yearly plan. Modifiable only if not already referenced by a subscription and/or invoice.

 

In the response, the JSON object contains the following data:

  • uuid - The UUID of the plan object generated by ChartMogul.
  • data_source_uuid - The UUID of the data source that this subscription plan belongs to.
  • name - Name of this plan, as specified by you.
  • interval_count - The number of intervals (specified in the interval_unit attribute) between each billing date.
  • interval_unit - The frequency with which a subscription for this plan is billed. For example, if you bill your customer every 3 months for a subscription with this plan, then interval_count would be 3 and interval_unit would be month.
  • external_id - The unique external identifier for this plan, as specified by you.

Examples

curl -X PATCH "https://api.chartmogul.com/v1/plans/pl_eed05d54-75b4-431b-adb2-eb6b9e543206" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_KEY \
     -H "Content-Type: application/json"
     -d '{ 
           "name": "Bronze Monthly Plan"
         }'
plan = ChartMogul::Plan.retrieve("pl_eed05d54-75b4-431b-adb2-eb6b9e543206")

plan.name = "Bronze Monthly Plan"

plan.update!
ChartMogul.Plan.modify(config, "pl_eed05d54-75b4-431b-adb2-eb6b9e543206", {
    name: "Bronze Monthly Plan"
})
<?php

ChartMogul\Plan::update([
    'plan_uuid' => "pl_eed05d54-75b4-431b-adb2-eb6b9e543206"
        ], [
    "name" => "Bronze Monthly Plan",
]);
?>
api.UpdatePlan(&cm.Plan{
  Name: "Bronze Monthly Plan",
}, "pl_eed05d54-75b4-431b-adb2-eb6b9e543206")
chartmogul.Plan.modify(
    config,
    uuid="pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
    data={
      "name": "Bronze Monthly Plan"
    })

Result Format

{
   "uuid": "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
   "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
   "name": "Bronze Plan",
   "interval_count": 1,
   "interval_unit": "month",
   "external_id": "plan_0001"
}
#<ChartMogul::Plan:0x007fb4993f25a0 
@uuid="pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
@data_source_uuid="ds_fef05d54-47b4-431b-aed2-eb6b9e545430", 
@name="Bronze Monthly Plan", 
@interval_count=1, 
@interval_unit="month", 
@external_id="plan_0001"
>
{
   "uuid": "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
   "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
   "name": "Bronze Monthly Plan",
   "interval_count": 1,
   "interval_unit": "month",
   "external_id": "plan_0001"
}
<?php

ChartMogul\Plan::__set_state(array(
   "uuid" => "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
   "name" => "Bronze Monthly Plan",
   "interval_count" => 1,
   "interval_unit" => "month",
   "external_id" => "plan_0001",
   "data_source_uuid" => "ds_7f38c0d0-cc2f-11e6-91c9-5b7dd3da2e7a"
));
?>
(*chartmogul.Plan)(0xc04203e5a0)({
 UUID: (string) (len=39) "pl_9599eaf6-ee09-11e6-ae39-c7c8fe81e14e",
 DataSourceUUID: (string) (len=39) "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
 ExternalID: (string) (len=9) "plan_0001",
 Name: (string) (len=11) "Bronze Monthly Plan",
 IntervalCount: (uint32) 1,
 IntervalUnit: (string) (len=5) "month"
})
<Plan{
    data_source_uuid='pl_eed05d54-75b4-431b-adb2-eb6b9e543206',
    external_id='plan_0004',
    interval_count=1,
    interval_unit='month',
    name='Bronze Monthly Plan',
    uuid='pl_eed05d54-75b4-431b-adb2-eb6b9e543206'}>
Suggest Edits

Delete a Plan

Deletes a plan object from your ChartMogul account.

 
deletehttps://api.chartmogul.com/v1/plans/PLAN_UUID

Path Params

plan_uuid
string
required

The ChartMogul UUID of the plan to be deleted.

 

Conditions and impact of this action

Only plans belonging to data sources based on the Import API can be deleted. Deleting a plan will only remove the plan object, and only if it isn't referenced by any subscriptions or invoices.

Examples

curl -X DELETE "https://api.chartmogul.com/v1/plans/pl_eed05d54-75b4-431b-adb2-eb6b9e543206" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_KEY \
     -H "Content-Type: application/json"
plans = ChartMogul::Plan.all
plan = plans.last
plan.destroy!
ChartMogul.Plan.destroy(config, "pl_eed05d54-75b4-431b-adb2-eb6b9e543206", function (err, res) {
   // aysnchronously called
});
<?php

ChartMogul\Plan::all()->last()->destroy();
?>
api.DeletePlan("pl_eed05d54-75b4-431b-adb2-eb6b9e543206")
chartmogul.Plan.destroy(config, uuid='pl_eed05d54-75b4-431b-adb2-eb6b9e543206')

Result Format

{ }
true
{ }
true
nil
None
Suggest Edits

List Plans

Returns a list of plan objects in your ChartMogul account.

 
gethttps://api.chartmogul.com/v1/plans

Query Params

data_source_uuid
string

An optional filter parameter, for the ChartMogul UUID of the data source to which the desired plans belong.

external_id
string

An optional filter parameter, for the unique external identifier of the desired plan.

system
string

An optional filter parameter, for the billing system that the plan belongs to. For example, Stripe, Recurly, Chargify, or Import API.

page
int32

The page number for pagination of results.

per_page
int32

A limit on number of plans to return per page. The default and maximum value is 200.

 

In the response, plans contains an array of plan objects with the following data:

  • uuid - The UUID of the plan object generated by ChartMogul.
  • data_source_uuid - The UUID of the data source that this subscription plan belongs to.
  • name - Name of this plan, as specified by you.
  • interval_count - The number of intervals (specified in the interval_unit attribute) between each subscription billing.
  • interval_unit - The frequency with which a subscription for this plan is billed. For example, if you bill your customer every 3 months for a subscription with this plan, then interval_count would be 3 and interval_unit would be month.
  • external_id - The unique external identifier for this plan, as specified by you.

The other keys represent pagination attributes:

  • total_pages - The total number of pages with results for this request.
  • current_page - The page number of this response.

Examples

curl -X GET "https://api.chartmogul.com/v1/plans?per_page=3&data_source_uuid=ds_fef05d54-47b4-431b-aed2-eb6b9e545430" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_KEY
ChartMogul::Plan.all(page: 1, per_page: 200)
ChartMogul.Plan.all(config, function (err, res) {
 // asynchronously called
});
<?php

ChartMogul\Plan::all(["per_page" => 3]);
?>
api.ListPlans(&cm.ListPlansParams{Cursor: cm.Cursor{PerPage: 3}})
chartmogul.Plan.all(config, per_page=3)

Result Format

{
  "plans":[
    {
      "uuid": "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
      "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
      "name": "Bronze Plan",
      "interval_count": 1,
      "interval_unit": "month",
      "external_id": "plan_0001"
    },
    {
      "uuid": "pl_cdb35d54-75b4-431b-adb2-eb6b9e873425",
      "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
      "name": "Silver Plan",
      "interval_count": 6,
      "interval_unit": "month",
      "external_id": "plan_0002"
    },
    {
      "uuid": "pl_ab225d54-7ab4-421b-cdb2-eb6b9e553462",
      "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
      "name": "Gold Plan",
      "interval_count": 1,
      "interval_unit": "year",
      "external_id": "plan_0003"
    }
  ],
  "current_page": 1,
  "total_pages": 2
}
#<ChartMogul::Plans:0x00000003eb9e18
 @plans=
  [#<ChartMogul::Plan:0x007fb4993f25a0 
    @uuid="pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
    @data_source_uuid="ds_fef05d54-47b4-431b-aed2-eb6b9e545430", 
    @name="Bronze Plan", 
    @interval_count=1,
    @interval_unit="month",
    @external_id="plan_0001"
    >,
    #<ChartMogul::Plan:0x007fb4993f25a0 
    @uuid="pl_cdb35d54-75b4-431b-adb2-eb6b9e873425",
    @data_source_uuid="ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
    @name="Silver Plan",
    @interval_count=6,
    @interval_unit="month",
    @external_id="plan_0002"
    >,
    #<ChartMogul::Plan:0x007fb4993f25a0 
    @uuid="pl_ab225d54-7ab4-421b-cdb2-eb6b9e553462",
    @data_source_uuid="ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
    @name="Gold Plan",
    @interval_count=1,
    @interval_unit="year",
    @external_id="plan_0003"
    >
	],
 @current_page=1,
 @total_pages=1>
{
  "plans":[
    {
      "uuid": "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
      "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
      "name": "Bronze Plan",
      "interval_count": 1,
      "interval_unit": "month",
      "external_id": "plan_0001"
    },
    {
      "uuid": "pl_cdb35d54-75b4-431b-adb2-eb6b9e873425",
      "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
      "name": "Silver Plan",
      "interval_count": 6,
      "interval_unit": "month",
      "external_id": "plan_0002"
    },
    {
      "uuid": "pl_ab225d54-7ab4-421b-cdb2-eb6b9e553462",
      "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
      "name": "Gold Plan",
      "interval_count": 1,
      "interval_unit": "year",
      "external_id": "plan_0003"
    }
  ],
  "current_page": 1,
  "total_pages": 2
}
<?php

Doctrine\Common\Collections\ArrayCollection::__set_state(array(
   "elements" => 
  array (
    0 => 
    ChartMogul\Plan::__set_state(array(
       "uuid" => "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
       "name" => "Bronze Plan",
       "interval_count" => 1,
       "interval_unit" => "month",
       "external_id" => "plan_0001",
       "data_source_uuid" => "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
    )),
    1 => 
    ChartMogul\Plan::__set_state(array(
       "uuid" => "pl_cdb35d54-75b4-431b-adb2-eb6b9e873425",
       "name" => "Silver Plan",
       "interval_count" => 6,
       "interval_unit" => "month",
       "external_id" => "plan_0002",
       "data_source_uuid" => "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
    )),
    2 => 
    ChartMogul\Plan::__set_state(array(
       "uuid" => "pl_ab225d54-7ab4-421b-cdb2-eb6b9e553462",
       "name" => "Gold Plan",
       "interval_count" => 1,
       "interval_unit" => "year",
       "external_id" => "plan_0003",
       "data_source_uuid" => "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
    )),
  ),
  "current_page" => 1,
  "total_pages" => 2
));
?>
(*chartmogul.Plans)(0xc0420b0f60)({
 Plans: ([]*chartmogul.Plan) (len=3) {
  (*chartmogul.Plan)(0xc04201aae0)({
   UUID: (string) (len=39) "pl_86382dae-ee0c-11e6-ba5f-d71bf57a88d3",
   DataSourceUUID: (string) (len=39) "ds_9bb53a1e-edfd-11e6-bf83-af49e978cb11",
   ExternalID: (string) (len=9) "plan_0004",
   Name: (string) (len=12) "Awesome Plan",
   IntervalCount: (uint32) 1,
   IntervalUnit: (string) (len=5) "month"
  }),
  (*chartmogul.Plan)(0xc04201ab40)({
   UUID: (string) (len=39) "pl_8da1caec-ee0b-11e6-a4d9-dbe62a1a1694",
   DataSourceUUID: (string) (len=39) "ds_9bb53a1e-edfd-11e6-bf83-af49e978cb11",
   ExternalID: (string) (len=9) "plan_0002",
   Name: (string) (len=9) "Gold Plan",
   IntervalCount: (uint32) 1,
   IntervalUnit: (string) (len=5) "month"
  }),
  (*chartmogul.Plan)(0xc04201aba0)({
   UUID: (string) (len=39) "pl_9599eaf6-ee09-11e6-ae39-c7c8fe81e14e",
   DataSourceUUID: (string) (len=39) "ds_9bb53a1e-edfd-11e6-bf83-af49e978cb11",
   ExternalID: (string) (len=9) "plan_0001",
   Name: (string) (len=11) "Bronze Plan",
   IntervalCount: (uint32) 1,
   IntervalUnit: (string) (len=5) "month"
  })
 },
 TotalPages: (uint32) 1,
 CurrentPage: (uint32) 1
})
Plans(plans=[
    <Plan{
        data_source_uuid='ds_9bb53a1e-edfd-11e6-bf83-af49e978cb11',
        external_id='plan_0004',
        interval_count=1,
        interval_unit='month',
        name='Awesome Plan',
        uuid='pl_86382dae-ee0c-11e6-ba5f-d71bf57a88d3'}>,
    <Plan{
        data_source_uuid='ds_9bb53a1e-edfd-11e6-bf83-af49e978cb11',
        external_id='plan_0002',
        interval_count=1,
        interval_unit='month',
        name='Gold Plan',
        uuid='pl_8da1caec-ee0b-11e6-a4d9-dbe62a1a1694'}>,
    <Plan{
        data_source_uuid='ds_9bb53a1e-edfd-11e6-bf83-af49e978cb11',
        external_id='plan_0001',
        interval_count=1,
        interval_unit='month',
        name='Bronze Plan',
        uuid='pl_9599eaf6-ee09-11e6-ae39-c7c8fe81e14e'}>],
current_page=1,
total_pages=1)
Suggest Edits

Invoices

Invoices are crucial objects in ChartMogul. We auto-generate subscriptions and metrics from the information contained in these objects.

 

They contain information about the customer who was billed, the items that were included, and the transactions related to the invoice.

Pay close attention to the construction of this object.

Line Items

Invoices must contain an array of one or more line items that were billed. Line item objects represent the kind of product or service being billed, and relevant details about them.

Transactions

Invoices usually always contain an array of one or more transactions. Transaction objects represent payment or refund attempts related to the invoice.

Suggest Edits

Import Invoices

Creates invoices for a given API customer. ChartMogul auto-generates subscription objects from these invoices.

 
posthttps://api.chartmogul.com/v1/import/customers/CUSTOMER_UUID/invoices

Path Params

customer_uuid
string
required

The ChartMogul UUID of the Customer that these invoices belong to.

Form Data

external_id
string
required

A unique identifier specified by you for the invoice. Typically the Invoice Number in your system. Accepts alphanumeric characters.

date
date-time
required

The date on which this invoice was raised. Must be an ISO 8601 formatted time. The timezone defaults to UTC unless otherwise specified. The time defaults to 00:00:00 unless specified otherwise.

currency
string
required

The 3-letter currency code of the currency in which this invoice is being billed, e.g. USD, EUR, GBP. You can refer to our full list of supported currencies.

line_items
array
required

A list of Line Item objects. See table below for Line Item attributes.

transactions
array

A list of Transaction objects. See table below for Transaction attributes.

due_date
date-time

The date within which this invoice must be paid. Must be an ISO 8601 formatted time. The timezone defaults to UTC unless otherwise specified. The time defaults to 00:00:00 unless specified otherwise.

 

Line Item Attributes

The table below lists the expected parameters for every line_item object that is included in an invoice object.

Attribute
Required?
Datatype
Description

type

Yes

String

One of either subscription or one_time.

subscription_external_id

Yes, for subscription line items.
Irrelevant for one_time line items.

String

A reference identifier for the subscription in your system. Accepts alphanumeric characters.

plan_uuid

Yes, for subscription line items.
Optional for one_time line items.

String

The ChartMogul UUID of the plan for which this subscription is being charged.

service_period_start

Yes, for subscription line items.
Irrelevant for one_time line items.

Timestamp

The start of the service period for which this subscription is being charged.

Must be an ISO 8601 formatted time. The timezone defaults to UTC unless otherwise specified. The time defaults to 00:00:00 unless specified otherwise.

service_period_end

Yes, for subscription line items.
Irrelevant for one_time line items.

Timestamp

The end of the service period for which this subscription is being charged.

Must be an ISO 8601 formatted time. The timezone defaults to UTC unless otherwise specified. The time defaults to 00:00:00 unless specified otherwise.

amount_in_cents

Yes

Integer

The final amount charged towards this line item, for the specified quantity and service period, after discounts and taxes have been applied. Expected in cents (or pence for GBP, etc.)

This is the amount that is primarily used to calculate MRR.

cancelled_at

No. Accepted for subscription line items.
Irrelevant for one_time line items.

Timestamp

If this subscription has been cancelled, the time of cancellation.

Must be an ISO 8601 formatted time. The timezone defaults to UTC unless otherwise specified. The time defaults to 00:00:00 unless otherwise specified.

prorated

No. Accepted for subscription line items.
Irrelevant for one_time line items.

Boolean

If this is a prorated charge, then set this attribute to true.

description

No. Accepted for one_time line items.
Ignored for subscription line items.

String

A short description of the non-recurring item being charged to the customer.

quantity

No

Integer

The quantity of this line item being billed. Can be any non-zero integer. Defaults to 1.

Quantity value does not impact calculation of MRR.

discount_amount_in_cents

No

Integer

If any discount has been applied to this line item, then the discount amount in cents. Defaults to 0.

Discount amount does not impact calculation of MRR.

discount_code

No

String

If a discount has been applied to this line item, then an optional reference code to identify the discount.

tax_amount_in_cents

No

Integer

The tax that has been applied to this line item, in cents. Defaults to 0.

If specified, we exclude tax amount from MRR.

external_id

No

String

A unique identifier specified by you for the line item. Typically an identifier from your internal system. Accepts alphanumeric characters.

account_code

No

String

The unique account code of this line item used for the purposes of accounting and revenue recognition. Also called "account number" in some systems. Accepts a maximum of 30 alphanumeric characters.

Transaction Attributes

The table below lists the expected parameters for every transaction object that is included in an invoice object.

Attribute
Required?
Datatype
Description

date

Yes

Timestamp

The timestamp of when the transaction was attempted.

Must be an ISO 8601 formatted time. The timezone defaults to UTC unless otherwise specified. The time defaults to 00:00:00 unless specified otherwise.

type

Yes

String

Either one of payment or refund.

result

Yes

String

Either one of successful or failed.

external_id

No

String

A unique identifier specified by you for the transaction. Typically an identifier from your internal system. Accepts alphanumeric characters.

Invoice total

The invoice total is calculated with the following basic formula:
SUM of (amount_in_cents of each line_item on the invoice)

We assume that the transaction amount is always equal to the Invoice total, therefore there's no need to specify an amount in transaction objects.

MRR Calculation

ChartMogul uses several attributes from invoices to calculate MRR. Below, we describe some of the attributes in the context of their impact on MRR calculations.

  • Amount paid - The amount paid for a subscription is the primary driver in calculating MRR. In the Import API, this is represented by the amount_in_cents attribute.
  • Plans - With monthly plans the MRR is simply the price paid each month for the subscription. If customers are paying for plans with longer billing intervals (e.g. 12 months) ChartMogul simply divides the amount paid for the subscription by the number of months in the subscription period.
  • Discounts - We assume that discounts have already been deducted from the specified amount_in_cents value. For this reason, if discount_amount_in_cents is specified it doesn’t impact MRR but enables more detailed analysis in ChartMogul.
  • Taxes - Taxes must be excluded from the calculation of MRR. If specified, tax_amount_in_cents is used to deduct the tax prior to the calculation of MRR.
  • Quantity - Subscription quantity does not factor in the calculation of MRR. If specified, quantity is used to generate the Subscriptions Quantity and Quantity Churn Rate charts.
  • Prorated - Prorated items in invoices need to be explicitly identified for us to calculate their MRR contribution correctly. If specified as true, the prorated attribute impacts the calculation of MRR. For more details on how proration works, read our tutorial on adding pro-rated invoices.
  • One-time payments are excluded from MRR.

To give an example, let's imagine that:

  • Your customer Adam Smith buys 2 subscriptions to the Gold Monthly Plan.
  • Each Gold Monthly Plan is priced at $100 per month, including a $9 tax.
  • You provide a $20 discount on the total purchase amount.
  • Adam therefore pays $180 for this purchase.

These are the line item attributes for this example:

  • type: subscription
  • plan_uuid: The UUID of the Gold Monthly Plan
  • amount_in_cents: 18000
  • tax_amount_in_cents: 1800
  • discount_amount_in_cents: 2000
  • quantity: 2

In this scenario the MRR will be calculated as: ($180 - $18) = $162 MRR

What you need to know

  • Your data will be processed and reported faster if you send us batches of customer invoices with each request, instead of one invoice per request.
  • ChartMogul calculates MRR related metrics from invoice line items, and cash flow reports based on transaction information. If you send us an invoice with no transactions then there will be no contribution to cash flow from that invoice.
  • Currently, ChartMogul only allows you to import invoices for customers created using our API. This means that users cannot import invoices for customers created from one of our native integrations with Stripe, Braintree, Recurly, Chargify, or PayPal.
  • Once imported, it is not yet possible to edit or delete invoices or their line items and transactions. You will have to delete the customer that the invoice belongs to, and re-create the data once again.

Examples

curl -X POST "https://api.chartmogul.com/v1/import/customers/cus_f466e33d-ff2b-4a11-8f85-417eb02157a7/invoices" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_KEY \
     -H "Content-Type: application/json" \
     -d '{
     "invoices":[
       {
          "external_id": "INV0001",
          "date": "2015-11-01 00:00:00",
          "currency": "USD",
          "due_date": "2015-11-15 00:00:00",
          "line_items": [
            {
              "type": "subscription",
              "subscription_external_id": "sub_0001",
              "plan_uuid":"pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
              "service_period_start": "2015-11-01 00:00:00",
              "service_period_end": "2015-12-01 00:00:00",
              "amount_in_cents": 5000,
              "quantity": 1,
              "discount_code": "PSO86",
              "discount_amount_in_cents": 1000,
              "tax_amount_in_cents": 900
            },
            {
              "type": "one_time",
              "description": "Setup Fees",
              "amount_in_cents": 2500,
              "quantity": 1,
              "discount_code": "PSO86",
              "discount_amount_in_cents": 500,
              "tax_amount_in_cents": 450
            }
          ],
          "transactions": [
            {
              "date": "2015-11-05 00:14:23",
              "type": "payment",
              "result": "successful"
            }
          ]   
       }
     ]
     }'
customer = ChartMogul::Customer.all(external_id:"cus_0001").first
plan = ChartMogul::Plan.all(external_id:"plan_0001").first

line_item_1 = ChartMogul::LineItems::Subscription.new(
  subscription_external_id: "sub_0001",
  plan_uuid: plan.uuid,
  service_period_start: Time.utc(2015, 11, 1),
  service_period_end: Time.utc(2015, 12, 1),
  amount_in_cents: 5000,
  quantity: 1,
  discount_code: "PSO86",
  discount_amount_in_cents: 1000,
  tax_amount_in_cents: 900
)
line_item_2 = ChartMogul::LineItems::OneTime.new(
  description: "Setup Fees",
  amount_in_cents: 2500,
  quantity: 1,
  discount_code: "PSO86",
  discount_amount_in_cents: 500,
  tax_amount_in_cents: 450
)
transaction = ChartMogul::Transactions::Payment.new(
  date: Time.utc(2015, 11, 5, 0, 14, 23),
  result: 'successful'
)
invoice = ChartMogul::Invoice.new(
	external_id: 'INV0001',
  date: Time.utc(2015, 11, 1),
  currency: 'USD',
  due_date: Time.utc(2015, 11, 15),
  line_items: [line_item_1, line_item_2],
  transactions: [transaction]
)

ChartMogul::CustomerInvoices.create!(customer_uuid: customer.uuid, invoices: [invoice])
ChartMogul.Invoice.create(config,
   "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
   {
     "invoices":[
       {
          "external_id": "INV0001",
          "date": "2015-11-01 00:00:00",
          "currency": "USD",
          "due_date": "2015-11-15 00:00:00",
          "line_items": [
            {
              "type": "subscription",
              "subscription_external_id": "sub_0001",
              "plan_uuid":"pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
              "service_period_start": "2015-11-01 00:00:00",
              "service_period_end": "2015-12-01 00:00:00",
              "amount_in_cents": 5000,
              "quantity": 1,
              "discount_code": "PSO86",
              "discount_amount_in_cents": 1000,
              "tax_amount_in_cents": 900
            },
            {
              "type": "one_time",
              "description": "Setup Fees",
              "amount_in_cents": 2500,
              "quantity": 1,
              "discount_code": "PSO86",
              "discount_amount_in_cents": 500,
              "tax_amount_in_cents": 450
            }
          ],
          "transactions": [
            {
              "date": "2015-11-05 00:14:23",
              "type": "payment",
              "result": "successful"
            }
          ]   
       }
     ]
     },
   function (err, res) {
   // asynchronously called
});
<?php

$line_item1 = new ChartMogul\LineItems\Subscription([
    "subscription_external_id" => "sub_0001",
    "plan_uuid" => "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
    "service_period_start" => "2015-07-01T00:00:00.000Z",
    "service_period_end" => "2016-01-01T00:00:00Z",
    "amount_in_cents" => -5000,
    "quantity" => -10
]);
$line_item2 = new ChartMogul\LineItems\OneTime([
    "description" => "Setup Fees",
    "amount_in_cents" => 2500,
    "quantity" => 1,
    "discount_code" => "PSO86",
    "discount_amount_in_cents" => 500,
    "tax_amount_in_cents" => 450
]);
$transaction = new ChartMogul\Transactions\Payment([
    "date" => "2015-11-05 00:14:23",
    "result" => "successful"
]);
$invoice = new ChartMogul\Invoice([
    "external_id" => "INV0001",
    "date" => "2015-11-01 00:00:00",
    "due_date" => "2015-11-15 00:00:00",
    "currency" => "USD",
    "line_items" => [$line_item1, $line_item2],
    "transactions" => [$transaction]
]);
$ci = ChartMogul\CustomerInvoices::create([
            "customer_uuid" => $cu->uuid,
            "invoices" => [$invoice]
]);
?>
api.CreateInvoices([]*cm.Invoice{
  &cm.Invoice{
		ExternalID: "INV0002",
		Date:       "2015-11-01 00:00:00",
		Currency:   "USD",
		DueDate:    "2015-11-15 00:00:00",
		LineItems: []*cm.LineItem{
			&cm.LineItem{
				Type: 					"subscription",
				SubscriptionExternalID: "sub_0002",
				PlanUUID:               "pl_8da1caec-ee0b-11e6-a4d9-dbe62a1a1694",
				ServicePeriodStart:     "2015-11-01 00:00:00",
				ServicePeriodEnd:       "2015-12-01 00:00:00",
				AmountInCents:          5000,
				Quantity:               1,
				DiscountCode:           "PSO86",
				DiscountAmountInCents:  1000,
				TaxAmountInCents:       900,
			},
			&cm.LineItem{
				Type:                  "one_time",
				Description:           "Setup Fees",
				AmountInCents:         2500,
				Quantity:              1,
				DiscountCode:          "PSO86",
				DiscountAmountInCents: 500,
				TaxAmountInCents:      450,
			}},
		Transactions: []*cm.Transaction{
			&cm.Transaction{
				Date:   "2015-11-05 00:14:23",
				Type:   "payment",
				Result: "successful",
			}},
	}}, "cus_c0dc8d74-edfd-11e6-a357-832dddba822f")
import chartmogul

chartmogul.Invoice.create(
    config,
    uuid="cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
    data={
        "invoices": [
         {
             "external_id": "INV0001",
             "date": "2015-11-01 00:00:00",
             "currency": "USD",
             "due_date": "2015-11-15 00:00:00",
             "line_items": [
                 {
                     "type": "subscription",
                     "subscription_external_id": "sub_0001",
                     "plan_uuid": "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
                     "service_period_start": "2015-11-01 00:00:00",
                     "service_period_end": "2015-12-01 00:00:00",
                     "amount_in_cents": 5000,
                     "quantity": 1,
                     "discount_code": "PSO86",
                     "discount_amount_in_cents": 1000,
                     "tax_amount_in_cents": 900
                 },
                 {
                     "type": "one_time",
                     "description": "Setup Fees",
                     "amount_in_cents": 2500,
                     "quantity": 1,
                     "discount_code": "PSO86",
                     "discount_amount_in_cents": 500,
                     "tax_amount_in_cents": 450
                 }
             ],
             "transactions": [
                 {
                     "date": "2015-11-05 00:14:23",
                     "type": "payment",
                     "result": "successful"
                 }
             ]
         }
        ]
    })

Result Format

{
  "invoices": [
    {
      "uuid": "inv_565c73b2-85b9-49c9-a25e-2b7df6a677c9",
      "external_id": "INV0001",
      "date": "2015-11-01T00:00:00.000Z",
      "due_date": "2015-11-15T00:00:00.000Z",
      "currency": "USD",
      "line_items": [
        {
          "uuid": "li_d72e6843-5793-41d0-bfdf-0269514c9c56",
          "external_id": null,
          "type": "subscription",
          "subscription_uuid": "sub_e6bc5407-e258-4de0-bb43-61faaf062035",
          "subscription_external_id": "sub_0001",
          "plan_uuid": "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
          "prorated": false,
          "service_period_start": "2015-11-01T00:00:00.000Z",
          "service_period_end": "2015-12-01T00:00:00.000Z",
          "amount_in_cents": 5000,
          "quantity": 1,
          "discount_code": "PSO86",
          "discount_amount_in_cents": 1000,
          "tax_amount_in_cents": 900,
          "account_code": null
        },
        {
          "uuid": "li_0cc8c112-beac-416d-af11-f35744ca4e83",
          "external_id": null,
          "type": "one_time",
          "description": "Setup Fees",
          "amount_in_cents": 2500,
          "quantity": 1,
          "discount_code": "PSO86",
          "discount_amount_in_cents": 500,
          "tax_amount_in_cents": 450,
          "account_code": null
        }
      ],
      "transactions": [
        {
          "uuid": "tr_879d560a-1bec-41bb-986e-665e38a2f7bc",
          "external_id": null,
          "type": "payment",
          "date": "2015-11-05T00:14:23.000Z",
          "result": "successful"
        }
      ]
    }
  ]
}
#<ChartMogul::CustomerInvoices:0x007fb49884b850 
@customer_uuid="cus_f466e33d-ff2b-4a11-8f85-417eb02157a7"
@invoices=[
  #<ChartMogul::Invoice:0x007fb498a04660 
  @uuid="inv_565c73b2-85b9-49c9-a25e-2b7df6a677c9",
  @external_id="INV0001", 
  @date=2015-11-01 00:00:00 UTC,
  @due_date=2015-11-15 00:00:00 UTC, 
  @currency="USD", 
  @line_items=[
    #<ChartMogul::LineItems::Subscription:0x007fb4994d23f8 
    @uuid="li_d72e6843-5793-41d0-bfdf-0269514c9c56",
    @external_id=nil, 
    @type="subscription",
    @subscription_uuid="sub_e6bc5407-e258-4de0-bb43-61faaf062035", 
    @subscription_external_id="sub_0001", 
    @plan_uuid="pl_eed05d54-75b4-431b-adb2-eb6b9e543206", 
    @service_period_start=2015-11-01 00:00:00 UTC, 
    @service_period_end=2015-12-01 00:00:00 UTC, 
    @amount_in_cents=5000, 
    @quantity=1, 
    @discount_code="PSO86",
    @discount_amount_in_cents=1000,
    @tax_amount_in_cents=900,
    @cancelled_at=nil,
    @prorated=false,
    @invoice_uuid="inv_565c73b2-85b9-49c9-a25e-2b7df6a677c9",
    @account_code=nil
    >,
    #<ChartMogul::LineItems::OneTime:0x007fb499149358 
    @uuid="li_0cc8c112-beac-416d-af11-f35744ca4e83",
    @external_id=nil,
    @type="one_time",
    @amount_in_cents=5000, 
    @description="Setup Fees", 
    @quantity=1, 
    @discount_amount_in_cents=1000, 
    @discount_code="PSO86", 
    @tax_amount_in_cents=900,
    @invoice_uuid="inv_565c73b2-85b9-49c9-a25e-2b7df6a677c9",
    @account_code=nil
    >
  ], 
  @transactions=[
    #<ChartMogul::Transactions::Payment:0x007fb4991013f0 
    @uuid="tr_879d560a-1bec-41bb-986e-665e38a2f7bc",
    @external_id=nil,
    @date=2015-11-05 00:14:23 UTC, 
    @result="successful", 
    @type="payment",
    @invoice_uuid="inv_565c73b2-85b9-49c9-a25e-2b7df6a677c9"
    >
  ]
  >
]
>
{
  "invoices": [
    {
      "uuid": "inv_565c73b2-85b9-49c9-a25e-2b7df6a677c9",
      "external_id": "INV0001",
      "date": "2015-11-01T00:00:00.000Z",
      "due_date": "2015-11-15T00:00:00.000Z",
      "currency": "USD",
      "line_items": [
        {
          "uuid": "li_d72e6843-5793-41d0-bfdf-0269514c9c56",
          "external_id": null,
          "type": "subscription",
          "subscription_uuid": "sub_e6bc5407-e258-4de0-bb43-61faaf062035",
          "subscription_external_id": "sub_0001",
          "plan_uuid": "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
          "prorated": false,
          "service_period_start": "2015-11-01T00:00:00.000Z",
          "service_period_end": "2015-12-01T00:00:00.000Z",
          "amount_in_cents": 5000,
          "quantity": 1,
          "discount_code": "PSO86",
          "discount_amount_in_cents": 1000,
          "tax_amount_in_cents": 900,
          "account_code": null
        },
        {
          "uuid": "li_0cc8c112-beac-416d-af11-f35744ca4e83",
          "external_id": null,
          "type": "one_time",
          "description": "Setup Fees",
          "amount_in_cents": 2500,
          "quantity": 1,
          "discount_code": "PSO86",
          "discount_amount_in_cents": 500,
          "tax_amount_in_cents": 450,
          "account_code": null
        }
      ],
      "transactions": [
        {
          "uuid": "tr_879d560a-1bec-41bb-986e-665e38a2f7bc",
          "external_id": null,
          "type": "payment",
          "date": "2015-11-05T00:14:23.000Z",
          "result": "successful"
        }
      ]
    }
  ]
}
<?php

ChartMogul\CustomerInvoices::__set_state(array(
   "invoices" => 
  Doctrine\Common\Collections\ArrayCollection::__set_state(array(
     "elements" => 
    array (
      0 => 
      ChartMogul\Invoice::__set_state(array(
         "uuid" => "inv_565c73b2-85b9-49c9-a25e-2b7df6a677c9",
         "date" => "2015-11-01T00:00:00.000Z",
         "external_id" => "INV0001",
         "due_date" => "2015-11-15T00:00:00.000Z",
         "currency" => "USD",
         "line_items" => 
        Doctrine\Common\Collections\ArrayCollection::__set_state(array(
           "elements" => 
          array (
            0 => 
            ChartMogul\LineItems\Subscription::__set_state(array(
               "type" => "subscription",
               "subscription_external_id" => "sub_0001",
               "service_period_start" => "2015-07-01T00:00:00.000Z",
               "service_period_end" => "2016-01-01T00:00:00.000Z",
               "cancelled_at" => NULL,
               "prorated" => false,
               "subscription_uuid" => "sub_e6bc5407-e258-4de0-bb43-61faaf062035",
               "plan_uuid" => "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
               "uuid" => "li_d72e6843-5793-41d0-bfdf-0269514c9c56",
               "amount_in_cents" => -5000,
               "quantity" => -10,
               "discount_amount_in_cents" => 0,
               "discount_code" => "",
               "tax_amount_in_cents" => 0,
               "external_id" => NULL,
               "invoice_uuid" => NULL,
               "account_code" => ""
            )),
            1 => 
            ChartMogul\LineItems\OneTime::__set_state(array(
               "type" => "one_time",
               "description" => "Setup Fees",
               "uuid" => "li_0cc8c112-beac-416d-af11-f35744ca4e83",
               "amount_in_cents" => 2500,
               "quantity" => 1,
               "discount_amount_in_cents" => 500,
               "discount_code" => "PSO86",
               "tax_amount_in_cents" => 450,
               "external_id" => NULL,
               "invoice_uuid" => NULL,
               "account_code" => ""
            )),
          ),
        )),
         "transactions" => 
        Doctrine\Common\Collections\ArrayCollection::__set_state(array(
           "elements" => 
          array (
            0 => 
            ChartMogul\Transactions\Payment::__set_state(array(
               "type" => "payment",
               "uuid" => "tr_879d560a-1bec-41bb-986e-665e38a2f7bc",
               "date" => "2015-11-05T00:14:23.000Z",
               "result" => "successful"
           )))
        ))
)))))));
?>
(*chartmogul.Invoices)(0xc0420085c0)({
 CustomerUUID: (string) "",
 CurrentPage: (uint32) 0,
 TotalPages: (uint32) 0,
 Error: (string) "",
 Invoices: ([]*chartmogul.Invoice) (len=1) {
  (*chartmogul.Invoice)(0xc04210a5a0)({
   UUID: (string) (len=40) "inv_36045157-e5df-45f5-bd96-a8e6bbe08517",
   Currency: (string) (len=3) "USD",
   Date: (string) (len=24) "2015-11-01T00:00:00.000Z",
   DueDate: (string) (len=24) "2015-11-15T00:00:00.000Z",
   ExternalID: (string) (len=7) "INV0002",
   LineItems: ([]*chartmogul.LineItem) (len=2) {
    (*chartmogul.LineItem)(0xc0421cb080)({
     AmountInCents: (int) 2500,
     CancelledAt: (string) "",
     Description: (string) (len=10) "Setup Fees",
     DiscountAmountInCents: (int) 500,
     DiscountCode: (string) (len=5) "PSO86",
     ExternalID: (string) "",
     PlanUUID: (string) "",
     Prorated: (bool) false,
     Quantity: (int) 1,
     ServicePeriodEnd: (string) "",
     ServicePeriodStart: (string) "",
     SubscriptionExternalID: (string) "",
     SubscriptionUUID: (string) "",
     TaxAmountInCents: (int) 450,
     Type: (string) (len=8) "one_time"
    }),
    (*chartmogul.LineItem)(0xc0421cb140)({
     AmountInCents: (int) 5000,
     CancelledAt: (string) "",
     Description: (string) "",
     DiscountAmountInCents: (int) 1000,
     DiscountCode: (string) (len=5) "PSO86",
     ExternalID: (string) "",
     PlanUUID: (string) (len=39) "pl_8da1caec-ee0b-11e6-a4d9-dbe62a1a1694",
     Prorated: (bool) false,
     Quantity: (int) 1,
     ServicePeriodEnd: (string) (len=24) "2015-12-01T00:00:00.000Z",
     ServicePeriodStart: (string) (len=24) "2015-11-01T00:00:00.000Z",
     SubscriptionExternalID: (string) "sub_0001",
     SubscriptionUUID: (string) "sub_e6bc5407-e258-4de0-bb43-61faaf062035",
     TaxAmountInCents: (int) 900,
     Type: (string) (len=12) "subscription"
    })
   },
   Transactions: ([]*chartmogul.Transaction) (len=1) {
    (*chartmogul.Transaction)(0xc0420e2c00)(Transaction() successful payment (2015-11-05T00:14:23.000Z))
   },
   Errors: (*chartmogul.Errors)(<nil>)
  })
 }
})
Invoices(invoices=[<Invoice{
    currency='USD',
    date=datetime.datetime(2015, 11, 1, 0, 0),
    due_date=datetime.datetime(2015, 11, 15, 0, 0),
    external_id='INV0001',
    line_items=[
        <LineItem{
            account_code='',
            amount_in_cents=2500,
            discount_amount_in_cents=500,
            discount_code='PSO86',
            external_id=None,
            quantity=1,
            tax_amount_in_cents=450,
            type='one_time',
            uuid='li_15c316b4-6b41-4673-9c58-6070c3c9b5c9'}>,
        <LineItem{
            account_code='',
            amount_in_cents=5000,
            discount_amount_in_cents=1000,
            discount_code='PSO86',
            external_id=None,
            plan_uuid='pl_8da1caec-ee0b-11e6-a4d9-dbe62a1a1694',
            prorated=False,
            quantity=1,
            service_period_end=datetime.datetime(2015, 12, 1, 0, 0),
            service_period_start=datetime.datetime(2015, 11, 1, 0, 0),
            subscription_uuid='sub_b8ba9b19-0d7d-401c-ad99-496104b435f1',
            subscription_external_id='sub_0001',
            tax_amount_in_cents=900,
            type='subscription',
            uuid='li_80c5c60c-bbb6-459c-bfba-9e6eaa458d5f'}>],
    transactions=[
        <Transaction{
            date=datetime.datetime(2015, 11, 5, 0, 14, 23),
            external_id=None,
            result='successful',
            type='payment',
            uuid='tr_9f5162d6-d2a7-4d35-bdf9-03be5d901b42'}>],
    uuid='inv_7ca4b8e7-6f90-446c-9fdf-6433e9999f96'}>],
current_page=None,
total_pages=None)
Suggest Edits

List Customer's Invoices

Returns a list of invoice objects for a given customer.

 
gethttps://api.chartmogul.com/v1/import/customers/CUSTOMER_UUID/invoices

Path Params

customer_uuid
string
required

The ChartMogul UUID of the Customer whose invoices are requested.

Query Params

page
int32

The page number for pagination of results.

per_page
int32

A limit on number of subscriptions to return per page. The default and maximum value is 200.

 

In the response, the customer_uuid is the UUID of the customer whose invoices are listed.

invoices contains an array of invoice objects with the following data:

  • uuid - The UUID of the invoice object generated by ChartMogul.
  • external_id - The unique external identifier for this invoice, as specified by you.
  • date - The date on which this invoice was raised, as specified by you.
  • due_date - The date within which this invoice must be paid, as specified by you.
  • currency - The 3-letter code of the currency of this invoice, as specified by you.
  • line_items contains an array of line_item objects of this invoice with the following data:
    • uuid - The UUID of the line_item object generated by ChartMogul.
    • external_id - The unique external identifier for this line item, as specified by you.
    • type - The type of line item - one of subscription or one_time, as specified by you.
    • subscription_uuid - The UUID of the subscription object generated by ChartMogul.
    • subscription_external_id - The unique external identifier for this subscription, as specified by you.
    • plan_uuid - The UUID of the plan object associated with the above subscription object. Generated by ChartMogul.
    • prorated - A boolean stating whether or not this is a prorated charge for the subscription object, as specified by you.
    • service_period_start - The start of the service period for which the subscription is being charged, as specified by you.
    • service_period_end - The end of the service period for which the subscription is being charged, as specified by you.
    • description - A short description of the one_time line item being charged to the customer, as specified by you.
    • amount_in_cents - The amount in cents charged towards this line item for the specified service period, after discounts and taxes have been applied. Specified by you.
    • quantity - The quantity of this line item being billed.
    • discount_code - A reference code for any discount applied to this line item, as specified by you.
    • discount_amount_in_cents - The discount amount in cents for this line item if any, as specified by you.
    • tax_amount_in_cents - The tax amount in cents for this line item if any, as specified by you.
    • account_code - The accounting code for the line item, as specified by you.
  • transactions contains an array of transaction objects of this invoice with the following data:
    • uuid - The UUID of the transaction object generated by ChartMogul.
    • external_id - The unique external identifier for this transaction, as specified by you.
    • type - One of payment or refund, as specified by you.
    • date - The timestamp of when the transaction was attempted, as specified by you.
    • result - The result of the transaction attempt. One of successful or failed, as specified by you.

The other keys represent pagination attributes:

  • total_pages - The total number of pages with results for this request.
  • current_page - The page number of this response.

Examples

curl -X GET "https://api.chartmogul.com/v1/import/customers/cus_f466e33d-ff2b-4a11-8f85-417eb02157a7/invoices" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_KEY \
     -H "Content-Type: application/json"
ChartMogul::CustomerInvoices.all('cus_7388fd53-1ecf-481e-97e6-28adb653f6c0', page: 1, per_page: 200)
ChartMogul.Invoice.all(config, "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7", function (err, res) {
   // asynchronously called
});
<?php

ChartMogul\CustomerInvoices::all([
    "customer_uuid" => "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7"
]);
?>
res, err := api.ListInvoices(&cm.Cursor{PerPage: 1},
		"cus_c0dc8d74-edfd-11e6-a357-832dddba822f")
chartmogul.Invoice.all(
  config,
  uuid='cus_c0dc8d74-edfd-11e6-a357-832dddba822f',
  per_page=1)

Result Format

{
  "customer_uuid": "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
  "invoices": [
    {
      "uuid": "inv_565c73b2-85b9-49c9-a25e-2b7df6a677c9",
      "external_id": "INV0001",
      "date": "2015-11-01T00:00:00.000Z",
      "due_date": "2015-11-15T00:00:00.000Z",
      "currency": "USD",
      "line_items": [
        {
          "uuid": "li_d72e6843-5793-41d0-bfdf-0269514c9c56",
          "external_id": null,
          "type": "subscription",
          "subscription_uuid": "sub_e6bc5407-e258-4de0-bb43-61faaf062035",
          "subscription_external_id": "sub_0001",
          "plan_uuid": "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
          "prorated": false,
          "service_period_start": "2015-11-01T00:00:00.000Z",
          "service_period_end": "2015-12-01T00:00:00.000Z",
          "amount_in_cents": 5000,
          "quantity": 1,
          "discount_code": "PSO86",
          "discount_amount_in_cents": 1000,
          "tax_amount_in_cents": 900,
          "account_code": null
        },
        {
          "uuid": "li_0cc8c112-beac-416d-af11-f35744ca4e83",
          "external_id": null,
          "type": "one_time",
          "description": "Setup Fees",
          "amount_in_cents": 2500,
          "quantity": 1,
          "discount_code": "PSO86",
          "discount_amount_in_cents": 500,
          "tax_amount_in_cents": 450,
          "account_code": null
        }
      ],
      "transactions": [
        {
          "uuid": "tr_879d560a-1bec-41bb-986e-665e38a2f7bc",
          "external_id": null,
          "type": "payment",
          "date": "2015-11-05T00:14:23.000Z",
          "result": "successful"
        }
      ]
    }
  ],
  "current_page": 1,
  "total_pages": 1
}
#<ChartMogul::CustomerInvoices:0x007fb49884b850 
@customer_uuid="cus_7388fd53-1ecf-481e-97e6-28adb653f6c0"
@invoices=[
  #<ChartMogul::Invoice:0x007fb498a04660 
  @uuid="inv_64acf8fd-7597-4955-b395-150445bb5a99",
  @date=2015-11-01 00:00:00 UTC, 
  @currency="USD", 
  @external_id="INV0001", 
  @due_date=2015-11-15 00:00:00 UTC, 
  @line_items=[
    #<ChartMogul::LineItems::Subscription:0x007fb4994d23f8 
    @uuid="li_d72e6843-5793-41d0-bfdf-0269514c9c56",
    @external_id=nil, 
    @type="subscription",
    @subscription_uuid="sub_e6bc5407-e258-4de0-bb43-61faaf062035", 
    @subscription_external_id="sub_0001", 
    @plan_uuid="pl_eed05d54-75b4-431b-adb2-eb6b9e543206", 
    @service_period_start=2015-11-01 00:00:00 UTC, 
    @service_period_end=2015-12-01 00:00:00 UTC, 
    @amount_in_cents=5000, 
    @quantity=1, 
    @discount_code="PSO86",
    @discount_amount_in_cents=1000,
    @tax_amount_in_cents=900,
    @cancelled_at=nil,
    @prorated=false,
    @invoice_uuid="inv_64acf8fd-7597-4955-b395-150445bb5a99",
    @account_code=nil
    >,
    #<ChartMogul::LineItems::OneTime:0x007fb499149358 
    @uuid="li_0cc8c112-beac-416d-af11-f35744ca4e83",
    @external_id=nil,
    @type="one_time",
    @amount_in_cents=5000, 
    @description="Setup Fees", 
    @quantity=1, 
    @discount_amount_in_cents=1000, 
    @discount_code="PSO86", 
    @tax_amount_in_cents=900,
    @invoice_uuid="inv_64acf8fd-7597-4955-b395-150445bb5a99",
    @account_code=nil
    >
  ], 
  @transactions=[
    #<ChartMogul::Transactions::Payment:0x007fb4991013f0 
    @uuid="tr_39c00a54-30c9-4ce4-8b40-621266418c06",
    @external_id=nil,
    @date=2015-11-01 12:00:00 UTC, 
    @result="successful", 
    @type="payment",
    @invoice_uuid="inv_64acf8fd-7597-4955-b395-150445bb5a99"
    >
  ]>,
  @current_page= 1,
  @total_page=: 1
]>
{
  "customer_uuid": "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
  "invoices": [
    {
      "uuid": "inv_565c73b2-85b9-49c9-a25e-2b7df6a677c9",
      "external_id": "INV0001",
      "date": "2015-11-01T00:00:00.000Z",
      "due_date": "2015-11-15T00:00:00.000Z",
      "currency": "USD",
      "line_items": [
        {
          "uuid": "li_d72e6843-5793-41d0-bfdf-0269514c9c56",
          "external_id": null,
          "type": "subscription",
          "subscription_uuid": "sub_e6bc5407-e258-4de0-bb43-61faaf062035",
          "subscription_external_id": "sub_0001",
          "plan_uuid": "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
          "prorated": false,
          "service_period_start": "2015-11-01T00:00:00.000Z",
          "service_period_end": "2015-12-01T00:00:00.000Z",
          "amount_in_cents": 5000,
          "quantity": 1,
          "discount_code": "PSO86",
          "discount_amount_in_cents": 1000,
          "tax_amount_in_cents": 900,
          "account_code": null
        },
        {
          "uuid": "li_0cc8c112-beac-416d-af11-f35744ca4e83",
          "external_id": null,
          "type": "one_time",
          "description": "Setup Fees",
          "amount_in_cents": 2500,
          "quantity": 1,
          "discount_code": "PSO86",
          "discount_amount_in_cents": 500,
          "tax_amount_in_cents": 450,
          "account_code": null
        }
      ],
      "transactions": [
        {
          "uuid": "tr_879d560a-1bec-41bb-986e-665e38a2f7bc",
          "external_id": null,
          "type": "payment",
          "date": "2015-11-05T00:14:23.000Z",
          "result": "successful"
        }
      ]
    }
  ],
  "current_page": 1,
  "total_pages": 1
}
<?php

ChartMogul\CustomerInvoices::__set_state(array(
   "customer_uuid" => "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
   "current_page" => 1,
   "total_pages" => 1,
   "invoices" => 
  Doctrine\Common\Collections\ArrayCollection::__set_state(array(
     "elements" => 
    array (
      0 => 
      ChartMogul\Invoice::__set_state(array(
         "uuid" => "inv_565c73b2-85b9-49c9-a25e-2b7df6a677c9",
         "date" => "2015-11-01T00:00:00.000Z",
         "external_id" => "INV0001",
         "due_date" => "2015-11-15T00:00:00.000Z",
         "currency" => "USD",
         "line_items" => 
        Doctrine\Common\Collections\ArrayCollection::__set_state(array(
           "elements" => 
          array (
            0 => 
            ChartMogul\LineItems\Subscription::__set_state(array(
               "type" => "subscription",
               "subscription_external_id" => NULL,
               "service_period_start" => "2015-07-01T00:00:00.000Z",
               "service_period_end" => "2016-01-01T00:00:00.000Z",
               "cancelled_at" => NULL,
               "prorated" => false,
               "subscription_uuid" => "sub_e6bc5407-e258-4de0-bb43-61faaf062035",
          		 "subscription_external_id" => "sub_0001",
               "plan_uuid" => "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
               "uuid" => "li_d72e6843-5793-41d0-bfdf-0269514c9c56",
               "amount_in_cents" => -5000,
               "quantity" => -10,
               "discount_amount_in_cents" => 0,
               "discount_code" => "",
               "tax_amount_in_cents" => 0,
               "external_id" => NULL,
               "invoice_uuid" => NULL,
               "account_code" => ""
            )),
            1 => 
            ChartMogul\LineItems\OneTime::__set_state(array(
               "type" => "one_time",
               "description" => "Setup Fees",
               "uuid" => "li_0cc8c112-beac-416d-af11-f35744ca4e83",
               "amount_in_cents" => 2500,
               "quantity" => 1,
               "discount_amount_in_cents" => 500,
               "discount_code" => "PSO86",
               "tax_amount_in_cents" => 450,
               "external_id" => NULL,
               "invoice_uuid" => NULL,
               "account_code" => ""
            )),
          ),
        )),
         "transactions" => 
        Doctrine\Common\Collections\ArrayCollection::__set_state(array(
           "elements" => 
          array (
            0 => 
            ChartMogul\Transactions\Payment::__set_state(array(
               "type" => "payment",
               "uuid" => "tr_879d560a-1bec-41bb-986e-665e38a2f7bc",
               "date" => "2015-11-05T00:14:23.000Z",
               "result" => "successful"
           )))
        ))
)))))));
?>
(*chartmogul.Invoices)(0xc04204a380)({
 CustomerUUID: (string) (len=40) "cus_c0dc8d74-edfd-11e6-a357-832dddba822f",
 CurrentPage: (uint32) 1,
 TotalPages: (uint32) 3,
 Error: (string) "",
 Invoices: ([]*chartmogul.Invoice) (len=1) {
  (*chartmogul.Invoice)(0xc042088240)({
   UUID: (string) (len=40) "inv_36045157-e5df-45f5-bd96-a8e6bbe08517",
   Currency: (string) (len=3) "USD",
   Date: (string) (len=24) "2015-11-01T00:00:00.000Z",
   DueDate: (string) (len=24) "2015-11-15T00:00:00.000Z",
   ExternalID: (string) (len=7) "INV0003",
   LineItems: ([]*chartmogul.LineItem) (len=2) {
    (*chartmogul.LineItem)(0xc0420dc0c0)({
     AmountInCents: (int) 2500,
     CancelledAt: (string) "",
     Description: (string) (len=10) "Setup Fees",
     DiscountAmountInCents: (int) 500,
     DiscountCode: (string) (len=5) "PSO86",
     ExternalID: (string) "",
     PlanUUID: (string) "",
     Prorated: (bool) false,
     Quantity: (int) 1,
     ServicePeriodEnd: (string) "",
     ServicePeriodStart: (string) "",
     SubscriptionExternalID: (string) "",
     SubscriptionUUID: (string) "",
     TaxAmountInCents: (int) 450,
     Type: (string) (len=8) "one_time"
    }),
    (*chartmogul.LineItem)(0xc0420dc180)({
     AmountInCents: (int) 5000,
     CancelledAt: (string) "",
     Description: (string) "",
     DiscountAmountInCents: (int) 1000,
     DiscountCode: (string) (len=5) "PSO86",
     ExternalID: (string) "",
     PlanUUID: (string) (len=39) "pl_8da1caec-ee0b-11e6-a4d9-dbe62a1a1694",
     Prorated: (bool) false,
     Quantity: (int) 1,
     ServicePeriodEnd: (string) (len=24) "2015-12-01T00:00:00.000Z",
     ServicePeriodStart: (string) (len=24) "2015-11-01T00:00:00.000Z",
     SubscriptionExternalID: (string) "sub_0001",
     SubscriptionUUID: (string) (len=40) "sub_e6bc5407-e258-4de0-bb43-61faaf062035",
     TaxAmountInCents: (int) 900,
     Type: (string) (len=12) "subscription"
    })
   },
   Transactions: ([]*chartmogul.Transaction) (len=1) {
    (*chartmogul.Transaction)(0xc042040840)(Transaction() successful payment (2015-11-05T00:14:23.000Z))
   },
   Errors: (*chartmogul.Errors)(<nil>)
  })
 }
})
Invoices(invoices=[<Invoice{
    currency='USD',
    date=datetime.datetime(2015, 11, 1, 0, 0),
    due_date=datetime.datetime(2015, 11, 15, 0, 0),
    external_id='INV0003',
    line_items=[
        <LineItem{
            account_code='',
            amount_in_cents=2500,
            discount_amount_in_cents=500,
            discount_code='PSO86',
            external_id=None,
            quantity=1,
            tax_amount_in_cents=450,
            type='one_time',
            uuid='li_b73e44ed-f724-49df-98f0-434332236f2a'}>,
        <LineItem{
            account_code='',
            amount_in_cents=5000,
            discount_amount_in_cents=1000,
            discount_code='PSO86',
            external_id=None,
            plan_uuid='pl_8da1caec-ee0b-11e6-a4d9-dbe62a1a1694',
            prorated=False,
            quantity=1,
            service_period_end=datetime.datetime(2015, 12, 1, 0, 0),
            service_period_start=datetime.datetime(2015, 11, 1, 0, 0),
            subscription_uuid='sub_a08e4f36-b170-494d-88d9-cbf0b2dc6100',
            subscription_external_id='sub_0001',
            tax_amount_in_cents=900,
            type='subscription',
            uuid='li_1559efac-2a02-4660-8323-6bb83be4c89b'}>],
    transactions=[<Transaction{
        date=datetime.datetime(2015, 11, 5, 0, 14, 23),
        external_id=None,
        result='successful',
        type='payment',
        uuid='tr_5b2ba340-330f-4737-820f-310ffa547b78'}>],
    uuid='inv_36045157-e5df-45f5-bd96-a8e6bbe08517'}>],
current_page=1,
total_pages=3,
customer_uuid='cus_c0dc8d74-edfd-11e6-a357-832dddba822f')
Suggest Edits

List Invoices

Returns a list of invoice objects created using the API in your ChartMogul account.

 
gethttps://api.chartmogul.com/v1/invoices

Query Params

data_source_uuid
string

The ChartMogul UUID of the data source with which you want to filter this invoice list.

customer_uuid
string

The ChartMogul UUID of the customer whose invoices you want to retrieve.

external_id
string

A unique external identifier of the invoice that you want to retrieve.

page
int32

The page number for pagination of results.

per_page
int32

A limit on number of invoices to return per page. The default and maximum value is 200.

 

In the response, invoices contains an array of invoice objects with the following data:

  • uuid - The UUID of the invoice object generated by ChartMogul.
  • external_id - The unique external identifier for this invoice, as specified by you.
  • customer_uuid - The UUID of the customer that the invoice belongs to.
  • date - The date on which this invoice was raised, as specified by you.
  • due_date - The date within which this invoice must be paid, as specified by you.
  • currency - The 3-letter code of the currency of this invoice, as specified by you.
  • line_items contains an array of line_item objects of this invoice with the following data:
    • uuid - The UUID of the line_item object generated by ChartMogul.
    • external_id - The unique external identifier for this line item, as specified by you.
    • type - The type of line item - one of subscription or one_time, as specified by you.
    • subscription_uuid - The UUID of the subscription object generated by ChartMogul.
    • subscription_external_id - The unique external identifier for this subscription, as specified by you.
    • plan_uuid - The UUID of the plan object associated with the above subscription object. Generated by ChartMogul.
    • prorated - A boolean stating whether or not this is a prorated charge for the subscription object, as specified by you.
    • service_period_start - The start of the service period for which the subscription is being charged, as specified by you.
    • service_period_end - The end of the service period for which the subscription is being charged, as specified by you.
    • description - A short description of the one_time line item being charged to the customer, as specified by you.
    • amount_in_cents - The amount in cents charged towards this line item for the specified service period, after discounts and taxes have been applied. Specified by you.
    • quantity - The quantity of this line item being billed.
    • discount_code - A reference code for any discount applied to this line item, as specified by you.
    • discount_amount_in_cents - The discount amount in cents for this line item if any, as specified by you.
    • tax_amount_in_cents - The tax amount in cents for this line item if any, as specified by you.
    • account_code - The accounting code for the line item, as specified by you.
  • transactions contains an array of transaction objects of this invoice with the following data:
    • uuid - The UUID of the transaction object generated by ChartMogul.
    • external_id - The unique external identifier for this transaction, as specified by you.
    • type - One of payment or refund, as specified by you.
    • date - The timestamp of when the transaction was attempted, as specified by you.
    • result - The result of the transaction attempt. One of successful or failed, as specified by you.

The other keys represent pagination attributes:

  • total_pages - The total number of pages with results for this request.
  • current_page - The page number of this response.

Examples

curl -X GET "https://api.chartmogul.com/v1/invoices?customer_uuid=cus_f466e33d-ff2b-4a11-8f85-417eb02157a7&external_id=INV0001" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_KEY \
     -H "Content-Type: application/json"
ChartMogul::Invoices.all(customer_uuid: "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7", external_id: "INV0001")
ChartMogul.Invoice.all(config, {
   customer_uuid: "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
   external_id: "INV0001"
   }, function (err, res) {
   // asynchronously called
});
<?php

ChartMogul\Invoice::all([
    "customer_uuid" => "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
    "external_id" => "INV0001"
]);
?>
result, err := api.ListAllInvoices(&cm.ListAllInvoicesParams{
  CustomerUUID: "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
  ExternalID:   "INV0001",
})
chartmogul.Invoice.all(
  config,
  customer_uuid='cus_f466e33d-ff2b-4a11-8f85-417eb02157a7',
  external_id='INV0001')

Result Format

{
  "invoices": [
    {
      "uuid": "inv_565c73b2-85b9-49c9-a25e-2b7df6a677c9",
      "customer_uuid": "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
      "external_id": "INV0001",
      "date": "2015-11-01T00:00:00.000Z",
      "due_date": "2015-11-15T00:00:00.000Z",
      "currency": "USD",
      "line_items": [
        {
          "uuid": "li_d72e6843-5793-41d0-bfdf-0269514c9c56",
          "external_id": null,
          "type": "subscription",
          "subscription_uuid": "sub_e6bc5407-e258-4de0-bb43-61faaf062035",
          "subscription_external_id": "sub_0001",
          "plan_uuid": "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
          "prorated": false,
          "service_period_start": "2015-11-01T00:00:00.000Z",
          "service_period_end": "2015-12-01T00:00:00.000Z",
          "amount_in_cents": 5000,
          "quantity": 1,
          "discount_code": "PSO86",
          "discount_amount_in_cents": 1000,
          "tax_amount_in_cents": 900,
          "account_code": null
        },
        {
          "uuid": "li_0cc8c112-beac-416d-af11-f35744ca4e83",
          "external_id": null,
          "type": "one_time",
          "description": "Setup Fees",
          "amount_in_cents": 2500,
          "quantity": 1,
          "discount_code": "PSO86",
          "discount_amount_in_cents": 500,
          "tax_amount_in_cents": 450,
          "account_code": null
        }
      ],
      "transactions": [
        {
          "uuid": "tr_879d560a-1bec-41bb-986e-665e38a2f7bc",
          "external_id": null,
          "type": "payment",
          "date": "2015-11-05T00:14:23.000Z",
          "result": "successful"
        }
      ]
    }
  ],
  "current_page": 1,
  "total_pages": 1
}
#<ChartMogul::Invoices:0x007fb49884b850
@invoices=[
  #<ChartMogul::Invoice:0x007fb498a04660 
  @uuid="inv_565c73b2-85b9-49c9-a25e-2b7df6a677c9",
  @customer_uuid="cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
  @date=2015-11-01 00:00:00 UTC, 
  @currency="USD", 
  @external_id="INV0001", 
  @due_date=2015-11-15 00:00:00 UTC, 
  @line_items=[
    #<ChartMogul::LineItems::Subscription:0x007fb4994d23f8 
    @uuid="li_d72e6843-5793-41d0-bfdf-0269514c9c56",
    @external_id=nil, 
    @type="subscription",
    @subscription_uuid="sub_e6bc5407-e258-4de0-bb43-61faaf062035", 
    @subscription_external_id="sub_0001", 
    @plan_uuid="pl_eed05d54-75b4-431b-adb2-eb6b9e543206", 
    @service_period_start=2015-11-01 00:00:00 UTC, 
    @service_period_end=2015-12-01 00:00:00 UTC, 
    @amount_in_cents=5000, 
    @quantity=1, 
    @discount_code="PSO86",
    @discount_amount_in_cents=1000,
    @tax_amount_in_cents=900,
    @cancelled_at=nil,
    @prorated=false,
    @invoice_uuid="inv_64acf8fd-7597-4955-b395-150445bb5a99",
    @account_code=nil
    >,
    #<ChartMogul::LineItems::OneTime:0x007fb499149358 
    @uuid="li_0cc8c112-beac-416d-af11-f35744ca4e83",
    @external_id=nil,
    @type="one_time",
    @amount_in_cents=5000, 
    @description="Setup Fees", 
    @quantity=1, 
    @discount_amount_in_cents=1000, 
    @discount_code="PSO86", 
    @tax_amount_in_cents=900,
    @invoice_uuid="inv_64acf8fd-7597-4955-b395-150445bb5a99",
    @account_code=nil
    >
  ], 
  @transactions=[
    #<ChartMogul::Transactions::Payment:0x007fb4991013f0 
    @uuid="tr_39c00a54-30c9-4ce4-8b40-621266418c06",
    @external_id=nil,
    @date=2015-11-01 12:00:00 UTC, 
    @result="successful", 
    @type="payment",
    @invoice_uuid="inv_64acf8fd-7597-4955-b395-150445bb5a99"
    >
  ]>,
  @current_page= 1,
  @total_page=: 1
]>
{
  "invoices": [
    {
      "uuid": "inv_565c73b2-85b9-49c9-a25e-2b7df6a677c9",
      "customer_uuid": "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
      "external_id": "INV0001",
      "date": "2015-11-01T00:00:00.000Z",
      "due_date": "2015-11-15T00:00:00.000Z",
      "currency": "USD",
      "line_items": [
        {
          "uuid": "li_d72e6843-5793-41d0-bfdf-0269514c9c56",
          "external_id": null,
          "type": "subscription",
          "subscription_uuid": "sub_e6bc5407-e258-4de0-bb43-61faaf062035",
          "subscription_external_id": "sub_0001",
          "plan_uuid": "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
          "prorated": false,
          "service_period_start": "2015-11-01T00:00:00.000Z",
          "service_period_end": "2015-12-01T00:00:00.000Z",
          "amount_in_cents": 5000,
          "quantity": 1,
          "discount_code": "PSO86",
          "discount_amount_in_cents": 1000,
          "tax_amount_in_cents": 900,
          "account_code": null
        },
        {
          "uuid": "li_0cc8c112-beac-416d-af11-f35744ca4e83",
          "external_id": null,
          "type": "one_time",
          "description": "Setup Fees",
          "amount_in_cents": 2500,
          "quantity": 1,
          "discount_code": "PSO86",
          "discount_amount_in_cents": 500,
          "tax_amount_in_cents": 450,
          "account_code": null
        }
      ],
      "transactions": [
        {
          "uuid": "tr_879d560a-1bec-41bb-986e-665e38a2f7bc",
          "external_id": null,
          "type": "payment",
          "date": "2015-11-05T00:14:23.000Z",
          "result": "successful"
        }
      ]
    }
  ],
  "current_page": 1,
  "total_pages": 1
}
<?php

Doctrine\Common\Collections\ArrayCollection::__set_state(array(
   'elements' =>
  array (
    0 =>
    ChartMogul\Invoice::__set_state(array(
       'uuid' => 'inv_565c73b2-85b9-49c9-a25e-2b7df6a677c9',
       'customer_uuid' => 'cus_f466e33d-ff2b-4a11-8f85-417eb02157a7',
       'date' => '2015-11-01T00:00:00.000Z',
       'currency' => 'USD',
       'line_items' =>
      Doctrine\Common\Collections\ArrayCollection::__set_state(array(
         'elements' =>
        array (
          0 =>
          ChartMogul\LineItems\Subscription::__set_state(array(
             'type' => 'subscription',
             'subscription_external_id' => 'sub_0001',
             'service_period_start' => '2015-11-01T00:00:00.000Z',
             'service_period_end' => '2015-12-01T00:00:00.000Z',
             'cancelled_at' => NULL,
             'prorated' => false,
             'subscription_uuid' => 'sub_e6bc5407-e258-4de0-bb43-61faaf062035',
             'plan_uuid' => 'pl_eed05d54-75b4-431b-adb2-eb6b9e543206',
             'uuid' => 'li_d72e6843-5793-41d0-bfdf-0269514c9c56',
             'amount_in_cents' => 5000,
             'quantity' => 1,
             'discount_amount_in_cents' => 1000,
             'discount_code' => 'PSO86',
             'tax_amount_in_cents' => 900,
             'external_id' => NULL,
             'invoice_uuid' => NULL,
             'account_code' => NULL,
          )),
          1 =>
          ChartMogul\LineItems\OneTime::__set_state(array(
             'type' => 'one_time',
             'description' => 'Setup Fees',
             'uuid' => 'li_0cc8c112-beac-416d-af11-f35744ca4e83',
             'amount_in_cents' => 2500,
             'quantity' => 1,
             'discount_amount_in_cents' => 500,
             'discount_code' => 'PSO86',
             'tax_amount_in_cents' => 450,
             'external_id' => NULL,
             'invoice_uuid' => NULL,
             'account_code' => NULL,
          )),
        ),
      )),
       'transactions' =>
      Doctrine\Common\Collections\ArrayCollection::__set_state(array(
         'elements' =>
        array (
          0 =>
          ChartMogul\Transactions\Payment::__set_state(array(
             'type' => 'payment',
             'uuid' => 'tr_879d560a-1bec-41bb-986e-665e38a2f7bc',
             'date' => '2015-11-05T00:14:23.000Z',
             'result' => 'successful',
             'external_id' => NULL,
             'invoice_uuid' => NULL,
          )),
        ),
      )),
       'external_id' => 'INV0001',
       'due_date' => '2015-11-15T00:00:00.000Z',
    )),
  ),
   'current_page' => 2,
   'total_pages' => 3,
))
  
?>
(*chartmogul.Invoices)(0xc042116400)({
 CustomerUUID: (string) "",
 CurrentPage: (uint32) 1,
 TotalPages: (uint32) 1,
 Error: (string) "",
 Invoices: ([]*chartmogul.Invoice) (len=1 cap=4) {
  (*chartmogul.Invoice)(0xc0420f0320)({
   UUID: (string) (len=40) "inv_565c73b2-85b9-49c9-a25e-2b7df6a677c9",
   CustomerUUID: (string) (len=40) "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
   Currency: (string) (len=3) "USD",
   Date: (string) (len=24) "2015-11-01T00:00:00.000Z",
   DueDate: (string) (len=24) "2015-11-15T00:00:00.000Z",
   ExternalID: (string) (len=7) "INV0001",
   LineItems: ([]*chartmogul.LineItem) (len=2 cap=4) {
    (*chartmogul.LineItem)(0xc0420e60f0)({
     UUID: (string) (len=39) "li_d72e6843-5793-41d0-bfdf-0269514c9c56",
     AccountCode: (string) "",
     AmountInCents: (int) 5000,
     CancelledAt: (string) "",
     Description: (string) "",
     DiscountAmountInCents: (int) 1000,
     DiscountCode: (string) (len=5) "PSO86",
     ExternalID: (string) "",
     PlanUUID: (string) (len=39) "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
     Prorated: (bool) false,
     Quantity: (int) 1,
     ServicePeriodEnd: (string) (len=24) "2015-12-01T00:00:00.000Z",
     ServicePeriodStart: (string) (len=24) "2015-11-01T00:00:00.000Z",
     SubscriptionExternalID: (string) "sub_0001",
     SubscriptionUUID: (string) (len=40) "sub_e6bc5407-e258-4de0-bb43-61faaf062035",
     TaxAmountInCents: (int) 900,
     Type: (string) (len=12) "subscription"
    }),
    (*chartmogul.LineItem)(0xc0420e61e0)({
     UUID: (string) (len=39) "li_0cc8c112-beac-416d-af11-f35744ca4e83",
     AccountCode: (string) "",
     AmountInCents: (int) 2500,
     CancelledAt: (string) "",
     Description: (string) (len=10) "Setup Fees",
     DiscountAmountInCents: (int) 500,
     DiscountCode: (string) (len=5) "PSO86",
     ExternalID: (string) "",
     PlanUUID: (string) "",
     Prorated: (bool) false,
     Quantity: (int) 1,
     ServicePeriodEnd: (string) "",
     ServicePeriodStart: (string) "",
     SubscriptionExternalID: (string) "",
     SubscriptionUUID: (string) "",
     TaxAmountInCents: (int) 450,
     Type: (string) (len=8) "one_time"
    })
   },
   Transactions: ([]*chartmogul.Transaction) (len=1 cap=4) {
    (*chartmogul.Transaction)(0xc04200fc80)({
     UUID: (string) (len=39) "tr_879d560a-1bec-41bb-986e-665e38a2f7bc",
     Date: (string) (len=24) "2015-11-05T00:14:23.000Z",
     ExternalID: (string) "",
     Result: (string) (len=10) "successful",
     Type: (string) (len=7) "payment",
     Errors: (chartmogul.Errors) chartmogul: map[]
    })
   },
   Errors: (*chartmogul.Errors)(<nil>)
  })
 }
})
Invoices(invoices=[
  <Invoice{currency='USD',
     customer_uuid='cus_f466e33d-ff2b-4a11-8f85-417eb02157a7',
     date=datetime.datetime(2015, 11, 1, 0, 0, tzinfo=tzutc()),
     due_date=datetime.datetime(2015, 11, 15, 0, 0, tzinfo=tzutc()),
     external_id='INV0001',
line_items=[
  <LineItem{account_code=None,
       amount_in_cents=5000,
       discount_amount_in_cents=1000,
       discount_code='PSO86',
       external_id=None,
       plan_uuid='pl_eed05d54-75b4-431b-adb2-eb6b9e543206',
       prorated=False,
       quantity=1,
       service_period_end=datetime.datetime(2015, 12, 1, 0, 0, tzinfo=tzutc()),
       service_period_start=datetime.datetime(2015, 11, 1, 0, 0, tzinfo=tzutc()),
       subscription_uuid='sub_e6bc5407-e258-4de0-bb43-61faaf062035',
       subscription_external_id='sub_0001',
       tax_amount_in_cents=900,
       type='subscription',
       uuid='li_d72e6843-5793-41d0-bfdf-0269514c9c56'} > ,
  <LineItem{account_code=None,
        amount_in_cents=2500,
        discount_amount_in_cents=500,
        discount_code='PSO86',
        external_id=None,
        quantity=1,
        tax_amount_in_cents=450,
        type='one_time',
        uuid='li_0cc8c112-beac-416d-af11-f35744ca4e83'} > ],
transactions=[
  <Transaction{date=datetime.datetime(2015, 11, 5, 0, 14, 23, tzinfo=tzutc()),
        external_id=None,
        result='successful',
        type='payment',
        uuid='tr_879d560a-1bec-41bb-986e-665e38a2f7bc'} > ],
    uuid='inv_565c73b2-85b9-49c9-a25e-2b7df6a677c9'} >],
    current_page=1,
    total_pages=1,
    customer_uuid=None)
Suggest Edits

Transactions

This object represents a payment or refund attempt on an invoice.

 

You can add any number of successful and failed transaction attempts on an invoice to ChartMogul. Transaction objects influence Cash Flow metrics in your ChartMogul account.

Suggest Edits

Import an Invoice Transaction

Creates a transaction object for an invoice imported using the Import API.

 
posthttps://api.chartmogul.com/v1/import/invoices/INVOICE_UUID/transactions

Path Params

invoice_uuid
string
required

The ChartMogul UUID of the Invoice.

Form Data

type
string
required

Either one of payment or refund.

date
date-time
required

The timestamp of when the transaction was attempted. Must be an ISO 8601 formatted time. The timezone defaults to UTC unless otherwise specified. The time defaults to 00:00:00 unless specified otherwise.

result
string
required

Either one of successful or failed depending on the result of this attempted transaction.

external_id
string

A unique identifier specified by you for the transaction. Typically an identifier from your internal system. Accepts alphanumeric characters.

 

In the response, the JSON object contains the following data:

  • uuid - The UUID of the transaction object generated by ChartMogul.
  • external_id - The unique external identifier for this transaction, as specified by you.
  • type - One of payment or refund, as specified by you.
  • date - The timestamp of when the transaction was attempted, as specified by you.
  • result - The result of the transaction attempt. One of successful or failed, as specified by you.

Examples

curl -X POST "https://api.chartmogul.com/v1/import/invoices/inv_565c73b2-85b9-49c9-a25e-2b7df6a677c9/transactions" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_KEY \
     -H "Content-Type: application/json"
     -d '{
            "type": "refund",
            "date": "2015-12-25 18:10:00",
            "result": "successful"
         }'
customer = ChartMogul::Customer.all(external_id:"cus_0001").first
invoice = customer.invoices.last
transaction = ChartMogul::Transactions::Refund.create!(
  invoice_uuid: invoice.uuid,
  date: Time.utc(2015, 12, 25, 18, 10),
  result: 'successful'
)
ChartMogul.Transaction.create(config, "inv_565c73b2-85b9-49c9-a25e-2b7df6a677c9", {
   "type": "refund",
   "date": "2015-12-25 18:10:00",
   "result": "successful"
   }, function (err, res) {
   // asynchronously called
});
<?php

ChartMogul\Transactions\Refund::create([
    "invoice_uuid" => "inv_565c73b2-85b9-49c9-a25e-2b7df6a677c9",
    "date" => "2015-12-25 18:10:00",
    "result" => "successful"
]);
?>
api.CreateTransaction(&cm.Transaction{
		Type:   "refund",
		Date:   "2015-12-25 18:10:00",
		Result: "successful",
	}, "inv_565c73b2-85b9-49c9-a25e-2b7df6a677c9")
chartmogul.Transaction.create(config, uuid='inv_565c73b2-85b9-49c9-a25e-2b7df6a677c9', data={
    "type": "refund",
    "date": "2015-12-25 18:10:00",
    "result": "successful"
  })

Result Format

{
  "uuid": "tr_325e460a-1bec-41bb-986e-665e38a1e4cd",
  "external_id": null,
  "type": "refund",
  "date": "2015-12-25T18:10:00.000Z",
  "result": "successful"
}
#<ChartMogul::Transactions::Refund:0x007fb499222a40 
@uuid="tr_4b424719-52c6-4905-a860-ff318e47bfa0",
@external_id=nil,
@type="refund",
@date=2015-12-25 18:10:00 UTC,
@result="successful"
>
{
  "uuid": "tr_325e460a-1bec-41bb-986e-665e38a1e4cd",
  "external_id": null,
  "type": "refund",
  "date": "2015-12-25T18:10:00.000Z",
  "result": "successful"
}
<?php

ChartMogul\Transactions\Refund::__set_state(array(
   "type" => "refund",
   "uuid" => "tr_325e460a-1bec-41bb-986e-665e38a1e4cd",
   "date" => "2015-12-25T18:10:00.000Z",
   "result" => "successful",
   "external_id" => NULL
));
?>
(*chartmogul.Transaction)(0xc04201a600)({
 UUID: (string) (len=39) "tr_b83ff492-8291-41d3-99de-994538779948",
 Date: (string) (len=24) "2015-12-25T18:10:00.000Z",
 ExternalID: (string) "",
 Result: (string) (len=10) "successful",
 Type: (string) (len=6) "refund",
 Errors: (chartmogul.Errors) chartmogul: map[]
})
<Transaction{
    date=datetime.datetime(2015, 12, 25, 18, 10),
    external_id=None,
    result='successful',
    type='refund',
    uuid='tr_7141b6cf-e869-42a7-87d8-6e342ded2bfa'}>
Suggest Edits

Subscriptions

Subscription objects are auto-generated from Invoice objects.

 

In ChartMogul, customers can have multiple subscriptions at the same time. Subscriptions are created when a customer purchases a plan for the first time. They may be altered, cancelled and re-activated indefinitely.

Suggest Edits

List Customer's Subscriptions

Returns a list of subscription objects for a given customer. Subscriptions are auto-generated from invoice objects created using the Import API.

 
gethttps://api.chartmogul.com/v1/import/customers/CUSTOMER_UUID/subscriptions

Path Params

customer_uuid
string
required

The ChartMogul UUID of the Customer whose subscriptions are requested.

Query Params

page
int32

The page number for pagination of results.

per_page
int32

A limit on number of subscriptions to return per page. The default and maximum value is 200.

 

In the response, the customer_uuid is the UUID of the customer whose subscriptions are listed.

subscriptions contains an array of subscription objects with the following data:

  • uuid - The UUID of the subscription object generated by ChartMogul.
  • external_id - The unique external identifier for this subscription, as specified by you.
  • plan_uuid - The UUID of the plan object generated by ChartMogul.
  • data_source_uuid - The UUID of the data source that this subscription plan belongs to.
  • cancellation_dates - An array of cancelled_at attributes specified by you. This is an array because a subscription may be re-activated and cancelled several times.

The other keys represent pagination attributes:

  • total_pages - The total number of pages with results for this request.
  • current_page - The page number of this response.

Examples

curl -X GET "https://api.chartmogul.com/v1/import/customers/cus_f466e33d-ff2b-4a11-8f85-417eb02157a7/subscriptions" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_KEY \
     -H "Content-Type: application/json"
ChartMogul::Subscription.all('cus_f466e33d-ff2b-4a11-8f85-417eb02157a7', page: 1, per_page: 200)
ChartMogul.Subscription.all(config, "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7", function(err, res) {
   // asynchronously called
});
<?php

$cus = new ChartMogul\Customer([
    "uuid" => "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7"
        ]);

$subscriptions = $cus->subscriptions();
?>
api.ListSubscriptions(&cm.Cursor{PerPage: 2},
                      "cus_c0dc8d74-edfd-11e6-a357-832dddba822f")
chartmogul.Subscription.all(
    config,
    uuid="cus_c0dc8d74-edfd-11e6-a357-832dddba822f",
    per_page=2)

Result Format

{
  "customer_uuid": "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
  "subscriptions":[
    {
      "uuid": "sub_e6bc5407-e258-4de0-bb43-61faaf062035",
      "external_id": "sub_0001",
      "plan_uuid": "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
      "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
      "cancellation_dates":[]
    }
  ],
  "current_page": 1,
  "total_pages": 1
}
#<ChartMogul::Subscriptions:0x00000003d7c870
 @customer_uuid="cus_510b1395-4fe8-4d35-ae23-0e61f9a51e33",
 @subscriptions=
  [
    #<ChartMogul::Subscription:0x007fb4991dae98 
    @uuid="sub_01e1b5d0-f7dd-441e-870e-62d6b7233a76", 
    @external_id="sub_0001", 
    @plan_uuid="pl_f364391a-c08b-4586-88db-d42ca5608360", 
    @data_source_uuid="ds_d138c0bd-6de1-4cf5-9a16-6f0d3bc540d7", 
    @cancellation_dates=[]
    >
  ],
 @current_page=1,
 @total_pages=1>
{
  "customer_uuid": "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
  "subscriptions":[
    {
      "uuid": "sub_e6bc5407-e258-4de0-bb43-61faaf062035",
      "external_id": "sub_0001",
      "plan_uuid": "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
      "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
      "cancellation_dates":[]
    }
  ],
  "current_page": 1,
  "total_pages": 1
}
<?php

Doctrine\Common\Collections\ArrayCollection::__set_state(array(
   "elements" => 
  array (
    0 => 
    ChartMogul\Subscription::__set_state(array(
       "uuid" => "sub_e6bc5407-e258-4de0-bb43-61faaf062035",
       "external_id" => "sub_0001",
       "cancellation_dates" => 
      array (
      ),
       "plan_uuid" => "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
       "data_source_uuid" => "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  ))),
  "current_page" => 1,
  "total_pages" => 1,
  "customer_uuid" => "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
));
?>
(*chartmogul.Subscriptions)(0xc042088b40)({
 Subscriptions: ([]chartmogul.Subscription) (len=2) {
  (chartmogul.Subscription) {
   UUID: (string) (len=40) "sub_b8ba9b19-0d7d-401c-ad99-496104b435f1",
   ExternalID: (string) (len=8) "sub_0001",
   PlanUUID: (string) (len=39) "pl_8da1caec-ee0b-11e6-a4d9-dbe62a1a1694",
   CustomerUUID: (string) "",
   DataSourceUUID: (string) (len=39) "ds_9bb53a1e-edfd-11e6-bf83-af49e978cb11",
   CancellationDates: ([]string) {
   }
  },
  (chartmogul.Subscription) {
   UUID: (string) (len=40) "sub_00fbccd1-084d-4eec-9805-685ddafcd399",
   ExternalID: (string) (len=8) "sub_0002",
   PlanUUID: (string) (len=39) "pl_8da1caec-ee0b-11e6-a4d9-dbe62a1a1694",
   CustomerUUID: (string) "",
   DataSourceUUID: (string) (len=39) "ds_9bb53a1e-edfd-11e6-bf83-af49e978cb11",
   CancellationDates: ([]string) {
   }
  }
 },
 CustomerUUID: (string) (len=40) "cus_c0dc8d74-edfd-11e6-a357-832dddba822f",
 TotalPages: (uint32) 2,
 CurrentPage: (uint32) 1
})
Subscriptions(subscriptions=[
    <Subscription{
        cancellation_dates=[], 
        data_source_uuid='ds_9bb53a1e-edfd-11e6-bf83-af49e978cb11', 
        external_id='sub_0001', 
        plan_uuid='pl_8da1caec-ee0b-11e6-a4d9-dbe62a1a1694', 
        uuid='sub_b8ba9b19-0d7d-401c-ad99-496104b435f1'}>, 
    <Subscription{
        cancellation_dates=[], 
        data_source_uuid='ds_9bb53a1e-edfd-11e6-bf83-af49e978cb11', 
        external_id='sub_0002', 
        plan_uuid='pl_8da1caec-ee0b-11e6-a4d9-dbe62a1a1694', 
        uuid='sub_00fbccd1-084d-4eec-9805-685ddafcd399'}>], 
current_page=1, 
total_pages=2, 
customer_uuid='cus_c0dc8d74-edfd-11e6-a357-832dddba822f')
Suggest Edits

Cancel a Customer's Subscription

Cancels a subscription that was generated from an imported invoice.

 
patchhttps://api.chartmogul.com/v1/import/subscriptions/SUBSCRIPTION_UUID

Path Params

subscription_uuid
string
required

The ChartMogul UUID of the subscription that needs to be cancelled.

Form Data

cancelled_at
date-time

The time at which the subscription was cancelled. Must be an ISO 8601 formatted time. The timezone defaults to UTC unless otherwise specified. The time defaults to 00:00:00 unless specified otherwise.

cancellation_dates
array of strings

Array of ISO 8601 Timestamps representing all cancellations in the subscription's lifetime. Can be an empty array.

 

In the response, the JSON object contains the following data:

  • uuid - The UUID of the subscription object generated by ChartMogul.
  • external_id - The unique external identifier for this subscription, as specified by you.
  • customer_uuid - the UUID of the customer whose subscription this is.
  • plan_uuid - The UUID of the plan object generated by ChartMogul.
  • cancellation_dates - An array of cancelled_at attributes specified by you. This is an array because a subscription may be re-activated and cancelled several times.
  • data_source_uuid - The UUID of the data source that this subscription plan belongs to.

Subscription cancellation and Churn recognition

If you are using the Import API, ChartMogul always recognizes churn from subscription cancellations at the time of cancellation.

In the example shown here for subscription with UUID sub_e6bc5407-e258-4de0-bb43-61faaf062035, churn will be recognized on January 15th 2016, even though the customer may have paid for a service period ending on January 31st 2016.

Examples

curl -X PATCH "https://api.chartmogul.com/v1/import/subscriptions/sub_e6bc5407-e258-4de0-bb43-61faaf062035" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_KEY \
     -H "Content-Type: application/json" \
     -d '{ 
          "cancelled_at": "2016-01-15 00:00:00"
        }'
        
curl -X PATCH "https://api.chartmogul.com/v1/import/subscriptions/sub_e6bc5407-e258-4de0-bb43-61faaf062035" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_KEY \
     -H "Content-Type: application/json" \
     -d '{ 
          "cancellation_dates": ["2016-01-01T10:00:00.000Z", "2017-01-01T10:00:00.000Z"]
        }'
customer = ChartMogul::Customer.all(external_id:"cus_0001").first
subscription = customer.subscriptions.last
subscription.cancel(Time.utc(2016, 1, 15))

subscription.set_cancellation_dates([Time.utc(2016, 1, 1), Time.utc(2017, 1, 1)])
ChartMogul.Subscription.cancel(config,
   "sub_e6bc5407-e258-4de0-bb43-61faaf062035", 
   { "cancelled_at": "2016-01-15 00:00:00" },
   function(err, res) {
   // asynchronously called
});

ChartMogul.Subscription.cancel(config,
   "sub_e6bc5407-e258-4de0-bb43-61faaf062035", 
   { "cancellation_dates": ["2016-01-01T10:00:00.000Z", "2017-01-01T10:00:00.000Z"] },
   function(err, res) {
   // asynchronously called
});
<?php

$canceldate = "2016-01-15 00:00:00";
$subscription = new ChartMogul\Subscription([
    "uuid" => "sub_e6bc5407-e258-4de0-bb43-61faaf062035"
]);
$subscription->cancel($canceldate);

// Or set cancellation dates
$cancellationDates = ['2016-01-01T10:00:00.000Z', '2017-01-01T10:00:00.000Z']
$subscription = $subscriptions->last()->setCancellationDates($cancellationDates)
?>
api.CancelSubscription(
  "sub_b8ba9b19-0d7d-401c-ad99-496104b435f1",
  &cm.CancelSubscriptionParams{CancelledAt: "2016-01-15T00:00:00Z"})

api.CancelSubscription(
  "sub_b8ba9b19-0d7d-401c-ad99-496104b435f1",
  &cm.CancelSubscriptionParams{
    CancellationDates: []string{
      "2016-01-01T10:00:00.000Z", "2017-01-01T10:00:00.000Z"}})
chartmogul.Subscription.cancel(
    config,
    uuid="sub_00fbccd1-084d-4eec-9805-685ddafcd399",
    data={"cancelled_at": "2016-01-15 00:00:00"}
  
chartmogul.Subscription.cancel(
    config,
    uuid="sub_00fbccd1-084d-4eec-9805-685ddafcd399",
    data={"cancellation_dates":
          ["2016-01-01T10:00:00.000Z", "2017-01-01T10:00:00.000Z"] }

Result Format

{
  "uuid": "sub_e6bc5407-e258-4de0-bb43-61faaf062035",
  "external_id": "sub_0001",
  "customer_uuid": "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
  "plan_uuid": "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
  "cancellation_dates": ["2016-01-15T00:00:00.000Z"],
  "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430"
}

{
  "uuid": "sub_e6bc5407-e258-4de0-bb43-61faaf062035",
  "external_id": "sub_0001",
  "customer_uuid": "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
  "plan_uuid": "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
  "cancellation_dates": ["2016-01-01T10:00:00.000Z", "2017-01-01T10:00:00.000Z"],
  "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430"
}
#<ChartMogul::Subscription:0x007fb4991dae98 
@uuid="sub_01e1b5d0-f7dd-441e-870e-62d6b7233a76", 
@external_id="sub_0001", 
@plan_uuid="pl_f364391a-c08b-4586-88db-d42ca5608360",
@cancellation_dates=[2016-01-15 00:00:00 UTC],
@data_source_uuid="ds_d138c0bd-6de1-4cf5-9a16-6f0d3bc540d7"
>
  
#<ChartMogul::Subscription:0x007fb4991dae98 
@uuid="sub_01e1b5d0-f7dd-441e-870e-62d6b7233a76", 
@external_id="sub_0001", 
@plan_uuid="pl_f364391a-c08b-4586-88db-d42ca5608360",
@cancellation_dates=[2016-01-01 00:00:00 UTC, 2017-01-01 00:00:00 UTC],
@data_source_uuid="ds_d138c0bd-6de1-4cf5-9a16-6f0d3bc540d7"
>
{
  "uuid": "sub_e6bc5407-e258-4de0-bb43-61faaf062035",
  "external_id": "sub_0001",
  "customer_uuid": "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
  "plan_uuid": "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
  "cancellation_dates": ["2016-01-15T00:00:00.000Z"],
  "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430"
}

{
  "uuid": "sub_e6bc5407-e258-4de0-bb43-61faaf062035",
  "external_id": "sub_0001",
  "customer_uuid": "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
  "plan_uuid": "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
  "cancellation_dates": ["2016-01-01T10:00:00.000Z", "2017-01-01T10:00:00.000Z"],
  "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430"
}
<?php

ChartMogul\Subscription::__set_state(array(
   "uuid" => "sub_e6bc5407-e258-4de0-bb43-61faaf062035",
   "external_id" => "sub_0001",
   "cancellation_dates" => 
  array (
    0 => "2016-01-15T00:00:00.000Z",
  ),
   "plan_uuid" => "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
   "data_source_uuid" => "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
));

ChartMogul\Subscription::__set_state(array(
   "uuid" => "sub_e6bc5407-e258-4de0-bb43-61faaf062035",
   "external_id" => "sub_0001",
   "cancellation_dates" => 
  array (
    0 => "2016-01-01T00:00:00.000Z",
    1 => "2017-01-01T00:00:00.000Z",
  ),
   "plan_uuid" => "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
   "data_source_uuid" => "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
));
?>
(*chartmogul.Subscription)(0xc042004bd0)({
 UUID: (string) (len=40) "sub_b8ba9b19-0d7d-401c-ad99-496104b435f1",
 ExternalID: (string) (len=8) "sub_0001",
 PlanUUID: (string) (len=39) "pl_8da1caec-ee0b-11e6-a4d9-dbe62a1a1694",
 CustomerUUID: (string) (len=40) "cus_c0dc8d74-edfd-11e6-a357-832dddba822f",
 DataSourceUUID: (string) (len=39) "ds_9bb53a1e-edfd-11e6-bf83-af49e978cb11",
 CancellationDates: ([]string) (len=1) {
  (string) (len=24) "2016-01-15T00:00:00.000Z"
 }
})

(*chartmogul.Subscription)(0xc042004bd0)({
 UUID: (string) (len=40) "sub_b8ba9b19-0d7d-401c-ad99-496104b435f1",
 ExternalID: (string) (len=8) "sub_0001",
 PlanUUID: (string) (len=39) "pl_8da1caec-ee0b-11e6-a4d9-dbe62a1a1694",
 CustomerUUID: (string) (len=40) "cus_c0dc8d74-edfd-11e6-a357-832dddba822f",
 DataSourceUUID: (string) (len=39) "ds_9bb53a1e-edfd-11e6-bf83-af49e978cb11",
 CancellationDates: ([]string) (len=2) {
  (string) (len=24) "2016-01-01T00:00:00.000Z",
  (string) (len=24) "2017-01-01T00:00:00.000Z"
 }
})
<Subscription{
    cancellation_dates=[datetime.datetime(2016, 1, 15, 0, 0)], 
    customer_uuid='cus_c0dc8d74-edfd-11e6-a357-832dddba822f', 
    data_source_uuid='ds_9bb53a1e-edfd-11e6-bf83-af49e978cb11', 
    external_id='sub_0002', 
    plan_uuid='pl_8da1caec-ee0b-11e6-a4d9-dbe62a1a1694', 
    uuid='sub_00fbccd1-084d-4eec-9805-685ddafcd399'}>

<Subscription{
    cancellation_dates=[
    	datetime.datetime(2016, 1, 1, 0, 0), datetime.datetime(2017, 1, 1, 0, 0)], 
    customer_uuid='cus_c0dc8d74-edfd-11e6-a357-832dddba822f', 
    data_source_uuid='ds_9bb53a1e-edfd-11e6-bf83-af49e978cb11', 
    external_id='sub_0002', 
    plan_uuid='pl_8da1caec-ee0b-11e6-a4d9-dbe62a1a1694', 
    uuid='sub_00fbccd1-084d-4eec-9805-685ddafcd399'}>
Suggest Edits

Introduction to the Enrichment API

The Enrichment API allows users to enrich their customer information in ChartMogul, and leverage the powerful segmentation features that we offer.

 
Suggest Edits

Endpoint Overview

 
Endpoint
Description

Returns a list of all customer objects with the specified email address in your ChartMogul account.

Accepts details of two customer objects that you want to merge.

Retrieves the customer attributes of a given customer.

Adds tags to a given customer.

Adds tags to customers that have the specified email address.

Removes tags from a given customer.

Adds custom attributes to a given customer.

Adds custom attributes to customers that have the specified email address.

Updates the custom attributes of a given customer.

Removes custom attributes from a given customer.

Suggest Edits

Customers

This object represents one of your customers in ChartMogul.

 

You can search for customers with their email address, and merge customers using the following endpoints. You can also retrieve a customer or list all customers to find the customer that you want to enrich.

Suggest Edits

Search for Customers

Returns a list of all customer objects with the specified email address in your ChartMogul account.

 
gethttps://api.chartmogul.com/v1/customers/search

Query Params

email
string
required

The email address of the customer you are searching for. Specified as a query parameter in the request URL.

page
int32

The page number for pagination of results.

per_page
int32

A limit on number of customers to return per page. The default and maximum value is 200.

 

In the response, entries contains an array of customer objects with the following data:

  • id - The internal ChartMogul ID of the customer object.
  • uuid - The UUID of the customer object generated by ChartMogul.
  • external_id - The unique external identifier for this customer, if any.
  • name - The name of this customer.
  • email - This customer's email address.
  • status - The status of this customer. One of Lead, Active or Cancelled.
  • customer-since - An RFC3339 formatted datetime attribute indicating when the customer first started paying for a subscription.
  • attributes - A JSON object representing this customer's attributes containing the following data:
  • tags - An Array of tags that you have added to this customer.
  • stripe - A JSON object representing any metadata on this customer object in your Stripe account.
  • clearbit - A JSON object representing publicly available information about this customer retrieved from Clearbit.
  • custom - A JSON object representing custom attributes that you have added to this customer.
  • address - A JSON object representing this customer's address containing the following data:
    • address_zip - The zip code of this customer's address.
    • city - The city of this customer's address.
    • state - The state from this customer's address.
    • country - The country code of this customer's address as per the ISO-3166 alpha-2 standard.
  • mrr - The current monthly recurring revenue for this customer, expressed in the currency selected for your account, as an integer number of cents. Divide by 100 to obtain the actual amount.
  • arr - The current annual run rate for this customer, also expressed as an integer number of cents in your account's selected currency.
  • billing-system-url - A URL for this customer's data in your billing system, if available.
  • chartmogul-url - The URL for this customer's ChartMogul page. This is only accessible to a user logged in to your ChartMogul account.
  • billing-system-type - The type of the billing system from where the customer was imported to ChartMogul. For example, Stripe, Recurly, Chargify, or Import API.
  • currency - The currency of the MRR readings for this customer.
  • currency-sign - Text representation to display the currency. E.g. $, or €.

The other keys represent pagination attributes:

  • has_more - One of true or false depending on whether there are more pages with results for this request.
  • per_page - The number of results in this response.
  • page - The page number of this response.

Examples

curl -X GET "https://api.chartmogul.com/v1/customers/[email protected]" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_KEY
ChartMogul::Customer.search([email protected]')
ChartMogul.Customer.search(config, {
   email: [email protected]' },
   function (err, res) {
   // asynchronously called
});
<?php

ChartMogul\Customer::search("[email protected]");
?>
api.SearchCustomers(&cm.SearchCustomersParams{
		Email:  "[email protected]",
		Cursor: cm.Cursor{PerPage: 2},
	})
chartmogul.Customer.search(
    config,
    email="[email protected]",
    per_page=2)

Result Format

{
  "entries":[
    {
      "id": 25647,
      "uuid": "cus_de305d54-75b4-431b-adb2-eb6b9e546012",
      "external_id": "34916129",
      "email": "[email protected]",
      "name": "Example Company",
      "address": {
        "address_zip": "0185128",
        "city": "Nowhereville",
        "country": "US",
        "state": "Alaska"
      },
      "mrr": 3000,
      "arr": 36000,
      "status": "Active",
      "customer-since": "2015-06-09T13:16:00-04:00",
      "billing-system-url": "https:\/\/dashboard.stripe.com\/customers\/cus_4Z2ZpyJFuQ0XMb",
      "chartmogul-url": "https:\/\/app.chartmogul.com\/#customers\/25647-Example_Company",
      "billing-system-type": "Stripe",
      "currency": "USD",
      "currency-sign": "$",
      "attributes": {
        "custom": {
          "CAC": 213,
          "utmCampaign": "social media 1",
          "convertedAt": "2015-09-08 00:00:00",
          "pro": false,
          "salesRep": "Gabi"
        },
        "tags": ["engage", "unit loss", "discountable"],
        "stripe": {
          "uid": 7,
          "coupon": true
        }, 
        "clearbit": {
          "id": "027b0d40-016c-40ea-8925-a076fa640992",
          "name": "Acme",
          "legalName": "Acme Inc.",
          "domain": "acme.com",
          "url": "http://acme.com",
          "metrics": {
            "raised": 1502450000,
            "employees": 1000,
            "googleRank": 7,
            "alexaGlobalRank": 2319,
            "marketCap": null
          },
          "category": {
            "sector": "Information Technology",
            "industryGroup": "Software and Services",
            "industry": "Software",
            "subIndustry": "Application Software"
          }
        }
      }
    },
    {"...more...": "...entries..."}
  ],
  "has_more":false,
  "per_page":200,
  "page":1
}
#<ChartMogul::Customers:0x007fd843685d58 
@entries=[
  #<ChartMogul::Customer:0x007faf03b02d68 
  @id=25647, 
  @uuid="cus_de305d54-75b4-431b-adb2-eb6b9e546012", 
  @external_id="34916129",
  @name="Example Company", 
  @email="[email protected]", 
  @status="Active", 
  @customer_since=2015-06-09 13:16:00 -04:00:00,
  @attributes={
    :tags=>["engage", "unit loss", "discountable"], 
    :stripe=>{
      :uid=>7,
      :coupon=>true
    },
    :clearbit=>{
      :id=>"027b0d40-016c-40ea-8925-a076fa640992",
      :name=>"Acme",
      :legalName=> "Acme Inc.",
      :domain=> "acme.com",
      :url=> "http://acme.com",
      :metrics=> {
        :raised=> 1502450000,
        :employees=> 1000,
        :googleRank=> 7,
        :alexaGlobalRank=> 2319,
        :marketCap=> null
      },
      :category=> {
        :sector=> "Information Technology",
        :industryGroup=> "Software and Services",
        :industry=> "Software",
        :subIndustry=> "Application Software"
      }
    },
    :custom=> {
      :CAC=> 213,
      :utmCampaign=> "social media 1",
      :convertedAt=> "2015-09-08 00:00:00",
      :pro=> false,
      :salesRep=> "Gabi"
    }
  }, 
  @address={
    :address_line1=>"First line of address", 
    :address_line2=>"Second line of address", 
    :address_zip=>"0185128",
    :city=>"Nowhereville",
    :state=>"Alaska", 
    :country=>"US"
    }, 
  @mrr=3000, 
  @arr=36000, 
  @billing_system_url="https:\/\/dashboard.stripe.com\/customers\/cus_4Z2ZpyJFuQ0XMb", 
  @chartmogul_url="https:\/\/app.chartmogul.com\/#customers\/25647-Example_Company", 
  @billing_system_type="Stripe", 
  @currency="USD", 
  @currency_sign="$"
  >
],
@has_more=false,
@per_page=200,
@page=1
>
{
  "entries":[
    {
      "id": 25647,
      "uuid": "cus_de305d54-75b4-431b-adb2-eb6b9e546012",
      "external_id": "34916129",
      "email": "[email protected]",
      "name": "Example Company",
      "address": {
        "address_line1": "First line of address",
        "address_line2": "Second line of address",
        "address_zip": "0185128",
        "city": "Nowhereville",
        "country": "US",
        "state": "Alaska"
      },
      "mrr": 3000,
      "arr": 36000,
      "status": "Active",
      "customer-since": "2015-06-09T13:16:00-04:00",
      "billing-system-url": "https:\/\/dashboard.stripe.com\/customers\/cus_4Z2ZpyJFuQ0XMb",
      "chartmogul-url": "https:\/\/app.chartmogul.com\/#customers\/25647-Example_Company",
      "billing-system-type": "Stripe",
      "currency": "USD",
      "currency-sign": "$",
      "attributes": {
        "custom": {
          "CAC": 213,
          "utmCampaign": "social media 1",
          "convertedAt": "2015-09-08 00:00:00",
          "pro": false,
          "salesRep": "Gabi"
        },
        "tags": ["engage", "unit loss", "discountable"],
        "stripe": {
          "uid": 7,
          "coupon": true
        }, 
        "clearbit": {
          "id": "027b0d40-016c-40ea-8925-a076fa640992",
          "name": "Acme",
          "legalName": "Acme Inc.",
          "domain": "acme.com",
          "url": "http://acme.com",
          "metrics": {
            "raised": 1502450000,
            "employees": 1000,
            "googleRank": 7,
            "alexaGlobalRank": 2319,
            "marketCap": null
          },
          "category": {
            "sector": "Information Technology",
            "industryGroup": "Software and Services",
            "industry": "Software",
            "subIndustry": "Application Software"
          }
        }
      }
    },
    {"...more...": "...entries..."}
  ],
  "has_more":false,
  "per_page":200,
  "page":1
}
<?php

ChartMogul\Customers::__set_state(array(
    "current_page" => 1,
    "total_pages" => 1,
    "has_more" => false,
    "per_page" => 200,
    "page" => 1,
    "entries" =>
  Doctrine\Common\Collections\ArrayCollection::__set_state(array(
     "elements" =>
    array (
      0 =>
      ChartMogul\Customer::__set_state(array(
         "id" => 25647,
         "uuid" => "cus_de305d54-75b4-431b-adb2-eb6b9e546012",
         "external_id" => "34916129",
         "name" => "Example Company",
         "email" => "[email protected]",
         "status" => "Active",
         "customer_since" => "2015-06-09T13:16:00-04:00",
         "attributes" =>
        array (
          "custom" =>
          array (
            "CAC" => 213,
            "utmCampaign" => "social media 1",
            "convertedAt" => "2015-09-08 00 =>00 =>00",
            "pro" => false,
            "salesRep" => "Gabi"
          ),
          "clearbit" =>
          array (
            "id" => "027b0d40-016c-40ea-8925-a076fa640992",
            "name" => "Acme",
            "legalName" => "Acme Inc.",
            "domain" => "acme.com",
            "url" => "http =>//acme.com",
            "metrics" => array (
              "raised" => 1502450000,
              "employees" => 1000,
              "googleRank" => 7,
              "alexaGlobalRank" => 2319,
              "marketCap" => null
            ),
            "category" => array (
              "sector" => "Information Technology",
              "industryGroup" => "Software and Services",
              "industry" => "Software",
              "subIndustry" => "Application Software"
            )
          ),
          "stripe" =>
          array (
            "uid" => 7,
            "coupon" => true
          ),
          "tags" =>
          array (
            0 => "engage",
            1 => "unit loss",
            2 => "discountable"
          ),
        ),
         "address" =>
        array (
          "address_line1" => "First line of address",
          "address_line2" => "Second line of address",
          "address_zip" => "0185128",
          "city" => "Nowhereville",
          "state" => "Alaska",
          "country" => "US"
        ),
         "mrr" => 3000,
         "arr" => 36000,
         "billing_system_url" => "https:\/\/dashboard.stripe.com\/customers\/cus_4Z2ZpyJFuQ0XMb",
         "chartmogul_url" => "https:\/\/app.chartmogul.com\/#customers\/25647-Example_Company",
         "billing_system_type" => "Stripe",
         "currency" => "USD",
         "currency_sign" => "$",
         "data_source_uuid" => "ds_80686670-cc45-11e6-b9da-ff67b9895fe3",
         "data_source_uuids" =>
        array (
          0 => "ds_80686670-cc45-11e6-b9da-ff67b9895fe3",
        ),
         "external_ids" =>
        array (
          0 => "cus_0001",
        ),
         "city" => "Nowhereville",
         "country" => "US",
         "state" => "Alaska",
         "zip" => "0185128",
         "lead_created_at" => "2015-10-14T00:00:00.000Z",
         "free_trial_started_at" => "2015-11-01T00:00:00.000Z",
         "company" => "",
    ))
  )))
));
?>
(*chartmogul.Customers)(0xc042088b40)({
 Entries: ([]*chartmogul.Customer) (len=2) {
  (*chartmogul.Customer)(0xc0421c6160)({
   ID: (uint32) 4861688,
   DataSourceUUID: (string) (len=39) "ds_9bb53a1e-edfd-11e6-bf83-af49e978cb11",
   UUID: (string) (len=40) "cus_c0dc8d74-edfd-11e6-a357-832dddba822f",
   ExternalID: (string) (len=8) "cus_0001",
   Name: (string) (len=10) "Adam Smith",
   Email: (string) (len=14) "[email protected]",
   Status: (string) (len=6) "Active",
   CustomerSince: (string) (len=25) "2015-11-01T00:00:00+00:00",
   Attributes: (*chartmogul.Attributes)(0xc0420067b0)({
    Tags: ([]string) (len=1) {
     (string) (len=10) "high-value"
    },
    Stripe: (*chartmogul.Stripe)(0xc04200c5b0)({
     UID: (uint64) 0,
     Coupon: (bool) false
    }),
    Clearbit: (*chartmogul.Clearbit)(0xc0420da3c0)({
     ID: (string) "",
     Name: (string) "",
     LegalName: (string) "",
     Domain: (string) "",
     URL: (string) "",
     Metrics: (map[string]interface {}) <nil>,
     Category: (*chartmogul.Category)(<nil>)
    }),
    Custom: (map[string]interface {}) (len=2) {
     (string) (len=3) "CAC": (float64) 25,
     (string) (len=7) "channel": (string) (len=8) "Facebook"
    }
   }),
   Address: (*chartmogul.Address)(0xc0420084c0)({
    AddressZIP: (string) "",
    City: (string) (len=6) "Juneau",
    State: (string) (len=6) "Alaska",
    Country: (string) (len=13) "United States"
   }),
   Mrr: (float64) 4100,
   Arr: (float64) 49200,
   BillingSystemURL: (string) "",
   ChartmogulURL: (string) (len=56) "https://app.chartmogul.com/#customers/4861688-Adam_Smith",
   BillingSystemType: (string) (len=10) "Import API",
   Currency: (string) (len=3) "USD",
   CurrencySign: (string) (len=1) "$",
   Company: (string) "",
   Country: (string) (len=2) "US",
   State: (string) (len=2) "AK",
   City: (string) (len=6) "Juneau",
   LeadCreatedAt: (string) (len=24) "2015-01-01T00:00:00.000Z",
   FreeTrialStartedAt: (string) (len=24) "2015-06-13T15:45:13.000Z",
   Errors: (chartmogul.Errors) chartmogul: map[]
  }),
  (*chartmogul.Customer)(0xc0421c66e0)({
   ID: (uint32) 4865413,
   DataSourceUUID: (string) (len=39) "ds_9bb53a1e-edfd-11e6-bf83-af49e978cb11",
   UUID: (string) (len=40) "cus_b3e32f0e-edff-11e6-8a4b-7f2150c9ba2f",
   ExternalID: (string) (len=8) "cus_0004",
   Name: (string) (len=10) "Adam Smith",
   Email: (string) (len=14) "[email protected]",
   Status: (string) (len=4) "Lead",
   CustomerSince: (string) "",
   Attributes: (*chartmogul.Attributes)(0xc042006a80)({
    Tags: ([]string) {
    },
    Stripe: (*chartmogul.Stripe)(0xc04200c6d0)({
     UID: (uint64) 0,
     Coupon: (bool) false
    }),
    Clearbit: (*chartmogul.Clearbit)(0xc0420da420)({
     ID: (string) "",
     Name: (string) "",
     LegalName: (string) "",
     Domain: (string) "",
     URL: (string) "",
     Metrics: (map[string]interface {}) <nil>,
     Category: (*chartmogul.Category)(<nil>)
    }),
    Custom: (map[string]interface {}) {
    }
   }),
   Address: (*chartmogul.Address)(0xc042008540)({
    AddressZIP: (string) "",
    City: (string) (len=8) "New York",
    State: (string) "",
    Country: (string) (len=13) "United States"
   }),
   Mrr: (float64) 0,
   Arr: (float64) 0,
   BillingSystemURL: (string) "",
   ChartmogulURL: (string) (len=56) "https://app.chartmogul.com/#customers/4865413-Adam_Smith",
   BillingSystemType: (string) (len=10) "Import API",
   Currency: (string) (len=3) "USD",
   CurrencySign: (string) (len=1) "$",
   Company: (string) "",
   Country: (string) (len=2) "US",
   State: (string) "",
   City: (string) (len=8) "New York",
   LeadCreatedAt: (string) (len=24) "2015-10-14T00:00:00.000Z",
   FreeTrialStartedAt: (string) (len=24) "2015-11-01T00:00:00.000Z",
   Errors: (chartmogul.Errors) chartmogul: map[]
  })
 },
 Page: (uint32) 1,
 PerPage: (uint32) 2,
 HasMore: (bool) true,
 CurrentPage: (int32) 1,
 TotalPages: (int32) 0
})
Customers(entries=[
    <Customer{
        address=<Address{
            address_zip=None, 
            city='Juneau', 
            country='United States', 
            state='Alaska'}>, 
        arr=49200.0, 
        attributes=<Attributes{
            clearbit=<Clearbit{
            }>, 
            custom={
                'CAC': 25, 
                'channel': 'Facebook'}, 
            stripe=<Stripe{
            }>, 
        tags=['high-value']}>, 
        billing_system_type='Import API', 
        billing_system_url=None, 
        chartmogul_url='https://app.chartmogul.com/#customers/4861688-Adam_Smith', 
        city='Juneau', 
        company='', 
        country='US', 
        currency='USD', 
        currency_sign='$', 
        customer_since=datetime.datetime(2015, 11, 1, 0, 0), 
        data_source_uuid='ds_9bb53a1e-edfd-11e6-bf83-af49e978cb11', 
        data_source_uuids=['ds_9bb53a1e-edfd-11e6-bf83-af49e978cb11'], 
        email=[email protected]', 
        external_id='cus_0001', 
        external_ids=['cus_0001'], 
        free_trial_started_at=datetime.datetime(2015, 6, 13, 15, 45, 13), 
        id=4861688, 
        lead_created_at=datetime.datetime(2015, 1, 1, 0, 0), 
        mrr=4100.0, 
        name='Adam Smith', 
        state='AK', 
        status='Active', 
        uuid='cus_c0dc8d74-edfd-11e6-a357-832dddba822f', 
        zip=None}>, 
    <Customer{
    address=<Address{
        address_zip=None, 
        city='New York', 
        country='United States', 
        state=None}>, 
    arr=0.0, 
    attributes=<Attributes{
        clearbit=<Clearbit{
        }>, 
        custom={
        }, 
        stripe=<Stripe{
        }>, 
        tags=[]}>, 
    billing_system_type='Import API', 
    billing_system_url=None, 
    chartmogul_url='https://app.chartmogul.com/#customers/4865413-Adam_Smith', 
    city='New York', 
    company='', 
    country='US', 
    currency='USD', 
    currency_sign='$', 
    customer_since=None, 
    data_source_uuid='ds_9bb53a1e-edfd-11e6-bf83-af49e978cb11', 
    data_source_uuids=['ds_9bb53a1e-edfd-11e6-bf83-af49e978cb11'], 
    email=[email protected]', 
    external_id='cus_0004', 
    external_ids=['cus_0004'], 
    free_trial_started_at=datetime.datetime(2015, 11, 1, 0, 0), 
    id=4865413, 
    lead_created_at=datetime.datetime(2015, 10, 14, 0, 0), 
    mrr=0.0, 
    name='Adam Smith', 
    state=None, 
    status='Lead', 
    uuid='cus_b3e32f0e-edff-11e6-8a4b-7f2150c9ba2f', 
    zip=None}>], 
has_more=True, 
per_page=2, 
page=1, 
current_page=1, 
total_pages=None)
Suggest Edits

Merge Customers

Accepts details of two customer objects that you want to merge.

 
posthttps://api.chartmogul.com/v1/customers/merges

Form Data

from
object
required

Details of the customer you want to merge data from (you can use the customer’s UUID or external ID).

into
object
required

Details of the customer you want to merge data into (you can use the customer’s UUID or external ID).

 

Once a valid request is received by the API, it will respond with 202 - Accepted, and the merging function will proceed to work asynchronously.

Merged customers

The merged customer will have the ChartMogul Customer UUID, email address, and location of the customer identified using the into key. Both customers’ external IDs, tags, custom attributes, and notes will be preserved. Subscriptions, MRR movements and transactions will be collated and ordered by date. If both customers have the same custom field, the value retained for the field will be that of the customer specified in into.

You can see the merged customer reported in your ChartMogul account.

Examples

# Example using Customer UUIDs for identifying customers to merge

curl -X POST "https://api.chartmogul.com/v1/customers/merges" \
       -u <token>:<secret>
       -H "Content-Type: application/json"
       -d {
             "from": {"customer_uuid": "cus_de305d54-75b4-431b-adb2-eb6b9e546012"},
             "into": {"customer_uuid": "cus_ab223d54-75b4-431b-adb2-eb6b9e234571"}
           }
           
# Example using Data Source UUIDs and External IDs for identifying customers to merge

curl -X POST "https://api.chartmogul.com/v1/customers/merges" \
       -u <token>:<secret>
       -H "Content-Type: application/json"
       -d {
             "from": {"data_source_uuid": "ds_ade45e52-47a4-231a-1ed2-eb6b9e541213",
                      "external_id": "cus_187544"},
             "into": {"data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
                      "external_id": "34916129"}
           }
# Example using Customer UUIDs

from_customer = ChartMogul::Customer.retrieve('cus_de305d54-75b4-431b-adb2-eb6b9e546012')
into_customer = ChartMogul::Customer.retrieve('cus_ab223d54-75b4-431b-adb2-eb6b9e234571')

from_customer.merge_into!(into_customer)
// Example using Customer UUIDs
ChartMogul.Customer.merge(config, {
  "from": {"customer_uuid": "cus_5915ee5a-babd-406b-b8ce-d207133fb4cb"},
  "into": {"customer_uuid": "cus_2123290f-09c8-4628-a205-db5596bd58f7"}
})
<?php

ChartMogul\Customer::merge([
    "customer_uuid" => "cus_5915ee5a-babd-406b-b8ce-d207133fb4cb"
        ], [
    "customer_uuid" => "cus_2123290f-09c8-4628-a205-db5596bd58f7"
]);
?>
// Example using Customer UUIDs
api.MergeCustomers(&cm.MergeCustomersParams{
  From: cm.CustID{CustomerUUID: "cus_5915ee5a-babd-406b-b8ce-d207133fb4cb"},
  To:   cm.CustID{CustomerUUID: "cus_2123290f-09c8-4628-a205-db5596bd58f7"},
})
# Example using Customer UUIDs
chartmogul.Customer.merge(config, data={
    "from": {
        "customer_uuid": "cus_5915ee5a-babd-406b-b8ce-d207133fb4cb"
    },
    "into": {
        "customer_uuid": "cus_2123290f-09c8-4628-a205-db5596bd58f7"
    }
})

Result Format

{ }
true
{ }
true
None
<Customer{}>
Suggest Edits

Customer Attributes

Customer attributes are metadata that can be used to filter and segment your customers in ChartMogul.

 

The types of customer attributes available via the Enrichment API are:

  • Tags
  • Stripe metadata
  • Clearbit data
  • Custom Attributes

The Enrichment API allows you to manipulate Tags and Custom Attributes on your customers. It also allows you to retrieve metadata that we automatically pull from Stripe and Clearbit to enrich your customer profiles.

Suggest Edits

Retrieve Customer's Attributes

Retrieves the customer attributes of a given customer.

 
gethttps://api.chartmogul.com/v1/customers/CUSTOMER_UUID/attributes

Path Params

customer_uuid
string
required

The ChartMogul UUID of the customer whose attributes are required.

 

The response contains the customer's attributes with the following data:

  • tags - An Array of tags that you have added to this customer.
  • stripe - A JSON object representing any metadata on this customer object in your Stripe account.
  • clearbit - A JSON object representing publicly available information about this customer retrieved from Clearbit.
  • custom - A JSON object representing custom attributes that you have added to this customer.

Examples

curl -X GET "https://api.chartmogul.com/v1/customers/cus_de305d54-75b4-431b-adb2-eb6b9e546012/attributes" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_KEY
customer = ChartMogul::Customer.retrieve('cus_de305d54-75b4-431b-adb2-eb6b9e546012')
customer.attributes
ChartMogul.Customer.attributes(config, "cus_de305d54-75b4-431b-adb2-eb6b9e546012", function (err, res) {
   // asynchronously called
});
<?php

$customer = ChartMogul\Customer::retrieve(
  						"cus_de305d54-75b4-431b-adb2-eb6b9e546012");
$customer->attributes;
?>
api.RetrieveCustomersAttributes("cus_c0dc8d74-edfd-11e6-a357-832dddba822f")
chartmogul.Attributes.retrieve(
    config,
    uuid='cus_c0dc8d74-edfd-11e6-a357-832dddba822f')

Result Format

{
  "tags": ["engage", "unit loss", "discountable"],
  "stripe": {
    "uid": 7,
    "coupon": true
  },
  "clearbit": {
    "company": {
      "name": "Example Company",
      "legalName": "Example Company Inc.",
      "domain": "examplecompany.com",
      "url": "http://examplecompany.com",
      "category": {
        "sector": "Information Technology",
        "industryGroup": "Software and Services",
        "industry": "Software",
        "subIndustry": "Application Software"
      },
      "metrics": {
        "raised": 1502450000,
        "employees": 1000,
        "googleRank": 7,
        "alexaGlobalRank": 2319,
        "marketCap": null
      },
    },
    "person": {
      "name": {
        "fullName": "Bob Kramer"
      },
      "employment": {
        "name": "Example Company"
      }
    }
  },
  "custom": {
    "CAC": 213,
    "utmCampaign": "social media 1",
    "convertedAt": "2015-09-08 00:00:00",
    "pro": false,
    "salesRep": "Gabi"
  }
}
{
  :tags=>["engage", "unit loss", "discountable"], 
  :stripe=>{
    :uid=>7,
    :coupon=>true
  },
  :clearbit=>{
    :id=>"027b0d40-016c-40ea-8925-a076fa640992",
    :name=>"Acme",
    :legalName=> "Acme Inc.",
    :domain=> "acme.com",
    :url=> "http://acme.com",
    :metrics=> {
      :raised=> 1502450000,
      :employees=> 1000,
      :googleRank=> 7,
      :alexaGlobalRank=> 2319,
      :marketCap=> null
    },
    :category=> {
      :sector=> "Information Technology",
      :industryGroup=> "Software and Services",
      :industry=> "Software",
      :subIndustry=> "Application Software"
    }
  },
  :custom=> {
    :CAC=> 213,
    :utmCampaign=> "social media 1",
    :convertedAt=> "2015-09-08 00:00:00",
    :pro=> false,
    :salesRep=> "Gabi"
  }
}
{
  "tags": ["engage", "unit loss", "discountable"],
  "stripe": {
    "uid": 7,
    "coupon": true
  },
  "clearbit": {
    "company": {
      "name": "Example Company",
      "legalName": "Example Company Inc.",
      "domain": "examplecompany.com",
      "url": "http://examplecompany.com",
      "category": {
        "sector": "Information Technology",
        "industryGroup": "Software and Services",
        "industry": "Software",
        "subIndustry": "Application Software"
      },
      "metrics": {
        "raised": 1502450000,
        "employees": 1000,
        "googleRank": 7,
        "alexaGlobalRank": 2319,
        "marketCap": null
      },
    },
    "person": {
      "name": {
        "fullName": "Bob Kramer"
      },
      "employment": {
        "name": "Example Company"
      }
    }
  },
  "custom": {
    "CAC": 213,
    "utmCampaign": "social media 1",
    "convertedAt": "2015-09-08 00:00:00",
    "pro": false,
    "salesRep": "Gabi"
  }
}
<?php

array (
  'custom' =>
  array (
    'CAC' => 213,
    'utmCampaign' => 'social media 1',
    'convertedAt' => '2015-09-08T00:00:00.000Z',
    'pro' => false,
    'salesRep' => 'Gabi',
  ),
  'clearbit' =>
  array (
    "company" => array (
      "name" => "Example Company",
      "legalName" => "Example Company Inc.",
      "domain" => "examplecompany.com",
      "url" => "http =>//examplecompany.com",
      "category" => array (
        "sector" => "Information Technology",
        "industryGroup" => "Software and Services",
        "industry" => "Software",
        "subIndustry" => "Application Software"
      ),
      "metrics" => array (
        "raised" => 1502450000,
        "employees" => 1000,
        "googleRank" => 7,
        "alexaGlobalRank" => 2319,
        "marketCap" => null
      ),
    ),
    "person" => array (
      "name" => array (
        "fullName" => "Bob Kramer"
      ),
      "employment" => array (
        "name" => "Example Company"
      )
    )
  ),
  'stripe' =>
  array (
    "uid" => 7,
    "coupon" => true
  ),
  'tags' => 
  array (
    0 => 'engage',
    1 => 'unit loss',
    2 => 'discountable',
  ),
)
?>
(*chartmogul.Attributes)(0xc042042f30)({
 Tags: ([]string) (len=2) {
  (string) (len=15) "merged-customer",
  (string) (len=10) "high-value"
 },
 Stripe: (*chartmogul.Stripe)(<nil>),
 Clearbit: (*chartmogul.Clearbit)(<nil>),
 Custom: (map[string]interface {}) (len=2) {
  (string) (len=3) "CAC": (float64) 25,
  (string) (len=7) "channel": (string) (len=8) "Facebook"
 }
})
<Attributes{
    custom={
        'CAC': 25, 
        'channel': 'Facebook'}, 
    tags=['merged-customer', 
    'high-value']}>
Suggest Edits

Tags

Tags are a type of customer attribute.

 

Think of them as keywords that can be used to describe properties of customers.

Tags are useful for storing unstructured information on a customer object. There is no limit to the number of tags you can add to a customer object in ChartMogul.

Suggest Edits

Add Tags to a Customer

Adds tags to a given customer.

 
posthttps://api.chartmogul.com/v1/customers/CUSTOMER_UUID/attributes/tags

Path Params

customer_uuid
string
required

The ChartMogul UUID of the customer.

Form Data

tags
array of strings
required

An Array of tags to be added to the customer.

 

In the response, tags contains an Array with all the tags now on this customer.

Examples

curl -X POST "https://api.chartmogul.com/v1/customers/cus_de305d54-75b4-431b-adb2-eb6b9e546012/attributes/tags" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_KEY \
     -H "Content-Type: application/json" \
     -d '{
          "tags": ["important", "Prio1"]
         }'
customer = ChartMogul::Customer.retrieve('cus_de305d54-75b4-431b-adb2-eb6b9e546012')
customer.add_tags!('important', 'Prio1')
ChartMogul.Tag.add(config, "cus_de305d54-75b4-431b-adb2-eb6b9e546012", {
   "tags": ["important", "Prio1"]
   }, function (err, res) {
   // asynchronously called
});
<?php

$customer = ChartMogul\Customer::retrieve(
    				"cus_de305d54-75b4-431b-adb2-eb6b9e546012");
$customer->addTags("important", "Prio1");
?>
api.AddTagsToCustomer(
		"cus_c0dc8d74-edfd-11e6-a357-832dddba822f",
		[]string{"important", "Prio1"})
chartmogul.Tags.add(
    config,
    uuid="cus_c0dc8d74-edfd-11e6-a357-832dddba822f",
    data={
      "tags": ["important", "Prio1"]
    })

Result Format

{
  "tags": ["engage", "unit loss", "discountable", "important", "Prio1"]
}
["engage", "unit loss", "discountable", "important", "Prio1"]
{
  "tags": ["engage", "unit loss", "discountable", "important", "Prio1"]
}
<?php

array (
  0 => 'engage',
  1 => 'unit loss',
  2 => 'discountable',
  3 => "important",
  4 => "Prio1"
)
?>
(*chartmogul.TagsResult)(0xc0420c8bc0)({
 Tags: ([]string) (len=4) {
  (string) (len=15) "merged-customer",
  (string) (len=10) "high-value",
  (string) (len=9) "important",
  (string) (len=5) "Prio1"
 }
})
<Tags{
    tags=['merged-customer', 
    'high-value', 
    'important', 
    'Prio1']}>
Suggest Edits

Add Tags to Customers with email

Adds tags to customers that have the specified email address.

 
posthttps://api.chartmogul.com/v1/customers/attributes/tags

Form Data

email
string
required

The email address of the customers to whom tags must be added.

tags
array of strings
required

An Array of tags to be added to the customers.

 

In the response, entries contains an array of JSON objects with the following data:

  • id - The internal ChartMogul ID of the customer object with specified email.
  • uuid - The UUID of the customer object generated by ChartMogul.
  • external_id - The unique external identifier for this customer, if any.
  • name - The name of this customer.
  • email - This customer's email address.
  • status - The status of this customer. One of Active or Cancelled, depending on whether the customer has any active subscriptions or not.
  • customer-since - An RFC3339 formatted datetime attribute indicating when the customer first started paying for a subscription.
  • attributes - A JSON object representing this customer's attributes containing the following data:
  • tags - An Array of all the tags now on this customer.
  • stripe - A JSON object representing any metadata on this customer object in your Stripe account.
  • clearbit - A JSON object representing publicly available information about this customer retrieved from Clearbit.
  • custom - A JSON object representing custom attributes that you have added to this customer.

Examples

curl -X POST "https://api.chartmogul.com/v1/customers/attributes/tags" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_KEY \
     -H "Content-Type: application/json" \
     -d '{
           "email": "[email protected]",
           "tags": ["important", "Prio1"]
         }'
customers = ChartMogul::Customer.search([email protected]')
customers.each {|c| c.add_tags!('important', 'Prio1') }
ChartMogul.Tag.add(config, {
   "email": [email protected]',
   "tags": ["important21", "Prio22"]
   }, function (err, res) {
   // asynchronously called
});
<?php

$customers = ChartMogul\Customer::search("[email protected]");

foreach ($customers->entries as $customer) {
    $customer->addTags(["important21", "Prio22"]);
}
?>
api.AddTagsToCustomersWithEmail(
		"[email protected]",
		[]string{"important2", "Prio2"})
chartmogul.Tags.add(
    config,
    data={
        "email": "[email protected]",
        "tags": ["important2", "Prio2"]
  	})

Result Format

{
  "entries": [
    {
      "id": 25647,
      "uuid": "cus_de305d54-75b4-431b-adb2-eb6b9e546012",
      "external_id": "40574176",
      "name": "Smith Company",
      "email": "[email protected]",
      "status": "Active",
      "customer-since": "2015-06-09T13:16:00-04:00",
      "attributes":  {
        "tags": ["important", "Prio1"],
        "stripe": {
          "coupon": true
        },
        "clearbit": {
          "name": "Acme"
        },
        "custom": {
          "CAC": 213
        }
      }
    },
    {
      "id": 13456,
      "uuid": "cus_fb305d54-75b4-431b-2334-eb6b9e540016",
      "external_id": "58473129",
      "name": "Adam",
      "email": "[email protected]",
      "customer-since": "2015-06-10T13:16:00-04:00",
      "status": "Active",
      "attributes":  {
        "tags": ["important", "Prio1"],
        "stripe": {
          "coupon": false
        },
        "clearbit": {
          "name": "Umbrella Corp"
        },
        "custom": {
          "CAC": 32
        }
      }
    }
  ]
}
[
  #<ChartMogul::Customer:0x007fc7e1ca7028 
  @id=25647, 
  @uuid="cus_de305d54-75b4-431b-adb2-eb6b9e546012", 
  @external_id="40574176", 
  @name="Smith Company", 
  @email="[email protected]", 
  @status="Active", 
  @customer_since=2015-06-09 13:16:00 -04:00,
  @attributes={
    :tags=>["important", "Prio1"], 
    :stripe=>{
      :coupon=> true
    },
    :clearbit=>{
      :name=> "Acme"
    },
    :custom=>{
      :CAC=> 213
    }
  }, 
  @address={
    :address_line1=>"First line of address",
    :address_line2=>"Second line of address",
    :address_zip=>"0185128",
    :city=>"Nowhereville",
    :state=>"Alaska",
    :country=>"US"
  },
  @mrr=3000,
  @arr=36000,
  @billing_system_url="https:\/\/dashboard.stripe.com\/customers\/cus_4Z2ZpyJFuQ0XMb",
  @chartmogul_url="https:\/\/app.chartmogul.com\/#customers\/25647-Example_Company",
  @billing_system_type="Stripe",
  @currency="USD",
  @currency_sign="$"
  >,
  #<ChartMogul::Customer:0x005ec6a0ca7123 
  @id=13456, 
  @uuid="cus_fb305d54-75b4-431b-2334-eb6b9e540016", 
  @external_id="58473129", 
  @name="Adam", 
  @email="[email protected]", 
  @status="Active", 
  @customer_since=2015-06-10 13:16:00 -04:00,
  @attributes={
    :tags=>["important", "Prio1"], 
    :stripe=>{
      :coupon=> false
    },
    :clearbit=>{
      :name=> "Umbrella Corp."
    },
    :custom=>{
      :CAC=> 32
    }
  }, 
  @address={
    :address_line1=>"First line of address",
    :address_line2=>"Second line of address",
    :address_zip=>"",
    :city=>"",
    :state=>"",
    :country=>""
  },
  @mrr=400,
  @arr=4800,
  @billing_system_url="",
  @chartmogul_url="https:\/\/app.chartmogul.com\/#customers\/13456-Adam",
  @billing_system_type="ImportApi",
  @currency="USD",
  @currency_sign="$"
  >
]
{
  "entries": [
    {
      "id": 25647,
      "uuid": "cus_de305d54-75b4-431b-adb2-eb6b9e546012",
      "external_id": "40574176",
      "name": "Smith Company",
      "email": "[email protected]",
      "status": "Active",
      "customer-since": "2015-06-09T13:16:00-04:00",
      "attributes":  {
        "tags": ["important", "Prio1"],
        "stripe": {
          "coupon": true
        },
        "clearbit": {
          "name": "Acme"
        },
        "custom": {
          "CAC": 213
        }
      }
    },
    {
      "id": 13456,
      "uuid": "cus_fb305d54-75b4-431b-2334-eb6b9e540016",
      "external_id": "58473129",
      "name": "Adam",
      "email": "[email protected]",
      "customer-since": "2015-06-10T13:16:00-04:00",
      "status": "Active",
      "attributes":  {
        "tags": ["important", "Prio1"],
        "stripe": {
          "coupon": false
        },
        "clearbit": {
          "name": "Umbrella Corp"
        },
        "custom": {
          "CAC": 32
        }
      }
    }
  ]
}
<?php

array (
  0 => "important",
  1 => "Prio1"
)
array (
  0 => "important",
  1 => "Prio1"
)
?>
(*chartmogul.Customers)(0xc042088b40)({
 Entries: ([]*chartmogul.Customer) (len=11) {
  (*chartmogul.Customer)(0xc04207ec60)({
   ID: (uint32) 4861688,
   DataSourceUUID: (string) "",
   UUID: (string) (len=40) "cus_c0dc8d74-edfd-11e6-a357-832dddba822f",
   ExternalID: (string) (len=8) "cus_0001",
   Name: (string) (len=10) "Adam Smith",
   Email: (string) (len=14) "[email protected]",
   Status: (string) (len=6) "Active",
   CustomerSince: (string) (len=25) "2015-11-01T00:00:00+00:00",
   Attributes: (*chartmogul.Attributes)(0xc042089440)({
    Tags: ([]string) (len=6) {
     (string) (len=15) "merged-customer",
     (string) (len=10) "high-value",
     (string) (len=10) "important2",
     (string) (len=5) "Prio2"
    },
    Stripe: (*chartmogul.Stripe)(0xc0420418b0)({
     UID: (uint64) 0,
     Coupon: (bool) false
    }),
    Clearbit: (*chartmogul.Clearbit)(0xc04203eae0)({
     ID: (string) "",
     Name: (string) "",
     LegalName: (string) "",
     Domain: (string) "",
     URL: (string) "",
     Metrics: (map[string]interface {}) <nil>,
     Category: (*chartmogul.Category)(<nil>)
    }),
    Custom: (map[string]interface {}) (len=2) {
     (string) (len=3) "CAC": (float64) 25,
     (string) (len=7) "channel": (string) (len=8) "Facebook"
    }
   }),
   Address: (*chartmogul.Address)(<nil>),
   Mrr: (float64) 0,
   Arr: (float64) 0,
   BillingSystemURL: (string) "",
   ChartmogulURL: (string) "",
   BillingSystemType: (string) "",
   Currency: (string) "",
   CurrencySign: (string) "",
   Company: (string) "",
   Country: (string) "",
   State: (string) "",
   City: (string) "",
   LeadCreatedAt: (string) "",
   FreeTrialStartedAt: (string) "",
   Errors: (chartmogul.Errors) chartmogul: map[]
  }),
  (*chartmogul.Customer)(0xc04207f080)({
   ID: (uint32) 4874834,
   DataSourceUUID: (string) "",
   UUID: (string) (len=40) "cus_922c2672-ee04-11e6-bea8-7fac984477db",
   ExternalID: (string) (len=8) "cus_0013",
   Name: (string) (len=10) "Adam Smith",
   Email: (string) (len=14) "[email protected]",
   Status: (string) (len=4) "Lead",
   CustomerSince: (string) "",
   Attributes: (*chartmogul.Attributes)(0xc0420895c0)({
    Tags: ([]string) (len=2) {
     (string) (len=10) "important2",
     (string) (len=5) "Prio2"
    },
    Stripe: (*chartmogul.Stripe)(0xc042041930)({
     UID: (uint64) 0,
     Coupon: (bool) false
    }),
    Clearbit: (*chartmogul.Clearbit)(0xc04203eba0)({
     ID: (string) "",
     Name: (string) "",
     LegalName: (string) "",
     Domain: (string) "",
     URL: (string) "",
     Metrics: (map[string]interface {}) <nil>,
     Category: (*chartmogul.Category)(<nil>)
    }),
    Custom: (map[string]interface {}) {
    }
   }),
   Address: (*chartmogul.Address)(<nil>),
   Mrr: (float64) 0,
   Arr: (float64) 0,
   BillingSystemURL: (string) "",
   ChartmogulURL: (string) "",
   BillingSystemType: (string) "",
   Currency: (string) "",
   CurrencySign: (string) "",
   Company: (string) "",
   Country: (string) "",
   State: (string) "",
   City: (string) "",
   LeadCreatedAt: (string) "",
   FreeTrialStartedAt: (string) "",
   Errors: (chartmogul.Errors) chartmogul: map[]
  }),
 },
 Page: (uint32) 1,
 PerPage: (uint32) 0,
 HasMore: (bool) false,
 CurrentPage: (int32) 1,
 TotalPages: (int32) 1
})
Customers(entries=[
    <Customer{
        attributes=<Attributes{
            clearbit=<Clearbit{
            }>, 
            custom={
                'CAC': 25, 
                'channel': 'Facebook'}, 
            stripe=<Stripe{
            }>, 
            tags=['merged-customer', 
            'high-value', 
            'important2', 
            'Prio2']}>, 
        customer_since=datetime.datetime(2015, 11, 1, 0, 0), 
        email=[email protected]', 
        external_id='cus_0001', 
        id=4861688, 
        name='Adam Smith', 
        status='Active', 
        uuid='cus_c0dc8d74-edfd-11e6-a357-832dddba822f'}>, 
    <Customer{
        attributes=<Attributes{
            clearbit=<Clearbit{
            }>, 
            custom={
            }, 
            stripe=<Stripe{
            }>, 
            tags=['important2', 'Prio2']}>, 
        customer_since=None, 
        email=[email protected]', 
        external_id='cus_0013', 
        id=4874834, 
        name='Adam Smith', 
        status='Lead', 
        uuid='cus_922c2672-ee04-11e6-bea8-7fac984477db'}>, 
])
Suggest Edits

Remove Tags from a Customer

Removes tags from a given customer.

 
deletehttps://api.chartmogul.com/v1/customers/CUSTOMER_UUID/attributes/tags

Path Params

customer_uuid
string
required

The ChartMogul UUID of the customer.

Form Data

tags
array of strings
required

An Array of tags to be removed from the customer.

 

In the response, tags contains an Array with all the tags now on this customer.

Examples

curl -X DELETE "https://api.chartmogul.com/v1/customers/cus_de305d54-75b4-431b-adb2-eb6b9e546012/attributes/tags" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_KEY \
     -H "Content-Type: application/json" \
     -d '{
          "tags": ["Prio1", "discountable"]
         }'
customer = ChartMogul::Customer.retrieve('cus_de305d54-75b4-431b-adb2-eb6b9e546012')
customer.remove_tags!('Prio1', 'discountable')
ChartMogul.Tag.remove(config, "cus_de305d54-75b4-431b-adb2-eb6b9e546012", {
   "tags": ["important1", "Prio2"]
   }, function (err, res) {
   // asynchronously called
});
<?php

$customer = ChartMogul\Customer::retrieve(
                "cus_de305d54-75b4-431b-adb2-eb6b9e546012");
$customer->removeTags("important1", "Prio2");
?>
api.RemoveTagsFromCustomer(
		"cus_d3b1672e-edff-11e6-950b-d3d5a143d29a",
		[]string{"important1", "Prio2"})
chartmogul.Tags.remove(
    config,
    uuid="cus_d3b1672e-edff-11e6-950b-d3d5a143d29a",
    data={
      "tags": ["important1", "Prio2"]})

Result Format

{
  "tags": ["engage", "unit loss", "important"]
}
['engage', 'unit loss', 'important']
{
  "tags": ["engage", "unit loss", "important"]
}
<?php

array (
  0 => 'engage',
  1 => 'unit loss',
  2 => 'important'
)
?>
(*chartmogul.TagsResult)(0xc0420c8bc0)({
 Tags: ([]string) (len=1) {
  (string) (len=10) "important2"
 }
})
<Tags{tags=[
    'important2'
  ]}>
Suggest Edits

Custom Attributes

Custom Attributes are a type of customer attribute. They are key-value metadata that can be used to describe properties of customers.

 

Custom Attributes are useful for storing structured information on a customer object. There is no limit to the number of custom attributes you can add to a customer object in ChartMogul.

Suggest Edits

Add Custom Attributes to a Customer

Adds custom attributes to a given customer.

 
posthttps://api.chartmogul.com/v1/customers/CUSTOMER_UUID/attributes/custom

Path Params

customer_uuid
string
required

The ChartMogul UUID of the customer.

Form Data

custom
array
required

An Array containing the custom attributes to be added to the customer. Each custom attribute must have a type, key, and value as described below.

type
string
required

The data type of the custom attribute. Can be one of String, Integer, Decimal, Timestamp or Boolean.

key
string
required

The name of the custom attribute. Accepts alphanumeric characters and underscores.

value
mixed type
required

The value of the custom attribute. Should be of the data type as specified in type.

source
string

Optional parameter for UI use. Can be updated, doesn't show in response.

 

Supported data types and their accepted formats

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.

In the response, custom contains all the custom attributes now on this customer.

Examples

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}
          ]
         }'
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}
)
ChartMogul.CustomAttribute.add(config, "cus_de305d54-75b4-431b-adb2-eb6b9e546012", {
   'custom': [
     {"type": "String", "key": "channel", "value": "Facebook"},
     {'type': 'Integer', 'key': 'age', 'value': 8}
   ]
}, 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]
);
?>
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},
		})
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}
        ]
    }
)

Result Format

{
  "custom": {
    "CAC": 213,
    "utmCampaign": "social media 1",
    "convertedAt": "2015-09-08 00:00:00",
    "pro": false,"salesRep": "Gabi",
    "channel": "Facebook",
    "age": 8
  }
}
{
  :CAC=> 213,
  :utmCampaign=> "social media 1",
  :convertedAt=> "2015-09-08 00:00:00",
  :pro=> false,
  :salesRep=> "Gabi",
  :channel=> "Facebook",
  :age=> 8
}
{
  "custom": {
    "CAC": 213,
    "utmCampaign": "social media 1",
    "convertedAt": "2015-09-08 00:00:00",
    "pro": false,"salesRep": "Gabi",
    "channel": "Facebook",
    "age": 8
  }
}
<?php

array (
  "CAC" => 213,
  "utmCampaign" => "social media 1",
  "convertedAt" => "2015-09-08 00:00:00",
  "pro" => false,"salesRep" => "Gabi",
  "channel" => "Facebook",
  "age" => 8
)
?>
(*chartmogul.CustomAttributes)(0xc04206c030)({
 Custom: (map[string]interface {}) (len=2) {
  (string) (len=3) "CAC": (float64) 8,
  (string) (len=7) "channel": (string) (len=8) "Facebook"
 }
})
<CustomAttributes{
    custom={
        'CAC': 8, 
        'channel': 'Facebook'}}>
Suggest Edits

Add Custom Attributes to Customers with email

Adds custom attributes to customers that have the specified email address.

 
posthttps://api.chartmogul.com/v1/customers/attributes/custom

Form Data

email
string
required

The email address of the customers to whom custom attributes must be added.

custom
array
required

An Array containing the custom attributes to be added to the customers. Each custom attribute must have a type, key, and value as described below.

type
string
required

The data type of the custom attribute. Can be one of String, Integer, Decimal, Timestamp or Boolean.

key
string
required

The name of the custom attribute. Accepts alphanumeric characters and underscores.

value
mixed type
required

The value of the custom attribute. Should be of the data type as specified in type.

source
string

Optional parameter for UI use. Can be updated, doesn't show in response.

 

Supported data types and their accepted formats

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.

In the response, entries contains an array of JSON objects with the following data:

  • id - The internal ChartMogul ID of the customer object with specified email.
  • uuid - The UUID of the customer object generated by ChartMogul.
  • external_id - The unique external identifier for this customer, if any.
  • name - The name of this customer.
  • email - This customer's email address.
  • status - The status of this customer. One of Active or Cancelled, depending on whether the customer has any active subscriptions or not.
  • customer-since - An RFC3339 formatted datetime attribute indicating when the customer first started paying for a subscription.
  • attributes - A JSON object representing this customer's attributes containing the following data:
  • t