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.

Lists all data_source objects that you have created using the Import API.

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

Creates a customer object in ChartMogul under the specified data_source.

Returns a list of customer objects created using the Import API.

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

Creates a plan object in ChartMogul under the specified data_source.

Returns a list of plan objects created using the Import API.

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

Returns a list of invoice objects for a given customer.

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/import/data_sources

Body Params

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.
  • created_at - The time when this data source was created in the ChartMogul system.
  • status - The current status of the data import into ChartMogul. 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.

Examples

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

ChartMogul\Import\DataSource::create([
    "name" => "In-house billing"
]);
?>

Result Format

{
    "uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
    "name": "In-house billing",
    "created_at": "2016-01-10 15:34:05",
    "status": "never_imported"
}
#<ChartMogul::Import::DataSource:0x007ff9f127d628 
@name="In-house billing", 
@uuid="ds_fef05d54-47b4-431b-aed2-eb6b9e545430", 
@status="never_imported", 
@created_at=2016-06-27 11:27:37 UTC
>
{
    "uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
    "name": "In-house billing",
    "created_at": "2016-01-10 15:34:05",
    "status": "never_imported"
}
ChartMogul\Import\DataSource::__set_state(array(
   "uuid" => "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
   "status" => "never_imported",
   "created_at" => "2016-12-27T07:55:08.585Z",
   "name" => "In-house billing"
));
Suggest Edits

List Data Sources

Lists all data_source objects that you have created using the Import API.

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

No request parameters are required for this endpoint.

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.
  • created_at - The time when this data source was created in the ChartMogul system.
  • status - The current status of the data import into ChartMogul. 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.

Examples

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

ChartMogul\Import\DataSource::all();
?>

Result Format

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

Doctrine\Common\Collections\ArrayCollection::__set_state(array(
   "elements" => 
  array (
    0 => 
    ChartMogul\Import\DataSource::__set_state(array(
       "uuid" => "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
       "status" => "never_imported",
       "created_at" => "2016-01-10 15:34:05",
       "name" => "In-house billing",
    )),
    1 => 
    ChartMogul\Import\DataSource::__set_state(array(
       "uuid" => "ds_ade45e52-47a4-231a-1ed2-eb6b9e541213",
       "status" => "import_complete",
       "created_at" => "2016-01-09 10:14:15",
       "name" => "Enterprise billing connection",
    ))
)));
?>
Suggest Edits

Delete a Data Source

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

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

Path Params

data_source_uuid
string
required

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

 

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/import/data_sources/ds_ade45e52-47a4-231a-1ed2-eb6b9e541213" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_KEY
data_sources = ChartMogul::Import::DataSource.all
ds = data_sources.last
ds.destroy!
ChartMogul.Import.DataSource.destroy(config, "ds_ade45e52-47a4-231a-1ed2-eb6b9e541213", function (err, res) {
   // aysnchronously called
});
<?php

ChartMogul\Import\DataSource::all()->last()->destroy();
?>

Result Format

{ }
true
{ }
true
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

Import a Customer

Creates a customer object in ChartMogul under the specified data_source.

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

Body Params

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.

 

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

  • uuid - The UUID of the customer object generated by ChartMogul.
  • data_source_uuid - The UUID of the data source that this customer belongs to.
  • external_id - The unique external identifier for this customer, as specified by you.
  • 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.

Examples

curl -X POST "https://api.chartmogul.com/v1/import/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",
          "city": "New York",
          "lead_created_at": "2015-10-14",
          "free_trial_started_at": "2015-11-01"
         }'
ChartMogul::Import::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)
)
ChartMogul.Import.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"
    }, function (err, res){
    // asynchronously called
});
<?php

ChartMogul\Import\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"
]);
?>

Result Format

{
   "uuid": "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
   "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
   "external_id": "cus_0001",
   "name": "Adam Smith",
   "company": "",
   "email": "[email protected]",
   "city": "New York",
   "state": "",
   "country": "US",
   "zip": "",
   "lead_created_at": "2015-10-14T00:00:00.000Z",
   "free_trial_started_at": "2015-11-01T00:00:00.000Z"
}
#<ChartMogul::Import::Customer:0x007fb499182310 
@uuid="cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
@data_source_uuid="ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
@external_id="cus_0001",
@name="Adam Smith",
@email="[email protected]",
@company="",
@city="New York",
@state="",
@country="US",
@zip="",
@lead_created_at=2015-10-14 00:00:00 UTC,
@free_trial_started_at=2015-11-01 00:00:00 UTC
>
{
   "uuid": "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
   "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
   "external_id": "cus_0001",
   "name": "Adam Smith",
   "company": "",
   "email": "[email protected]",
   "city": "New York",
   "state": "",
   "country": "US",
   "zip": "",
   "lead_created_at": "2015-10-14T00:00:00.000Z",
   "free_trial_started_at": "2015-11-01T00:00:00.000Z"
}
<?php

ChartMogul\Import\Customer::__set_state(array(
   "uuid" => "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
   "external_id" => "cus_0001",
   "name" => "Adam Smith",
   "email" => "[email protected]",
   "company" => "",
   "country" => "US",
   "state" => "",
   "city" => "New York",
   "zip" => "",
   "data_source_uuid" => "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
   "lead_created_at" => "2015-10-14T00:00:00.000Z",
   "free_trial_started_at" => "2015-11-01T00:00:00.000Z"
));
?>
Suggest Edits

List Customers

Returns a list of customer objects created using the Import API.

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

Query Params

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.

data_source_uuid
string

An optional filter parameter, for the ChartMogul UUID of the data source of this customer.

external_id
string

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

 

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

  • uuid - The UUID of the customer object generated by ChartMogul.
  • data_source_uuid - The UUID of the data source that this customer belongs to.
  • external_id - The unique external identifier for this customer, as specified by you.
  • 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.

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?per_page=2" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_KEY
ChartMogul::Import::Customer.all(page: 1, per_page: 2)
ChartMogul.Import.Customer.all(config, {
   per_page: 2
   }, function (err, res) {
   // asynchronously called
});
<?php

ChartMogul\Import\Customer::all(["per_page" => 2]);
?>

Result Format

{
  "customers":[
    {
      "uuid": "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
      "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
      "external_id": "cus_0001",
      "name": "Adam Smith",
      "email": "[email protected]",
      "company": "",
      "country": "US",
      "state": "",
      "city": "New York",
      "zip": ""
    },
    {
      "uuid": "cus_ee325d54-7ab4-421b-cdb2-eb6b9e546034",
      "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
      "external_id": "cus_0002",
      "name": "Alice",
      "email": "[email protected]",
      "company": "Acme inc.",
      "country": "",
      "state": "",
      "city": "",
      "zip": ""
    }
  ],
  "current_page": 1,
  "total_pages": 5
}
[
  #<ChartMogul::Import::Customer:0x007fb499182310
  @uuid="cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
  @data_source_uuid="ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  @external_id="cus_0001",
  @name="Adam Smith",
  @email="[email protected]",
  @company="",
  @city="New York",
  @state="",
  @country="US",
  @zip=""
  >,
  #<ChartMogul::Import::Customer:0x007fb4993589f0
  @uuid="cus_ee325d54-7ab4-421b-cdb2-eb6b9e546034",
  @data_source_uuid="ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  @external_id="cus_0002",
  @name="Alice",
  @email="[email protected]",
  @company="Acme inc.",
  @city="",
  @state="",
  @country="",
  @zip=""
  >
]
{
  "customers":[
    {
      "uuid": "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
      "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
      "external_id": "cus_0001",
      "name": "Adam Smith",
      "email": "[email protected]",
      "company": "",
      "country": "US",
      "state": "",
      "city": "New York",
      "zip": ""
    },
    {
      "uuid": "cus_ee325d54-7ab4-421b-cdb2-eb6b9e546034",
      "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
      "external_id": "cus_0002",
      "name": "Alice",
      "email": "[email protected]",
      "company": "Acme inc.",
      "country": "",
      "state": "",
      "city": "",
      "zip": ""
    }
  ],
  "current_page": 1,
  "total_pages": 5
}
<?php

Doctrine\Common\Collections\ArrayCollection::__set_state(array(
   "elements" => 
  array (
    0 => 
    ChartMogul\Import\Customer::__set_state(array(
       "uuid" => "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
       "external_id" => "cus_0001",
       "name" => "Adam Smith",
       "email" => "[email protected]",
       "company" => "",
       "country" => "US",
       "state" => "",
       "city" => "New York",
       "zip" => "",
       "data_source_uuid" => "ds_fef05d54-47b4-431b-aed2-eb6b9e545430"
    )),
    1 => 
    ChartMogul\Import\Customer::__set_state(array(
       "uuid" => "cus_ee325d54-7ab4-421b-cdb2-eb6b9e546034",
       "external_id" => "cus_0002",
       "name" => "Alice",
       "email" => "[email protected]",
       "company" => "Acme inc.",
       "country" => "",
       "state" => "",
       "city" => "",
       "zip" => "",
       "data_source_uuid" => "ds_fef05d54-47b4-431b-aed2-eb6b9e545430"
    ))
  ),
  "current_page" => 1,
  "total_pages" => 5
));
?>
Suggest Edits

Delete a Customer

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

 
deletehttps://api.chartmogul.com/v1/import/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/import/customers/cus_ee325d54-7ab4-421b-cdb2-eb6b9e546034" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_KEY
customers = ChartMogul::Import::Customer.all
customer = customers.last
customer.destroy!
ChartMogul.Import.Customer.destroy(config, 
 "cus_ee325d54-7ab4-421b-cdb2-eb6b9e546034",
 function (err, res) {
 // asynchronously called
});
<?php

ChartMogul\Import\Customer::all()->last()->destroy();
?>

Result Format

{ }
true
{ }
true
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

Import a Plan

Creates a plan object in ChartMogul under the specified data_source.

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

Body Params

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/import/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::Import::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.Import.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\Import\Plan::create([
    "data_source_uuid" => "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
    "name" => "Bronze Plan",
    "interval_count" => 1,
    "interval_unit" => "month",
    "external_id" => "plan_0001"
]);
?>

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::Import::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\Import\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"
));
?>
Suggest Edits

List Plans

Returns a list of plan objects created using the Import API.

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

Query Params

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.

data_source_uuid
string

An optional filter parameter, for the ChartMogul UUID of the data source of this plan.

external_id
string

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

 

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/import/plans?per_page=3" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_KEY
ChartMogul::Import::Plan.all(page: 1, per_page: 3)
ChartMogul.Import.Plan.all(config, {
  per_page: 3
  }, function (err, res) {
 // asynchronously called
});
<?php

ChartMogul\Import\Plan::all(["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::Import::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::Import::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::Import::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"
  >
]
{
  "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\Import\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\Import\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\Import\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
));
?>
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 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.

Body Params

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 in the past. 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.
Irrelevant 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 in the past. 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 paid 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 specified otherwise.

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. 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 in the past. 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.

Transactions vs Invoices

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.

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

Send us batches of Invoices

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.

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::Import::Customer.all(external_id:"cus_0001").first
plan = ChartMogul::Import::Plan.all(external_id:"plan_0001").first

line_item_1 = ChartMogul::Import::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::Import::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::Import::Transactions::Payment.new(
  date: Time.utc(2015, 11, 5, 0, 14, 23),
  result: 'successful'
)
invoice = ChartMogul::Import::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::Import::CustomerInvoices.create!(customer_uuid: customer.uuid, invoices: [invoice])
ChartMogul.Import.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\Import\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\Import\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\Import\Transactions\Payment([
    "date" => "2015-11-05 00:14:23",
    "result" => "successful"
]);
$invoice = new ChartMogul\Import\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\Import\CustomerInvoices::create([
            "customer_uuid" => $cu->uuid,
            "invoices" => [$invoice]
]);
?>

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",
          "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::Import::CustomerInvoices:0x007fb49884b850 
@customer_uuid="cus_f466e33d-ff2b-4a11-8f85-417eb02157a7"
@invoices=[
  #<ChartMogul::Import::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::Import::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::Import::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::Import::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",
          "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\Import\CustomerInvoices::__set_state(array(
   "invoices" => 
  Doctrine\Common\Collections\ArrayCollection::__set_state(array(
     "elements" => 
    array (
      0 => 
      ChartMogul\Import\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\Import\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",
               "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\Import\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\Import\Transactions\Payment::__set_state(array(
               "type" => "payment",
               "uuid" => "tr_879d560a-1bec-41bb-986e-665e38a2f7bc",
               "date" => "2015-11-05T00:14:23.000Z",
               "result" => "successful"
           )))
        ))
)))))));
?>
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.
    • 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::Import::CustomerInvoices.all('cus_7388fd53-1ecf-481e-97e6-28adb653f6c0', page: 1, per_page: 200)
ChartMogul.Import.Invoice.all(config, "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7", function (err, res) {
   // asynchronously called
});
<?php

ChartMogul\Import\CustomerInvoices::all([
    "customer_uuid" => "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7"
]);
?>

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",
          "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::Import::CustomerInvoices:0x007fb49884b850 
@customer_uuid="cus_7388fd53-1ecf-481e-97e6-28adb653f6c0"
@invoices=[
  #<ChartMogul::Import::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::Import::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::Import::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::Import::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"
    >
  ]
  >
]
>
{
  "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",
          "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\Import\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\Import\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\Import\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",
               "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\Import\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\Import\Transactions\Payment::__set_state(array(
               "type" => "payment",
               "uuid" => "tr_879d560a-1bec-41bb-986e-665e38a2f7bc",
               "date" => "2015-11-05T00:14:23.000Z",
               "result" => "successful"
           )))
        ))
)))))));
?>
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.

Body Params

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 in the past. 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::Import::Customer.all(external_id:"cus_0001").first
invoice = customer.invoices.last
transaction = ChartMogul::Import::Transactions::Refund.create!(
  invoice_uuid: invoice.uuid,
  date: Time.utc(2015, 12, 25, 18, 10),
  result: 'successful'
)
ChartMogul.Import.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\Import\Transactions\Refund::create([
    "invoice_uuid" => "inv_565c73b2-85b9-49c9-a25e-2b7df6a677c9",
    "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::Import::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\Import\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
));
?>
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::Import::Subscription.all('cus_f466e33d-ff2b-4a11-8f85-417eb02157a7', page: 1, per_page: 200)
ChartMogul.Import.Subscription.all(config, "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7", function(err, res) {
   // asynchronously called
});
<?php

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

$subscriptions = $cus->subscriptions();
?>

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::Import::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=[]
  >
]
{
  "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\Import\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",
));
?>
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.

Body Params

cancelled_at
date-time

The time at which the subscription was cancelled. Must be an ISO 8601 formatted time in the past. 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"
        }'
customer = ChartMogul::Import::Customer.all(external_id:"cus_0001").first
subscription = customer.subscriptions.last
subscription.cancel(Time.utc(2016, 1, 15))
ChartMogul.Import.Subscription.cancel(config,
   "sub_e6bc5407-e258-4de0-bb43-61faaf062035", 
   { "cancelled_at": "2016-01-15 00:00:00" },
   function(err, res) {
   // asynchronously called
});
<?php

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

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"
}
#<ChartMogul::Import::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"
>
{
  "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"
}
<?php

ChartMogul\Import\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",
));
?>
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

Retrieves a customer object from your ChartMogul account.

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

Returns a list of all customer objects 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.

 
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 Active or Cancelled, depending on whether the customer has any active subscriptions or not.
  • 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. One of Stripe, Braintree, Recurly, Chargify, PayPal, Manual (i.e. CSV upload) 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::Enrichment::Customer.retrieve('cus_de305d54-75b4-431b-adb2-eb6b9e546012')
ChartMogul.Enrichment.Customer.retrieve(config, "cus_de305d54-75b4-431b-adb2-eb6b9e546012", function(err, res) {
   // asynchronously called
});
<?php

ChartMogul\Enrichment\Customer::retrieve("cus_de305d54-75b4-431b-adb2-eb6b9e546012");
?>

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::Enrichment::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="$"
>
{
  "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_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": "$"
}
<?php

ChartMogul\Enrichment\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" => "",
));
?>
Suggest Edits

Update a Customer

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

Body Params

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

A Hash containing the custom attributes to be updated. Each custom attribute must have a key and value.

 

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 -
  • 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.
  • chartmogul-url - The URL for this customer's ChartMogul page. This is only accessible to a user logged in to your ChartMogul account.

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": "Juneau",
            "country": "US",
            "state": "Alaska",
            "attributes": {
              "tags": ["high-value"],
              "custom": {
                "CAC": 25
              }
             }
           }'
customer = 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 = "Juneau",
customer.country = "US",
customer.state = "Alaska",
customer.attributes.tags = ["high-value"],
customer.attributes.custom = {"CAC": 25}

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": "Juneau",
    "country": "US",
    "state": "Alaska",
    "attributes": {
        "tags": ["high-value"],
        "custom": {
            "CAC": 25
        }
    }
};

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

ChartMogul\Enrichment\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" => "Juneau",
    "country" => "US",
    "state" => "Alaska",
    "attributes" => [
        "tags" => ["high-value"],
        "custom" => [
            "CAC" => 25
        ]
    ]
]);
?>

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": "Juneau",
    "country": "US",
    "state": "Alaska",
    "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": "Juneau",
      "country": "US",
      "state": "Alaska"
     },
    "attributes": {
      "custom": {
        "CAC": 25,
        "SalesRep": "Mike",
      },
      "clearbit": {},
      "stripe": {},
      "tags": ["high-value"]
    },
    "mrr": 3000,
    "arr": 36000,
    "chartmogul-url": "https:\/\/app.chartmogul.com\/#customers\/25647-Example_Company"
}
Suggest Edits

List all 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.

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. One of Stripe, Braintree, Recurly, Chargify, PayPal, or Import API. Returns all customers that have billing data from the specified system.

external_id
string

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

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.
  • status - The status of this customer. One of Active or Cancelled, depending on whether the customer has any active subscriptions or not.
  • 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. One of Stripe, Braintree, Recurly, Chargify, PayPal, Manual (i.e. CSV upload) 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.

Examples

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

ChartMogul\Enrichment\Customer::all([
    'per_page' => 50
]);
?>

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::Enrichment::Customers:0x007fe7e09ca7c8 
@entries=[
  #<ChartMogul::Enrichment::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\Enrichment\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\Enrichment\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" => "..."
  )))
));
?>
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.

 

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 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 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. One of Stripe, Braintree, Recurly, Chargify, PayPal, Manual (i.e. CSV upload) 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::Enrichment::Customer.search([email protected]')
ChartMogul.Enrichment.Customer.search(config, {
   email: [email protected]' },
   function (err, res) {
   // asynchronously called
});
<?php

ChartMogul\Enrichment\Customer::search("[email protected]");
?>

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::Enrichment::Customers:0x007fd843685d58 
@entries=[
  #<ChartMogul::Enrichment::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="$"
  >
]
>
{
  "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\Enrichment\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\Enrichment\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" => "",
    ))
  )))
));
?>
Suggest Edits

Merge Customers

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

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

Body Params

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::Enrichment::Customer.retrieve('cus_de305d54-75b4-431b-adb2-eb6b9e546012')
into_customer = ChartMogul::Enrichment::Customer.retrieve('cus_ab223d54-75b4-431b-adb2-eb6b9e234571')

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

ChartMogul\Enrichment\Customer::merge([
    "customer_uuid" => "cus_5915ee5a-babd-406b-b8ce-d207133fb4cb"
        ], [
    "customer_uuid" => "cus_2123290f-09c8-4628-a205-db5596bd58f7"
]);
?>

Result Format

{ }
true
{ }
true
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.

 

In the response, attributes 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::Enrichment::Customer.retrieve('cus_de305d54-75b4-431b-adb2-eb6b9e546012')
customer.attributes
ChartMogul.Enrichment.Customer.attributes(config, "cus_de305d54-75b4-431b-adb2-eb6b9e546012", function (err, res) {
   // asynchronously called
});
<?php

$customer = ChartMogul\Enrichment\Customer::retrieve(
  						"cus_de305d54-75b4-431b-adb2-eb6b9e546012");
$customer->attributes;
?>

Result Format

{
  "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"
    }
  }
}
{
  :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"
  }
}
{
  "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"
    }
  }
}
<?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',
  ),
)
?>
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.

Body Params

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::Enrichment::Customer.retrieve('cus_de305d54-75b4-431b-adb2-eb6b9e546012')
customer.add_tags!('important', 'Prio1')
ChartMogul.Enrichment.Tag.add(config, "cus_de305d54-75b4-431b-adb2-eb6b9e546012", {
   "tags": ["important", "Prio1"]
   }, function (err, res) {
   // asynchronously called
});
<?php

$customer = ChartMogul\Enrichment\Customer::retrieve(
    				"cus_de305d54-75b4-431b-adb2-eb6b9e546012");
$customer->addTags("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"
)
?>
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

Body Params

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::Enrichment::Customer.search([email protected]')
customers.each {|c| c.add_tags!('important', 'Prio1') }
ChartMogul.Enrichment.Tag.add(config, {
   "email": [email protected]',
   "tags": ["important21", "Prio22"]
   }, function (err, res) {
   // asynchronously called
});
<?php

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

foreach ($customers->entries as $customer) {
    $customer->addTags(["important21", "Prio22"]);
}
?>

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::Enrichment::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::Enrichment::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"
)
?>
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.

Body Params

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::Enrichment::Customer.retrieve('cus_de305d54-75b4-431b-adb2-eb6b9e546012')
customer.remove_tags!('Prio1', 'discountable')
ChartMogul.Enrichment.Tag.remove(config, "cus_de305d54-75b4-431b-adb2-eb6b9e546012", {
   "tags": ["important1", "Prio2"]
   }, function (err, res) {
   // asynchronously called
});
<?php

$customer = ChartMogul\Enrichment\Customer::retrieve(
                "cus_de305d54-75b4-431b-adb2-eb6b9e546012");
$customer->removeTags("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'
)
?>
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.

Body Params

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, 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.

 

Supported data types and their accepted formats

String - Accepts alphanumeric characters. Maximum of 255 characters allowed.
Integer - Accepts only numeric characters.
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::Enrichment::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.Enrichment.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\Enrichment\Customer::retrieve(
                "cus_de305d54-75b4-431b-adb2-eb6b9e546012");
$custom = $customer->addCustomAttributes(
        ['type' => 'String', "key" => "channel", "value" => "Facebook"],
        ['type' => 'Integer', "key" => "age", "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
)
?>
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

Body Params

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, 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.

 

Supported data types and their accepted formats

String - Accepts alphanumeric characters. Maximum of 255 characters allowed.
Integer - Accepts only numeric characters.
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:
  • 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/custom" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_KEY \
     -H "Content-Type: application/json" \
     -d '{
          "email": "[email protected]",
          "custom": [
            {"type": "String", "key": "channel", "value": "Facebook"},
            {"type": "Integer", "key": "age", "value": 8}
          ]
         }'
customers = ChartMogul::Enrichment::Customer.search([email protected]')
customers.each |c| 
  c.add_custom_attributes!(
    {type: "String", key: "channel", value: "Facebook"},
    {type: "Integer", key: "age", value: 8}
  )
end
ChartMogul.Enrichment.CustomAttribute.add(config, {
   'email': [email protected]',
   'custom': [
     {"type": "String", "key": "channel", "value": "Facebook"},
     {'type': 'Integer', 'key': 'age', 'value': 8}
   ]
}, function (err, res) {
   // asynchronously called
});
<?php

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

foreach ($customers->entries as $customer) {
    $customer->addCustomAttributes(
        ["type" => "String", "key" => "channel", "value" => "Facebook"],
        ["type" => "Integer", "key" => "age", "value" => 8 ]
    );
}
?>

Result Format

{
  "entries": [
    {
      "id": 25647,
      "uuid": "cus_de305d54-75b4-431b-adb2-eb6b9e546012",
      "external_id": "40574176",
      "email": "[email protected]",
      "name": "Smith Company",
      "customer-since": "2015-06-09T13:16:00-04:00",
      "status": "Active",
      "attributes": {
        "tags": ["important", "Prio1"],
        "stripe": {
          "coupon": true
        },
        "clearbit": {
          "name": "Acme"
        },
        "custom": {
          "channel": "Facebook",
          "age": 8
        }
      }
    },
    {
      "id": 13456,
      "uuid": "cus_fb305d54-75b4-431b-2334-eb6b9e540016",
      "external_id": "58473129",
      "email": "[email protected]",
      "name": "Adam",
      "customer-since": "2015-06-10T13:16:00-04:00",
      "status": "Active",
      "attributes": {
        "tags": ["important", "Prio1"],
        "stripe": {
          "coupon": false
        },
        "clearbit": {
          "name": "Umbrella Corp."
        },
        "custom": {
          "channel": "Facebook",
          "age": 8
        }
      }
    }
  ]
}
[
  #<ChartMogul::Enrichment::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=>{
      :channel=> "Facebook",
      :age=> 8
    }
  }, 
  @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::Enrichment::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=>{
      :channel=> "Facebook",
      :age=> 8
    }
  }, 
  @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",
      "email": "[email protected]",
      "name": "Smith Company",
      "customer-since": "2015-06-09T13:16:00-04:00",
      "status": "Active",
      "attributes": {
        "tags": ["important", "Prio1"],
        "stripe": {
          "coupon": true
        },
        "clearbit": {
          "name": "Acme"
        },
        "custom": {
          "channel": "Facebook",
          "age": 8
        }
      }
    },
    {
      "id": 13456,
      "uuid": "cus_fb305d54-75b4-431b-2334-eb6b9e540016",
      "external_id": "58473129",
      "email": "[email protected]",
      "name": "Adam",
      "customer-since": "2015-06-10T13:16:00-04:00",
      "status": "Active",
      "attributes": {
        "tags": ["important", "Prio1"],
        "stripe": {
          "coupon": false
        },
        "clearbit": {
          "name": "Umbrella Corp."
        },
        "custom": {
          "channel": "Facebook",
          "age": 8
        }
      }
    }
  ]
}
<?php

array (
  "channel" => "Facebook",
  "age" => 8
)
array (
  "channel" => "Facebook",
  "age" => 8
)
?>
Suggest Edits

Update Custom Attributes of a Customer

Updates the custom attributes of a given customer.

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

Path Params

customer_uuid
string
required

The ChartMogul UUID of the customer.

Body Params

custom
object
required

A Hash containing the custom attributes to be updated. Each custom attribute must have a key and value as described below.

key
string
required

The name of the custom attribute that is to be updated. Accepts alphanumeric characters and underscores.

value
mixed type
required

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

 

Supported data types and their accepted formats

String - Accepts alphanumeric characters. Maximum of 255 characters allowed.
Integer - Accepts only numeric characters .
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 PUT "https://api.chartmogul.com/v1/customers/cus_de305d54-75b4-431b-adb2-eb6b9e546012/attributes/custom" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_KEY \
     -H "Content-Type: application/json" \
     -d '{
          "custom":{
            "pro": true,
            "channel": "Twitter"
          }
         }'
customer = ChartMogul::Enrichment::Customer.retrieve('cus_de305d54-75b4-431b-adb2-eb6b9e546012')
customer.update_custom_attributes!(
  pro: true, 
  channel: "Twitter"
)
ChartMogul.Enrichment.CustomAttribute.update(config, "cus_de305d54-75b4-431b-adb2-eb6b9e546012", {
   "custom": {
    "pro": true,
    "channel": "Twitter"
   }
}, function (err, res) {
   // asynchronously called
});
<?php

$customer = ChartMogul\Enrichment\Customer::retrieve(
                "cus_de305d54-75b4-431b-adb2-eb6b9e546012");
$customer->updateCustomAttributes(
        ["channel" => "Twitter"],
        ["pro" => true]
);
?>

Result Format

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

array (
  "CAC" => 213,
  "utmCampaign" => "social media 1",
  "convertedAt" => "2015-09-08 00:00:00",
  "pro" => true,
  "channel" => "Twitter"
)
?>
Suggest Edits

Remove Custom Attributes from a Customer

Removes custom attributes from a given customer.

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

Path Params

customer_uuid
string
required

The ChartMogul UUID of the customer.

Body Params

custom
array of strings
required

An Array containing the keys of all the custom attributes to be removed from the customer.

 

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

Examples

curl -X DELETE "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": ["age", "salesRep"]
         }'
customer = ChartMogul::Enrichment::Customer.retrieve('cus_de305d54-75b4-431b-adb2-eb6b9e546012')
customer.remove_custom_attributes!(:age, :salesRep)
ChartMogul.Enrichment.CustomAttribute.remove(config, "cus_de305d54-75b4-431b-adb2-eb6b9e546012", {
   "custom": ["age", "salesRep"]
}, function (err, res) {
   // asynchronously called
});
<?php

$customer = ChartMogul\Enrichment\Customer::retrieve(
                "cus_de305d54-75b4-431b-adb2-eb6b9e546012");
$customer->removeCustomAttributes("age", "salesRep");
?>

Result Format

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

array (
  "CAC" => 213,
  "utmCampaign" => "social media 1",
  "convertedAt" => "2015-09-08 00:00:00",
  "pro" => false,
  "channel" => "Facebook"
)
?>
Suggest Edits

Introduction to the Metrics API

The Metrics API allows users to programmatically pull the subscription metrics that ChartMogul generates.

 
Suggest Edits

Endpoint Overview

 
Endpoint
Description

Retrieves all key metrics, for the specified time period.

Retrieves the Monthly Recurring Revenue (MRR), for the specified time period.

Retrieves the Annualized Run Rate (ARR), for the specified time period.

Retrieves the Average Revenue Per Account (ARPA), for the specified time period.

Retrieves the Average Sale Price (ASP), for the specified time period.

Retrieves the number of active customers, for the specified time period.

Retrieves the Customer Churn Rate, for the specified time period.

Retrieves the Net MRR Churn Rate, for the specified time period.

Retrieves the Customer Lifetime Value (LTV), for the specified time period.

Returns a list of subscriptions for a given customer.

Returns a list of activities for a given customer.

Suggest Edits

Retrieve all key metrics

Retrieves all key metrics, for the specified time period.

 
gethttps://api.chartmogul.com/v1/metrics/all

Query Params

start-date
date
required

The start date of the required period of data. An ISO-8601 formatted date, e.g. 2015-05-12

end-date
date
required

The end date of the required period of data. An ISO-8601 formatted date, e.g. 2015-05-12

interval
string

One of day, week, month (default), or quarter

geo
string

A comma-separated list of ISO 3166-1 Alpha-2 formatted country codes to filter the results to, e.g. US,GB,DE.

plans
string

A comma-separated list of plan names (as configured in your ChartMogul account) to filter the results to. Note that spaces must be url-encoded and the names are case-sensitive, e.g. Silver%20plan,Gold%20plan,Enterprise%20plan.

 

In the response, entries contains an object for each interval, with the following data:

  • date - the end date of each interval period.
  • customer-churn-rate - The customer churn rate at the end of that month, expressed as a percentage.
  • mrr-churn-rate - The Net MRR churn rate at the end of that month, expressed as a percentage.
  • ltv - The Customer LTV as at the end of the month. This is in your account's selected currency, and is a number of cents. Divide it by 100 to obtain the actual value.
  • customers - The number of active customers in your account as at the end of the interval.
  • asp - The ASP as at the end of the period. This is in your account's selected currency, and is an integer number of cents. Divide it by 100 to obtain the actual value.
  • arpa - The ARPA as at the end of the period. This is in your account's selected currency, and is an integer number of cents. Divide it by 100 to obtain the actual value.
  • arr - the Annual Recurring Revenue as at the end of each interval period. This is in your account's selected currency, and is an integer number of cents. Divide it by 100 to obtain the actual value.
  • mrr - The Monthly Recurring Revenue as at the end of the interval.

Examples

curl -X GET "https://api.chartmogul.com/v1/metrics/all" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_KEY
     -d start-date=2015-01-01 \
     -d end-date=2015-11-24 \
     -d interval=month \
     -d geo=GB \
     -d plans=PRO%20Plan
ChartMogul::Metrics.all(start_date: '2015-01-01', end_date: '2015-11-24', interval: 'month', geo: 'GB', plans: 'PRO Plan')
ChartMogul.Metrics.all(config, {
   'start-date': '2015-01-01',
   'end-date': '2015-11-24',
   'interval': 'month',
   'geo': 'GB',
   'plans': 'PRO Plan'
}, function (err, res) {
   // asynchronously called
});
<?php

ChartMogul\Metrics::all([
    "start-date" => "2015-01-01",
    "end-date" => "2015-11-24",
    "interval" => "month",
    "geo" => "GB",
    "plans" => "PRO Plan"
]);
?>

Result Format

{
  "entries":[
    {
      "date":"2015-01-31",
      "customer-churn-rate":20,
      "mrr-churn-rate":14,
      "ltv":1250.3,
      "customers":331,
      "asp":125,
      "arpa":1250,
      "arr":254000,
      "mrr":21166
    },
    {
      "date":"2015-02-28",
      "customer-churn-rate":20,
      "mrr-churn-rate":22,
      "ltv":1248,
      "customers":329,
      "asp":125,
      "arpa":1250,
      "arr":238000,
      "mrr":21089
    },
    {"...more...": "...entries..."}
  ]
}
#<ChartMogul::Metrics::AllKeyMetrics:0x007fa4ec493200 
@entries=[
  #<ChartMogul::Metrics::AllKeyMetric:0x007fa4ec492fa8 
  @date=2015-01-31,
  @customer_churn_rate=20,
  @mrr_churn_rate=14,
  @ltv=1250.3,
  @customers=331,
  @asp=125,
  @arpa=1250,
  @arr=254000,
  @mrr=21166
  >, 
  #<ChartMogul::Metrics::AllKeyMetric:0x007fa4ec492328 
  @date=2015-02-28,
  @customer_churn_rate=20,
  @mrr_churn_rate=22,
  @ltv=1248,
  @customers=329,
  @asp=125,
  @arpa=1250,
  @arr=238000,
  @mrr=21089
  >, 
  <...more entries...>
]
>
{
  "entries":[
    {
      "date":"2015-01-31",
      "customer-churn-rate":20,
      "mrr-churn-rate":14,
      "ltv":1250.3,
      "customers":331,
      "asp":125,
      "arpa":1250,
      "arr":254000,
      "mrr":21166
    },
    {
      "date":"2015-02-28",
      "customer-churn-rate":20,
      "mrr-churn-rate":22,
      "ltv":1248,
      "customers":329,
      "asp":125,
      "arpa":1250,
      "arr":238000,
      "mrr":21089
    },
    {"...more...": "...entries..."}
  ]
}
<?php

ChartMogul\Metrics\AllKeyMetrics::__set_state(array(
    "entries" => 
  Doctrine\Common\Collections\ArrayCollection::__set_state(array(
     "elements" => 
    array (
      0 => 
      ChartMogul\Metrics\AllKeyMetric::__set_state(array(
         "date" => "2015-01-31",
         "arpa" => 1250,
         "arr" => 254000,
         "asp" => 125,
         "customer_churn_rate" => 20,
         "customers" => 331,
         "ltv" => 1250.3,
         "mrr" => 21166,
         "mrr_churn_rate" => 14,
      )),
      1 => ...
  )))
));
?>
Suggest Edits

Retrieve MRR

Retrieves the Monthly Recurring Revenue (MRR), for the specified time period.

 
gethttps://api.chartmogul.com/v1/metrics/mrr

Query Params

start-date
date
required

The start date of the required period of data. An ISO-8601 formatted date, e.g. 2015-05-12

end-date
date
required

The end date of the required period of data. An ISO-8601 formatted date, e.g. 2015-05-12

interval
string

One of day, week, month (default), or quarter

geo
string

A comma-separated list of ISO 3166-1 Alpha-2 formatted country codes to filter the results to, e.g. US,GB,DE.

plans
string

A comma-separated list of plan names (as configured in your ChartMogul account) to filter the results to. Note that spaces must be url-encoded and the names are case-sensitive, e.g. Silver%20plan,Gold%20plan,Enterprise%20plan.

 

In the response, the entries key contains an object for each interval, with the following data:

  • date - The date of the end of the interval.
  • mrr - The Monthly Recurring Revenue as at the end of the interval.
  • mrr-new-business - New MRR during the interval from new customers.
  • mrr-expansion - New MRR during the interval from existing customers (e.g. plan upgrades).
  • mrr-contraction - Decrease in MRR during the interval, excluding cancellations.
  • mrr-churn - Total decrease in MRR from customers who cancelled a subscription.
  • mrr-reactivation - Increase in MRR from customers who previously cancelled a subscription.

All amounts are given in the selected currency of your account, and are an integer number of cents. Divide by 100 to obtain the actual value.

The summary key contains the MRR data for the current period (based on the interval parameter supplied) and the period immediately before that. For example, if you request an interval value of month, you will receive the MRR calculated for the current month, and the one previous to it.

Examples

curl -X GET "https://api.chartmogul.com/v1/metrics/mrr" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_KEY \
     -d start-date=2015-01-01 \
     -d end-date=2015-11-01 \
     -d interval=week
ChartMogul::Metrics.mrr(start_date: '2015-01-01', end_date: '2015-11-01', interval: 'week')
ChartMogul.Metrics.mrr(config, {
   'start-date': '2015-01-01',
   'end-date': '2015-11-01',
   'interval': 'week'
}, function (err, res) {
   // asynchronously called
});
<?php

ChartMogul\Metrics::mrr([
    "start-date" => "2015-01-01",
    "end-date" => "2015-11-01",
    "interval" => "month"
]);
?>

Result Format

{
  "entries":[
    {
      "date":"2015-01-03",
      "mrr":30000,
      "mrr-new-business":10000,
      "mrr-expansion":15000,
      "mrr-contraction":0,
      "mrr-churn":0,
      "mrr-reactivation":0
    },
    {
      "date":"2015-01-10",
      "mrr":30000,
      "mrr-new-business":0,
      "mrr-expansion":0,
      "mrr-contraction":0,
      "mrr-churn":0,
      "mrr-reactivation":0
    },
    {"...more...": "...entries..."}
  ],
  "summary":{
    "current":43145000,
    "previous":43145000,
    "percentage-change":0.0
  }
}
#<ChartMogul::Metrics::MRRs:0x007fa4ed85e0f0 
@entries=[
  #<ChartMogul::Metrics::MRR:0x007fa4ed85cf48 
  @date=2015-01-03,
  @mrr=30000,
  @mrr_new_business=10000,
  @mrr_expansion=15000,
  @mrr_contraction=0,
  @mrr_churn=0,
  @mrr_reactivation=0
  >, 
  #<ChartMogul::Metrics::MRR:0x007fa4ed854a50 
  @date=2015-01-10,
  @mrr=30000,
  @mrr_new_business=0,
  @mrr_expansion=0,
  @mrr_contraction=0,
  @mrr_churn=0,
  @mrr_reactivation=0
  >,
  <...more entries...>
],
@summary=
  #<ChartMogul::Summary:0x007fa4ec07dda0
  @current=43145000,
  @previous=43145000,
  @percentage_change=0.0
>
>
{ 
  "entries":[
    { 
      "date": "2015-01-03",
      "mrr": 2083,
      "mrr-new-business": 2083,
      "mrr-expansion": 0,
      "mrr-contraction": 0,
      "mrr-churn": 0,
      "mrr-reactivation": 0
    },
    {
      "date": "2015-01-10",
      "mrr": 15166,
      "mrr-new-business": 13083,
      "mrr-expansion": 0,
      "mrr-contraction": 0,
      "mrr-churn": 0,
      "mrr-reactivation": 0
    },
    {
      "date": "2015-01-17",
      "mrr": 26749,
      "mrr-new-business": 11583,
      "mrr-expansion": 0,
      "mrr-contraction": 0,
      "mrr-churn": 0,
      "mrr-reactivation": 0
    },
    {"...more...": "...entries..."}
  ],
  "summary": {
    "current": 1131228,
    "previous": 1211228,
    "percentage-change": -7
  }
}
<?php

ChartMogul\Metrics\MRRs::__set_state(array(
   "entries" => 
  Doctrine\Common\Collections\ArrayCollection::__set_state(array(
     "elements" => 
    array (
      0 => 
      ChartMogul\Metrics\MRR::__set_state(array(
         "date" => "2015-01-03",
         "mrr" => 2083,
         "mrr_new_business" => 2083,
         "mrr_expansion" => 0,
         "mrr_contraction" => 0,
         "mrr_churn" => 0,
         "mrr_reactivation" => 0,
      )),
      1 => ...
   ))),
   "summary" => 
  ChartMogul\Summary::__set_state(array(
     "current" => 1131228,
     "previous" => 1211228,
     "percentage_change" => -7,
  )),
));
?>
Suggest Edits

Retrieve ARR

Retrieves the Annualized Run Rate (ARR), for the specified time period.

 
gethttps://api.chartmogul.com/v1/metrics/arr

Query Params

start-date
date
required

The start date of the required period of data. An ISO-8601 formatted date, e.g. 2015-05-12

end-date
date
required

The end date of the required period of data. An ISO-8601 formatted date, e.g. 2015-05-12

interval
string

One of day, week, month (default), or quarter

geo
string

A comma-separated list of ISO 3166-1 Alpha-2 formatted country codes to filter the results to, e.g. US,GB,DE.

plans
string

A comma-separated list of plan names (as configured in your ChartMogul account) to filter the results to. Note that spaces must be url-encoded and the names are case-sensitive, e.g. Silver%20plan,Gold%20plan,Enterprise%20plan.

 

In the response, the entries key contains an object for each interval, with the following data:

  • date - the end date of each interval period.
  • arr - the Annual Recurring Revenue as at the end of each interval period. This is in your account's selected currency, and is an integer number of cents. Divide it by 100 to obtain the actual value.

The summary key contains the ARR data for the current period (based on the interval parameter supplied) and the period immediately before that. For example, if you request an interval value of month, you will receive the ARR calculated for the current month, and the one previous to it.

Examples

curl -X GET "https://api.chartmogul.com/v1/metrics/arr" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_KEY \
     -d start-date=2015-01-01 \
     -d end-date=2015-11-24 \
     -d geo=US \
     -d interval=month 
ChartMogul::Metrics.arr(start_date: '2015-01-01', end_date: '2015-11-24', geo: 'US', interval: 'month')
ChartMogul.Metrics.arr(config, {
   'start-date': '2015-01-01',
   'end-date': '2015-11-24',
   'interval': 'month',
   'geo': 'GB',
   'plans': 'PRO Plan'
}, function (err, res) {
   // asynchronously called
});
<?php

ChartMogul\Metrics::arr([
    "start-date" => "2015-01-01",
    "end-date" => "2015-11-24",
    "interval" => "month",
    "geo" => "GB",
    "plans" => "PRO Plan"
]);
?>

Result Format

{
  "entries":[
    {
      "date":"2015-01-31",
      "arr":360000
    },
    {
      "date":"2015-02-28",
      "arr":36600000
    },
    {"...more...": "...entries..."}
  ],
  "summary":{
    "current":305520000,
    "previous":305520000,
    "percentage-change":0.0
  }
}
#<ChartMogul::Metrics::ARRs:0x007fa4ec673778 
@entries=[
  #<ChartMogul::Metrics::ARR:0x007fa4ec673368 
  @date=2015-01-31, 
  @arr=360000
  >, 
  #<ChartMogul::Metrics::ARR:0x007fa4ec672e18 
  @date=2015-02-28, 
  @arr=36600000
  >,
  <...more entries...>
], 
@summary=
  #<ChartMogul::Summary:0x007fa4ec64bde0 
  @current=305520000,
  @previous=305520000,
  @percentage_change=0.0
  >
>
{
  "entries":[
    {
      "date":"2015-01-31",
      "arr":360000
    },
    {
      "date":"2015-02-28",
      "arr":36600000
    },
    {"...more...": "...entries..."}
  ],
  "summary":{
    "current":305520000,
    "previous":305520000,
    "percentage-change":0.0
  }
}
<?php

ChartMogul\Metrics\ARRs::__set_state(array(
    "entries" => 
  Doctrine\Common\Collections\ArrayCollection::__set_state(array(
     "elements" => 
    array (
      0 => 
      ChartMogul\Metrics\ARR::__set_state(array(
         "date" => "2015-01-31",
         "arr" => 360000,
      )),
      1 => ...
  ))),
   "summary" => 
  ChartMogul\Summary::__set_state(array(
     "current" => 305520000,
     "previous" => 305520000,
     "percentage_change" => 0.0,
  )),
));
?>
Suggest Edits

Retrieve Average Revenue Per Account (ARPA)

Retrieves the Average Revenue Per Account (ARPA), for the specified time period.

 
gethttps://api.chartmogul.com/v1/metrics/arpa

Query Params

start-date
date
required

The start date of the required period of data. An ISO-8601 formatted date, e.g. 2015-05-12

end-date
date
required

The end date of the required period of data. An ISO-8601 formatted date, e.g. 2015-05-12

interval
string

One of day, week, month (default), quarter

geo
string

A comma-separated list of ISO 3166-1 Alpha-2 formatted country codes to filter the results to, e.g. US,GB,DE.

plans
string

A comma-separated list of plan names (as configured in your ChartMogul account) to filter the results to. Note that spaces must be url-encoded and the names are case-sensitive, e.g. Silver%20plan, Gold%20plan, Enterprise%20plan.

 

In the response, the entries key contains an object for each interval, with the following data:

  • date - The date of the end of the interval
  • arpa - The ARPA as at the end of the period. This is in your account's selected currency, and is an integer number of cents. Divide it by 100 to obtain the actual value.

The summary key contains the ARPA data for the current period (based on the interval parameter supplied) and the period immediately before that. For example, if you request an interval value of month, you will receive the ARPA calculated for the current month, and the one previous to it.

Examples

curl -X GET "https://api.chartmogul.com/v1/metrics/arpa" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_KEY \
     -d start-date=2015-01-01 \
     -d end-date=2015-11-01 \
     -d interval=week 
ChartMogul::Metrics.arpa(start_date: '2015-01-01', end_date: '2015-11-01', interval: 'week')
ChartMogul.Metrics.arpa(config, {
   'start-date': '2015-01-01',
   'end-date': '2015-11-01',
   'interval': 'week'
}, function (err, res) {
   // asynchronously called
});
<?php

ChartMogul\Metrics::arpa([
    "start-date" => "2015-01-01",
    "end-date" => "2015-11-01",
    "interval" => "month"
]);
?>

Result Format

{
  "entries":[
    {
      "date":"2015-01-03",
      "arpa":15000
    },
    {
      "date":"2015-01-10",
      "arpa":15000
    },
    {"...more...": "...entries..."}
  ],
  "summary":{
    "current":980568,
    "previous":980568,
    "percentage-change":0.0
  }
}
#<ChartMogul::Metrics::ARPAs:0x007fa4ec591148 
@entries=[
  #<ChartMogul::Metrics::ARPA:0x007fa4ec590ef0 
  @date=2015-01-03, 
  @arpa=15000
  >, 
  #<ChartMogul::Metrics::ARPA:0x007fa4ec590ab8 
  @date=2015-01-10, 
  @arpa=15000
  >, 
  <...more entries...>
], 
@summary=#<ChartMogul::Summary:0x007fa4ec578ff8 
  @current=980568,
  @previous=980568,
  @percentage_change=0.0
  >
>
{
  "entries":[
    {
      "date":"2015-01-03",
      "arpa":15000
    },
    {
      "date":"2015-01-10",
      "arpa":15000
    },
    {"...more...": "...entries..."}
  ],
  "summary":{
    "current":980568,
    "previous":980568,
    "percentage-change":0.0
  }
}
<?php

ChartMogul\Metrics\ARPAs::__set_state(array(
   "entries" => 
  Doctrine\Common\Collections\ArrayCollection::__set_state(array(
    "elements" => 
   array (
     0 => 
     ChartMogul\Metrics\ARPA::__set_state(array(
        "date" => "2015-01-31",
        "arpa" => 15000,
     )),
     1 => ...
  ))),
   "summary" => 
  ChartMogul\Summary::__set_state(array(
     "current" => 980568,
     "previous" => 980568,
     "percentage_change" => 9.0,
  )),
));
?>
Suggest Edits

Retrieve Average Sale Price (ASP)

Retrieves the Average Sale Price (ASP), for the specified time period.

 
gethttps://api.chartmogul.com/v1/metrics/asp

Query Params

start-date
date
required

The start date of the required period of data. An ISO-8601 formatted date, e.g. 2015-05-12

end-date
date
required

The end date of the required period of data. An ISO-8601 formatted date, e.g. 2015-05-12

interval
string

One of either month (default) or quarter.

geo
string

A comma-separated list of ISO 3166-1 Alpha-2 formatted country codes to filter the results to, e.g. US,UK,DE.

plans
string

A comma-separated list of plan names (as configured in your ChartMogul account) to filter the results to. Note that spaces must be url-encoded and the names are case-sensitive, e.g. Silver%20plan,Gold%20plan,Enterprise%20plan.

 

In the response, the entries key contains an object for each interval, with the following data:

  • date - The date of the end of the interval
  • asp - The ASP as at the end of the period. This is in your account's selected currency, and is an integer number of cents. Divide it by 100 to obtain the actual value.

The summary key contains the ASP data for the current period (based on the interval parameter supplied) and the period immediately before that. For example, if you request an interval value of month, you will receive the ASP calculated for the current month, and the one previous to it.

Examples

curl -X GET "https://api.chartmogul.com/v1/metrics/asp" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_KEY \
     -d start-date=2015-01-01 \
     -d end-date=2015-11-01 \
     -d interval=month 
ChartMogul::Metrics.asp(start_date: '2015-01-01', end_date: '2015-11-01', interval: 'month')
ChartMogul.Metrics.asp(config, {
   'start-date': '2015-01-01',
   'end-date': '2015-11-01',
   'interval': 'month'
}, function (err, res) {
   // asynchronously called
});
<?php

ChartMogul\Metrics::asp([
    "start-date" => "2015-01-01",
    "end-date" => "2015-11-01",
    "interval" => "month",
]);
?>

Result Format

{
  "entries":[
    {
      "date":"2015-01-31",
      "asp":10000
    },
    {
      "date":"2015-02-28",
      "asp":524000
    },
    {"...more...": "...entries..."}
  ],
  "summary":{
    "current":524000,
    "previous":524000,
    "percentage-change":0.0
  }
}
#<ChartMogul::Metrics::ASPs:0x007fa4ec501de0 
@entries=[
  #<ChartMogul::Metrics::ASP:0x007fa4ec501930 
  @date=2015-01-31, 
  @asp=10000
  >, 
  #<ChartMogul::Metrics::ASP:0x007fa4ec5013b8 
  @date=2015-02-28, 
  @asp=524000
  >,
  <...more entries...>
], 
@summary=
  #<ChartMogul::Summary:0x007fa4ec500e18
  @current=524000,
  @previous=524000,
  @percentage_change=0.0
  >
>
{
  "entries":[
    {
      "date":"2015-01-31",
      "asp":10000
    },
    {
      "date":"2015-02-28",
      "asp":524000
    },
    {"...more...": "...entries..."}
  ],
  "summary":{
    "current":524000,
    "previous":524000,
    "percentage-change":0.0
  }
}
<?php

ChartMogul\Metrics\ASPs::__set_state(array(
   "entries" => 
  Doctrine\Common\Collections\ArrayCollection::__set_state(array(
     "elements" => 
    array (
      0 => 
      ChartMogul\Metrics\ASP::__set_state(array(
         "date" => "2015-01-31",
         "asp" => 10000,
      )),
      1 => 
      ChartMogul\Metrics\ASP::__set_state(array(
         "date" => "2015-02-28",
         "asp" => 524000,
      )),
      2 => ...
  ))),
   "summary" => 
  ChartMogul\Summary::__set_state(array(
     "current" => 524000,
     "previous" => 524000,
     "percentage_change" => 0.0,
  )),
));
?>
Suggest Edits

Retrieve Customer Count

Retrieves the number of active customers, for the specified time period.

 
gethttps://api.chartmogul.com/v1/metrics/customer-count

Query Params

start-date
date
required

The start date of the required period of data. An ISO-8601 formatted date, e.g. 2015-05-12

end-date
date
required

The end date of the required period of data. An ISO-8601 formatted date, e.g. 2015-05-12

interval
string

One of day, week, month (default), or quarter

geo
string

A comma-separated list of ISO 3166-1 Alpha-2 formatted country codes to filter the results to, e.g. US,GB,DE.

plans
string

A comma-separated list of plan names (as configured in your ChartMogul account) to filter the results to. Note that spaces must be url-encoded and the names are case-sensitive, e.g. Silver%20plan,Gold%20plan,Enterprise%20plan.

 

In the response, the entries key contains an object for each interval, with the following data:

  • date - The date of the end of the interval
  • customers - The number of active customers in your account as at the end of the interval.

The summary key contains the customer count data for the current period (based on the interval parameter supplied) and the period immediately before that. For example, if you request an interval value of week, you will receive the customer count for the current week, and the one previous to it.

Examples

curl -X GET "https://api.chartmogul.com/v1/metrics/customer-count" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_KEY \
     -d start-date=2015-07-01 \
     -d end-date=2015-11-01 \
     -d interval=month 
ChartMogul::Metrics.customer_count(start_date: '2015-07-01', end_date: '2015-11-01', interval: 'month')
ChartMogul.Metrics.customerCount(config, {
   'start-date': '2015-07-01',
   'end-date': '2015-11-01',
   'interval': 'month'
}, function (err, res) {
   // asynchronously called
});
<?php

ChartMogul\Metrics::customerCount([
    "start-date" => "2015-07-01",
    "end-date" => "2015-11-01",
    "interval" => "month",
]);
?>

Result Format

{
  "entries":[
    {
      "date":"2015-07-31",
      "customers":382
    },
    {"...more...": "...entries..."}
  ],
  "summary":{
    "current":382,
    "previous":379,
    "percentage-change":0.8
  }
}
#<ChartMogul::Metrics::CustomerCounts:0x007fa4ec4605d0 
@entries=[
  #<ChartMogul::Metrics::CustomerCount:0x007fa4ec4602d8 
  @date=2015-07-31, 
  @customers=382
  >,
  <...more entries...>
], 
@summary=
  #<ChartMogul::Summary:0x007fa4ec45a338
  @current=382,
  @previous=379,
  @percentage_change=0.8
  >
>
{
  "entries":[
    {
      "date":"2015-07-31",
      "customers":382
    },
    {"...more...": "...entries..."}
  ],
  "summary":{
    "current":382,
    "previous":379,
    "percentage-change":0.8
  }
}
<?php

ChartMogul\Metrics\CustomerCounts::__set_state(array(
   "entries" => 
  Doctrine\Common\Collections\ArrayCollection::__set_state(array(
     "elements" => 
    array (
      0 => 
      ChartMogul\Metrics\CustomerCount::__set_state(array(
         "date" => "2015-07-31",
         "customers" => 382,
      )),
      1 => 
      ChartMogul\Metrics\CustomerCount::__set_state(array(
         "date" => "2015-08-31",
         "customers" => 382,
      )),
      2 => ...
 ))),
   "summary" => 
  ChartMogul\Summary::__set_state(array(
    "current" => 382,
    "previous" => 379,
    "percentage_change" => 0.8,
  ))
));
?>
Suggest Edits

Retrieve Customer Churn Rate

Retrieves the Customer Churn Rate, for the specified time period.

 
gethttps://api.chartmogul.com/v1/metrics/customer-churn-rate

Query Params

start-date
date
required

The start date of the required period of data. An ISO-8601 formatted date, e.g. 2015-05-12

end-date
date
required

The end date of the required period of data. An ISO-8601 formatted date, e.g. 2015-05-12

geo
string

A comma-separated list of ISO 3166-1 Alpha-2 formatted country codes to filter the results to, e.g. US,UK,DE.

plans
string

A comma-separated list of plan names (as configured in your ChartMogul account) to filter the results to. Note that spaces must be url-encoded and the names are case-sensitive, e.g. Silver%20plan,Gold%20plan,Enterprise%20plan.

 

In the response, the entries key contains an object for each month, with the following data:

  • date - The date of the end of the month
  • customer-churn-rate - The customer churn rate at the end of that month, expressed as a percentage.

The summary key contains the customer churn rate data for the current month and the month immediately before that.

Examples

curl -X GET "https://api.chartmogul.com/v1/metrics/customer-churn-rate" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_KEY \
     -d start-date=2015-01-01 \
     -d end-date=2015-11-01
ChartMogul::Metrics.customer_churn_rate(start_date: '2015-01-01', end_date: '2015-11-01')
ChartMogul.Metrics.customerChurnRate(config, {
   'start-date': '2015-01-01',
   'end-date': '2015-11-01'
}, function (err, res) {
   // asynchronously called
});
<?php

ChartMogul\Metrics::customerChurnRate([
    "start-date" => "2015-01-01",
    "end-date" => "2015-11-01",
]);
?>

Result Format

{
  "entries":[
    {
      "date":"2015-01-31",
      "customer-churn-rate":9.8
    },
    {"...more...": "...entries..."}
  ],
  "summary":{
    "current":9.8,
    "previous":8.5,
    "percentage-change":2
  }
}
#<ChartMogul::Metrics::CustomerChurnRates:0x007faf03d088d8 
@entries=[
  #<ChartMogul::Metrics::CustomerChurnRate:0x007faf03d08680 
  @date=2015-01-31, 
  @customer_churn_rate=9.8
  >, 
  <...more entries...>
], 
@summary=
  #<ChartMogul::Summary:0x007faf03d01038
  @current=9.8,
  @previous=8.5,
  @percentage_change=2.0
  >
>
{
  "entries":[
    {
      "date":"2015-01-31",
      "customer-churn-rate":9.8
    },
    {"...more...": "...entries..."}
  ],
  "summary":{
    "current":9.8,
    "previous":8.5,
    "percentage-change":2
  }
}
<?php

ChartMogul\Metrics\CustomerChurnRates::__set_state(array(
   "entries" => 
  Doctrine\Common\Collections\ArrayCollection::__set_state(array(
     "elements" => 
    array (
      0 => 
      ChartMogul\Metrics\CustomerChurnRate::__set_state(array(
         "date" => "2015-01-31",
         "customer_churn_rate" => 9.8,
      )),
      1 => ...
  ))),
   "summary" => 
  ChartMogul\Summary::__set_state(array(
     "current" => 9.8,
     "previous" => 8.5,
     "percentage_change" => 2,
  )),
?>
Suggest Edits

Retrieve MRR Churn Rate

Retrieves the Net MRR Churn Rate, for the specified time period.

 
gethttps://api.chartmogul.com/v1/metrics/mrr-churn-rate

Query Params

start-date
date
required

The start date of the required period of data. An ISO-8601 formatted date, e.g. 2015-05-12

end-date
date
required

The end date of the required period of data. An ISO-8601 formatted date, e.g. 2015-05-12

geo
string

A comma-separated list of ISO 3166-1 Alpha-2 formatted country codes to filter the results to, e.g. US,UK,DE.

plans
string

A comma-separated list of plan names (as configured in your ChartMogul account) to filter the results to. Note that spaces must be url-encoded and the names are case-sensitive, e.g. Silver%20plan,Gold%20plan,Enterprise%20plan.

 

In the response, the entries key contains an object for each month, with the following data:

  • date - The date of the end of the month
  • mrr-churn-rate - The Net MRR churn rate at the end of that month, expressed as a percentage.

Note that MRR Churn Rate can be both negative, and larger than 100% - in this case, a negative churn rate of -300.0% means that the MRR actually quadrupled during that period.
Normal values will typically be between -10% and +10%, though that depends, naturally, on what your customers are actually doing.

The summary key contains the MRR churn rate data for the current month and the month immediately before that.

Examples

curl -X GET "https://api.chartmogul.com/v1/metrics/mrr-churn-rate" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_KEY \
     -d start-date=2015-01-01 \
     -d end-date=2015-11-01
ChartMogul::Metrics.mrr_churn_rate(start_date: '2015-01-01', end_date: '2015-11-01')
ChartMogul.Metrics.mrrChurnRate(config, {
   'start-date': '2015-01-01',
   'end-date': '2015-11-01'
}, function (err, res) {
   // asynchronously called
});
<?php

ChartMogul\Metrics::mrrChurnRate([
    "start-date" => "2015-01-01",
    "end-date" => "2015-11-01",
]);
?>

Result Format

{
  "entries":[
    {
      "date":"2015-01-31",
      "mrr-churn-rate":-300.0
    },
    {
      "date":"2015-02-28",
      "mrr-churn-rate":-0.0
    },
    {"...more...": "...entries..."}
  ],
  "summary":{
    "current":0,
    "previous":0,
    "percentage-change":0.0
  }
}
#<ChartMogul::Metrics::MrrChurnRates:0x007faf03caacd8 
@entries=[
  #<ChartMogul::Metrics::MrrChurnRate:0x007faf03caa990 
  @date=2015-01-31, 
  @mrr_churn_rate=-300.00
  >, 
  #<ChartMogul::Metrics::MrrChurnRate:0x007faf03caa3a0 
  @date=2015-02-28, 
  @mrr_churn_rate=-0.0
  >, 
  <...more entries...>
], 
@summary=
  #<ChartMogul::Summary:0x007faf03ca3dc0
  @current=0,
  @previous=0,
  @percentage_change=0.0
>
>
{
  "entries":[
    {
      "date":"2015-01-31",
      "mrr-churn-rate":-300.0
    },
    {
      "date":"2015-02-28",
      "mrr-churn-rate":-0.0
    },
    {"...more...": "...entries..."}
  ],
  "summary":{
    "current":0,
    "previous":0,
    "percentage-change":0.0
  }
}
<?php

ChartMogul\Metrics\MRRChurnRates::__set_state(array(
    "entries" => 
   Doctrine\Common\Collections\ArrayCollection::__set_state(array(
      "elements" => 
     array (
       0 => 
       ChartMogul\Metrics\MRRChurnRate::__set_state(array(
          "date" => "2015-01-31",
          "mrr_churn_rate" => -300.0,
       )),
       1 => 
       ChartMogul\Metrics\MRRChurnRate::__set_state(array(
          "date" => "2015-02-28",
          "mrr_churn_rate" => -0.0,
       )),
       2 => ...
   ))),
   "summary" => 
  ChartMogul\Summary::__set_state(array(
     "current" => 0,
     "previous" => 0,
     "percentage_change" => 0.0,
  )),
));
?>
Suggest Edits

Retrieve LTV

Retrieves the Customer Lifetime Value (LTV), for the specified time period.

 
gethttps://api.chartmogul.com/v1/metrics/ltv

Query Params

start-date
date
required

The start date of the required period of data. An ISO-8601 formatted date, e.g. 2015-05-12

end-date
date
required

The end date of the required period of data. An ISO-8601 formatted date, e.g. 2015-05-12

geo
string

A comma-separated list of ISO 3166-1 Alpha-2 formatted country codes to filter the results to, e.g. US,UK,DE.

plans
string

A comma-separated list of plan names (as configured in your ChartMogul account) to filter the results to. Note that spaces must be url-encoded and the names are case-sensitive, e.g. Silver%20plan,Gold%20plan,Enterprise%20plan.

 

In the response, the entries key contains an object for each month, with the following data:

  • date - The date of the end of the month
  • ltv - The Customer LTV as at the end of the month. This is in your account's selected currency, and is a number of cents. Divide it by 100 to obtain the actual value.

LTV is presented with more precision than most monetary values in ChartMogul due to the way it is calculated, and used by some of our customers.

The summary key contains the LTV data for the current month and the month immediately before that.

Examples

curl -X GET "https://api.chartmogul.com/v1/metrics/ltv" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_KEY \
     -d start-date=2015-01-01 \
     -d end-date=2015-11-01
ChartMogul::Metrics.ltv(start_date: '2015-01-01', end_date: '2015-11-01')
ChartMogul.Metrics.ltv(config, {
   'start-date': '2015-01-01',
   'end-date': '2015-11-01'
}, function (err, res) {
   // asynchronously called
});
<?php

ChartMogul\Metrics::ltv([
    "start-date" => "2015-01-01",
    "end-date" => "2015-11-01",
]);
?>

Result Format

{
  "entries":[
    {
      "date":"2015-01-31",
      "ltv":0
    },
    {
      "date":"2015-02-28",
      "ltv":0
    },
    {
      "date":"2015-03-31",
      "ltv":1862989.7959183701
    },
    {"...more...": "...entries..."}
  ],
  "summary":{
    "current":980568,
    "previous":980568,
    "percentage-change":0.0
  }
}
#<ChartMogul::Metrics::LTVs:0x007faf03c4b440 
@entries=[
  #<ChartMogul::Metrics::LTV:0x007faf03c4b0a8 
  @date=2015-01-31, 
  @ltv=0
  >, 
  #<ChartMogul::Metrics::LTV:0x007faf03c4aab8 
  @date=2015-02-28, 
  @ltv=0
  >, 
  #<ChartMogul::Metrics::LTV:0x007faf03c4a720 
  @date=2015-03-31, 
  @ltv=1862989.7959183701
  >, 
  <...more entries...>
], 
@summary=
  #<ChartMogul::Summary:0x007faf03c484c0
  @current=980568,
  @previous=980568,
  @percentage_change=0
>
>
{
  "entries":[
    {
      "date":"2015-01-31",
      "ltv":0
    },
    {
      "date":"2015-02-28",
      "ltv":0
    },
    {
      "date":"2015-03-31",
      "ltv":1862989.7959183701
    },
    {"...more...": "...entries..."}
  ],
  "summary":{
    "current":980568,
    "previous":980568,
    "percentage-change":0.0
  }
}
<?php

ChartMogul\Metrics\LTVs::__set_state(array(
    "entries" =>
   Doctrine\Common\Collections\ArrayCollection::__set_state(array(
      "elements" =>
     array (
       0 =>
       ChartMogul\Metrics\LTV::__set_state(array(
          "date" => "2015-01-31",
          "ltv" => 0.0,
       )),
       1 =>
       ChartMogul\Metrics\LTV::__set_state(array(
          "date" => "2015-02-28",
          "ltv" => 0.0,
       )),
       2 => 
       ChartMogul\Metrics\LTV::__set_state(array(
          "date" => "2015-03-31",
          "ltv" => 1862989.7959183701,
       )),
       3 => ...
   ))),
    "summary" =>
   ChartMogul\Summary::__set_state(array(
      "current" => 980568,
      "previous" => 980568,
      "percentage_change" => 0.0,
   )),
));
?>
Suggest Edits

List Customer Subscriptions

Returns a list of subscriptions for a given customer.

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

Path Params

customer_uuid
string
required

The ChartMogul UUID of the customer.

Query Params

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 object for each subscription, with the following data:

  • id - ChartMogul's identifier for the subscription
  • plan - the billing plan that the customer has subscribed to with this subscription.
  • quantity - the quantity of plans purchased by the customer.
  • mrr - the current Monthly Recurring Revenue contributed by this subscription.
  • arr - the current Annual Run Rate of this subscription. This is calculated as the MRR * 12.
  • status - the current status of this subscription. One of inactive or active
  • billing-cycle - the billing cycle period. One of day, month, or year.
  • billing-cycle-count - the integer number representing frequency of billing cycle.
  • start-date - the timestamp for when this subscription started.
  • end-date - the timestamp for when this subscription is due to run out based on payments made so far.
  • currency - the currency of the MRR and ARR readings.
  • 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/cus_3f6f53d3-bca7-4fcd-ad47-345180ef329b/subscriptions" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_KEY
     -H "Content-Type: application/json"
ChartMogul::Metrics::Subscription.all('cus_3f6f53d3-bca7-4fcd-ad47-345180ef329b')
ChartMogul.Metrics.Customer.subscriptions(config, "cus_3f6f53d3-bca7-4fcd-ad47-345180ef329b", function (err, res) {
   // asynchronously called
});
<?php

ChartMogul\Metrics\Subscriptions::all(
        ["customer_uuid" => "cus_3f6f53d3-bca7-4fcd-ad47-345180ef329b"]
);
?>

Result Format

{
  "entries": [
    {
      "id": 9306830,
      "plan": "PRO Plan (10,000 active cust.) monthly",
      "quantity": 1,
      "mrr": 70800,
      "arr": 849600,
      "status": "active",
      "billing-cycle": "month",
      "billing-cycle-count": 1,
      "start-date": "2015-12-20T08:26:49-05:00",
      "end-date": "2016-03-20T09:26:49-05:00",
      "currency": "USD",
      "currency-sign": "$"
    }
  ],
  "has_more": false,
  "per_page": 200,
  "page": 1
}
#<ChartMogul::Metrics::Subscriptions:0x007faf058c8f28 
@entries=[
  #<ChartMogul::Metrics::Subscription:0x007faf058c8d98 
  @id=9306830, 
  @plan="PRO Plan (10,000 active cust.) monthly", 
  @quantity=1, 
  @mrr=70800, 
  @arr=849600, 
  @status="active", 
  @billing_cycle="month", 
  @billing_cycle_count=1, 
  @start_date=2015-12-20 08:26:49 -0500, 
  @end_date=2016-03-20 09:26:49 -05:00, 
  @currency="USD", 
  @currency_sign="$"
  >
], 
@has_more=false, 
@per_page=200, 
@page=1
>
{
  "entries": [
    {
      "id": 9306830,
      "plan": "PRO Plan (10,000 active cust.) monthly",
      "quantity": 1,
      "mrr": 70800,
      "arr": 849600,
      "status": "active",
      "billing-cycle": "month",
      "billing-cycle-count": 1,
      "start-date": "2015-12-20T08:26:49-05:00",
      "end-date": "2016-03-20T09:26:49-05:00",
      "currency": "USD",
      "currency-sign": "$"
    }
  ],
  "has_more": false,
  "per_page": 200,
  "page": 1
}
<?php

ChartMogul\Metrics\Subscriptions::__set_state(array(
   "entries" => 
  Doctrine\Common\Collections\ArrayCollection::__set_state(array(
     "elements" => 
    array (
      ChartMogul\Metrics\Subscription::__set_state(array(
        "id" => 9306830,
        "plan" => "PRO Plan (10,000 active cust.) monthly",
        "quantity" => 1,
        "mrr" => 70800,
        "arr" => 849600,
        "status" => "active",
        "billing-cycle" => "month",
        "billing-cycle-count" => 1,
        "start-date" => "2015-12-20T08:26:49-05:00",
        "end-date" => "2016-03-20T09:26:49-05:00",
        "currency" => "USD",
        "currency-sign" => "$"
      ))
    ),
  )),
   "has_more" => false,
   "per_page" => 200,
   "page" => 1,
))
?>
Suggest Edits

List Customer Activities

Returns a list of activities for a given customer.

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

Path Params

customer_uuid
string
required

The ChartMogul UUID of the customer.

Query Params

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 object for each activity, with the following data:

  • activity-arr - The new ARR after the activity has occurred.
  • activity-mrr - The new MRR after the activity has occurred.
  • activity-mrr-movement - The change in MRR as a result of the activity. May
    be a positive or negative number. All amounts are expressed as an integer number
    of cents in your account currency. Divide by 100 to obtain the actual amount.
  • currency - the code representing your account currency, e.g. USD or EUR
  • currency-sign - textual representation of the currency sign, e.g. $ or
  • date - The timestamp of when the activity occurred.
  • description - a description of the activity.
  • id - ChartMogul's identifier for the activity
  • type - The type of the activity. One of new_biz, churn, expansion,
    contraction or reactivation.

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/cus_58c7d166-3bd1-4c10-948e-e68bb0fa2478/activities" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_KEY
ChartMogul::Metrics::Activity.all('cus_58c7d166-3bd1-4c10-948e-e68bb0fa2478')
ChartMogul.Metrics.Customer.activities(config, "cus_3f6f53d3-bca7-4fcd-ad47-345180ef329b", function (err, res) {
   // asynchronously called
});
<?php

ChartMogul\Metrics\Activities::all(
        ["customer_uuid" => "cus_3f6f53d3-bca7-4fcd-ad47-345180ef329b"]
);
?>

Result Format

{
  "entries":[
    {
      "activity-arr": 24000,
      "activity-mrr": 2000,
      "activity-mrr-movement": 2000,
      "currency": "USD",
      "currency-sign": "$",
      "date": "2015-06-09T13:16:00-04:00",
      "description": "purchased the Silver Monthly plan (1)",
      "id": 48730,
      "type": "new_biz"
    },
    {"...more...": "...entries..."}
  ],
  "has_more":false,
  "per_page":200,
  "page":1
}
#<ChartMogul::Metrics::Activities:0x007faf03bda6f0 
@entries=[
  #<ChartMogul::Metrics::Activity:0x007faf03bd96b0 
  @activity_arr=24000,
  @activity_mrr=2000,
  @activity_mrr_movement=2000,
  @currency="USD",
  @currency_sign="$",
  @date=2015-06-09 13:16:00 -04:00,
  @description="purchased the Silver Monthly plan (1)", 
  @id=48730,
  @type="new_biz"
  >, 
  <...more entries...>
], 
@has_more=false, 
@per_page=200, 
@page=1
>
{
  "entries":[
    {
      "activity-arr": 24000,
      "activity-mrr": 2000,
      "activity-mrr-movement": 2000,
      "currency": "USD",
      "currency-sign": "$",
      "date": "2015-06-09T13:16:00-04:00",
      "description": "purchased the Silver Monthly plan (1)",
      "id": 48730,
      "type": "new_biz"
    },
    {"...more...": "...entries..."}
  ],
  "has_more":false,
  "per_page":200,
  "page":1
}
<?php

ChartMogul\Metrics\Subscriptions::__set_state(array(
   "entries" =>
  Doctrine\Common\Collections\ArrayCollection::__set_state(array(
     "elements" =>
    array (
      ChartMogul\Metrics\Activity::__set_state(array(
        "activity-arr" => 24000,
        "activity-mrr" => 2000,
        "activity-mrr-movement" => 2000,
        "currency" => "USD",
        "currency-sign" => "$",
        "date" => "2015-06-09T13:16:00-04:00",
        "description" => "purchased the Silver Monthly plan (1)",
        "id" => 48730,
        "type" => "new_biz"
      ))
    ),
  )),
   "has_more" => false,
   "per_page" => 200,
   "page" => 1,
))
?>