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    

Getting started with the Import API

You can use the ChartMogul Import API to import your customer and billing data.

If you are using Stripe, Braintree, Recurly, Chargify or PayPal to manage your subscription billing we recommend trying our pre-built integrations first.

This tutorial describes how you can import billing data into your ChartMogul account and keep your data in sync for real-time analytics. You can refer to our data model if you would like a system overview first.

Importing your billing data

1. Create a Data Source

The ChartMogul Import API allows you to import customer billing data from multiple data sources. Start by using the endpoint to create a data source. This will return a Data Source UUID for each data source that's created in ChartMogul. Save this Data Source UUID for use in subsequent API requests.

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

// 1. Create a Data Source
\ChartMogul\DataSource::create([
    "name" => "In-house Billing"
]);
?>
// 1. Create a Data Source
ds, err := api.CreateDataSource("In-house billing")
# 1. Create a Data Source
chartmogul.DataSource.create(
  	config,
    data={'name': 'In-house billing'}
).then(lambda ds: print(ds)).get()

Creating a Data Source using the UI

You can also create a data source by going to Admin > Data load, clicking on the Add Data Source button, and choosing Import API as the system. Be sure to save the UUID of the new data source for use in subsequent API requests.

2. Create Customers

Create customers in ChartMogul using the endpoint to create a Customer. This will return a Customer UUID for each customer object that's created. Save these Customer UUIDs for use in subsequent API requests.

# 2. Create Customers
curl -X POST "https://api.chartmogul.com/v1/customers" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_KEY \
     -H "Content-Type: application/json" \
     -d '{
          "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
          "external_id": "cus_0001",
          "name": "Adam Smith",
          "email": "[email protected]",
          "country": "US",
          "city": "New York"
         }'
# 2. Create Customers
ChartMogul::Customer.create!(
  data_source_uuid: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  external_id: "cus_0001",
  name: "Adam Smith",
  email: "[email protected]",
  country: "US",
  city: "New York"
)
// 2. Create Customers
ChartMogul.Customer.create(config, {
    "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
    "external_id": "cus_0001",
    "name": "Adam Smith",
    "email": "[email protected]",
    "country": "US",
    "city": "New York"
}, function(err, res) {
    // asynchronously called
});
<?php

// 2. Create Customers
\ChartMogul\Customer::create([
    "data_source_uuid" => "ds_e243129a-12c0-4e29-8f54-07da7905fbd1",
    "external_id" => "cus_0001",
    "name" => "Adam Smith",
    "email" => "[email protected]",
    "country" => "US",
    "city" => "New York"
]);
?>
// 2. Create Customers
cus, err := api.CreateCustomer(&cm.NewCustomer{
  DataSourceUUID: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  ExternalID:     "cus_0001",
  Name:           "Adam Smith",
  Email:          "[email protected]",
  Country:        "US",
  City:           "New York",
})
# 2. Create Customers
chartmogul.Customer.create(config, data={
    "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
    "external_id": "cus_0001",
    "name": "Adam Smith",
    "email": "[email protected]",
    "country": "US",
    "city": "New York"
}).then(lambda cus: print(cus)).get()

3. Create Subscription Plans

Create subscription plans in ChartMogul using the endpoint to create a Plan. This will return a Plan UUID for each plan object that's created. Save these Plan UUIDs for use in subsequent API requests.

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

// 3. Create Subscription Plans
ChartMogul\Plan::create([
    "data_source_uuid" => "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
    "name" => "Bronze Plan",
    "interval_count" => 1,
    "interval_unit" => "month",
    "external_id" => "plan_0001"
]);
?>
// 3. Create Subscription Plans
plan, err := api.CreatePlan(&cm.Plan{
  DataSourceUUID: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  Name:           "Bronze Plan",
  IntervalCount:  1,
  IntervalUnit:   "month",
  ExternalID:     "plan_0001",
})
# 3. Create Subscription Plans
chartmogul.Plan.create(config, data={
    "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
    "name": "Bronze Plan",
    "interval_count": 1,
    "interval_unit": "month",
    "external_id": "plan_0001"
}).then(lambda result: print(result)).get()

Creating a Plan using the UI

You can also create a plan by going to Admin > Data settings, clicking on the Add Plan button, and choosing the Import API data source for which you want to add a plan. Be sure to save the UUID of the new plan for use in subsequent API requests.

4. Send Invoices

Send each customer's Invoices to ChartMogul using the endpoint to import customer's Invoices.

Invoices are the crucial component

  • ChartMogul Invoice objects are designed specifically for generating subscription analytics. We auto-generate subscription objects and metrics from these Invoice objects. The focus in these Invoice objects is primarily on their line items and transactions. Pay close attention to the construction of this object.
  • Please note that invoice data will take up to a few minutes to appear in your ChartMogul account. Your data will be processed and reported faster if you send us several customer invoices with each request, instead of one invoice at a time.
  • Once imported, it is not yet possible to edit or delete invoices or their line items and transactions. You will have to delete the customer that the invoice belongs to, and re-create the data once again.
# 4. Send Invoices
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
            }
          ],
          "transactions": [
            {
              "date": "2015-11-05 00:14:23",
              "type": "payment",
              "result": "successful"
            }
          ]   
       },
       {
          "external_id": "INV0002",
          "date": "2015-12-01 00:00:00",
          "currency": "USD",
          "due_date": "2015-12-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-12-01 00:00:00",
              "service_period_end": "2016-01-01 00:00:00",
              "amount_in_cents": 5000,
              "quantity": 1,
              "discount_code": "PSO86",
              "discount_amount_in_cents": 1000,
              "tax_amount_in_cents": 900
            }
          ],
          "transactions": [
            {
              "date": "2015-12-05 07:54:02",
              "type": "payment",
              "result": "successful"
            }
          ]   
       }
     ]
     }'
# 4. Send Invoices
customer = ChartMogul::Customer.all(external_id:"cus_0001").first
plan = ChartMogul::Plan.all(external_id:"plan_0001").first

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

line_item_2 = ChartMogul::LineItems::Subscription.new(
  subscription_external_id: "sub_0001",
  plan_uuid: plan.uuid,
  service_period_start: Time.utc(2015, 12, 1),
  service_period_end: Time.utc(2016, 1, 1),
  amount_in_cents: 5000,
  quantity: 1,
  discount_code: "PSO86",
  discount_amount_in_cents: 1000,
  tax_amount_in_cents: 900
)
transaction_2 = ChartMogul::Transactions::Payment.new(
  date: Time.utc(2015, 12, 5, 7, 54, 02),
  result: 'successful'
)
invoice_2 = ChartMogul::Invoice.new(
  external_id: 'INV0002',
  date: Time.utc(2015, 12, 1),
  currency: 'USD',
  due_date: Time.utc(2015, 12, 15),
  line_items: [line_item_2],
  transactions: [transaction_2]
)

ChartMogul::CustomerInvoices.create!(customer_uuid: customer.uuid, invoices: [invoice_1, invoice_2])
// 4. Send Invoices
ChartMogul.Invoice.create(config,
    "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7", {
        "invoices": [{
            "external_id": "INV0001",
            "date": "2015-11-01 00:00:00",
            "currency": "USD",
            "due_date": "2015-11-15 00:00:00",
            "line_items": [{
                "type": "subscription",
                "subscription_external_id": "sub_0001",
                "plan_uuid": "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
                "service_period_start": "2015-11-01 00:00:00",
                "service_period_end": "2015-12-01 00:00:00",
                "amount_in_cents": 5000,
                "quantity": 1,
                "discount_code": "PSO86",
                "discount_amount_in_cents": 1000,
                "tax_amount_in_cents": 900
            }],
            "transactions": [{
                "date": "2015-11-05 00:14:23",
                "type": "payment",
                "result": "successful"
            }]
        }, {
            "external_id": "INV0002",
            "date": "2015-12-01 00:00:00",
            "currency": "USD",
            "due_date": "2015-12-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-12-01 00:00:00",
                "service_period_end": "2016-01-01 00:00:00",
                "amount_in_cents": 5000,
                "quantity": 1,
                "discount_code": "PSO86",
                "discount_amount_in_cents": 1000,
                "tax_amount_in_cents": 900
            }],
            "transactions": [{
                "date": "2015-12-05 07:54:02",
                "type": "payment",
                "result": "successful"
            }]
        }]
    },
    function(err, res) {
        // asynchronously called
    });
<?php

// 4. Send Invoices
$customer = ChartMogul\Customer::all(["external_id" => "cus_0001"])->first();
$plan = ChartMogul\Plan::all(["external_id" => "plan_0001"])->first();

$line_item_1 = new ChartMogul\LineItems\Subscription([
    "subscription_external_id" => "sub_0001",
    "plan_uuid" => $plan->uuid,
    "service_period_start" => "2015-11-01",
    "service_period_end" => "2015-12-01",
    "amount_in_cents" => 5000,
    "quantity" => 1,
    "discount_code" => "PSO86",
    "discount_amount_in_cents" => 1000,
    "tax_amount_in_cents" => 900
        ]);

$transaction_1 = new ChartMogul\Transactions\Payment([
    "date" => "2015-11-05",
    "result" => "successful"
        ]);

$invoice_1 = new ChartMogul\Invoice([
    "external_id" => "INV0001",
    "date" => "2015-11-01",
    "currency" => "USD",
    "due_date" => "2015-11-15",
    "line_items" => [$line_item_1],
    "transactions" => [$transaction_1]
        ]);

$line_item_2 = new ChartMogul\LineItems\Subscription([
    "subscription_external_id" => "sub_0001",
    "plan_uuid" => $plan->uuid,
    "service_period_start" => "2015-12-01",
    "service_period_end" => "2016-01-01",
    "amount_in_cents" => 5000,
    "quantity" => 1,
    "discount_code" => "PSO86",
    "discount_amount_in_cents" => 1000,
    "tax_amount_in_cents" => 900
        ]);

$transaction_2 = new ChartMogul\Transactions\Payment([
    "date" => "2015-12-05",
    "result" => "successful"
        ]);

$invoice_2 = new ChartMogul\Invoice([
    "external_id" => "INV0002",
    "date" => "2015-12-01",
    "currency" => "USD",
    "due_date" => "2015-12-15",
    "line_items" => [$line_item_2],
    "transactions" => [$transaction_2]
        ]);

ChartMogul\CustomerInvoices::create([
    "customer_uuid" => $customer->uuid,
    "invoices" => [$invoice_1, $invoice_2]
]);
?>
// 4. Send Invoices
lineItem1 := &cm.LineItem{
  SubscriptionExternalID: "sub_0001",
  PlanUUID:               "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
  ServicePeriodStart:     "2015-11-01 00:00:00",
  ServicePeriodEnd:       "2015-12-01 00:00:00",
  AmountInCents:          5000,
  Quantity:               1,
  DiscountCode:           "PSO86",
  DiscountAmountInCents:  1000,
  TaxAmountInCents:       900,
  Type:                   "subscription",
}
transaction1 := &cm.Transaction{
  Date:   "2015-11-05 00:14:23",
  Type:   "payment",
  Result: "successful",
}
invoice1 := &cm.Invoice{
  ExternalID:   "INV0001",
  Date:         "2015-11-01 00:00:00",
  Currency:     "USD",
  DueDate:      "2015-11-15 00:00:00",
  LineItems:    []*cm.LineItem{lineItem1},
  Transactions: []*cm.Transaction{transaction1},
}

lineItem2 := &cm.LineItem{
  SubscriptionExternalID: "sub_0001",
  PlanUUID:               "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
  ServicePeriodStart:     "2015-12-01 00:00:00",
  ServicePeriodEnd:       "2016-01-01 00:00:00",
  AmountInCents:          5000,
  Quantity:               1,
  DiscountCode:           "PSO86",
  DiscountAmountInCents:  1000,
  TaxAmountInCents:       900,
  Type:                   "subscription",
}
transaction2 := &cm.Transaction{
  Date:   "2015-12-05 07:54:02",
  Type:   "payment",
  Result: "successful",
}
invoice2 := &cm.Invoice{
  ExternalID:   "INV0002",
  Date:         "2015-12-01 00:00:00",
  Currency:     "USD",
  DueDate:      "2015-12-15 00:00:00",
  LineItems:    []*cm.LineItem{lineItem2},
  Transactions: []*cm.Transaction{transaction2},
}

api.CreateInvoices([]*cm.Invoice{invoice1, invoice2},
                   "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7")
# 4. Send Invoices
chartmogul.Invoice.create(
    config,
    uuid="cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
    data={
        "invoices": [{
            "external_id": "INV0001",
            "date": datetime(2015, 11, 1, 0, 0, 0),
            "currency": "USD",
            "due_date": datetime(2015, 11, 15, 0, 0, 0),
            "line_items": [{
                "type": "subscription",
                "subscription_external_id": "sub_0001",
                "plan_uuid": "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
                "service_period_start": datetime(2015, 11, 1, 0, 0, 0),
                "service_period_end": datetime(2015, 12, 1, 0, 0, 0),
                "amount_in_cents": 5000,
                "quantity": 1,
                "discount_code": "PSO86",
                "discount_amount_in_cents": 1000,
                "tax_amount_in_cents": 900
            }],
            "transactions": [{
                "date": datetime(2015, 11, 5, 0, 14, 23),
                "type": "payment",
                "result": "successful"
            }]
        }, {
            "external_id": "INV0002",
            "date": datetime(2015, 12, 1, 0, 0, 0),
            "currency": "USD",
            "due_date": datetime(2015, 12, 15, 0, 0, 0),
            "line_items": [{
                "type": "subscription",
                "subscription_external_id": "sub_0001",
                "plan_uuid": "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
                "service_period_start": datetime(2015, 12, 1, 0, 0, 0),
                "service_period_end": datetime(2016, 1, 1, 0, 0, 0),
                "amount_in_cents": 5000,
                "quantity": 1,
                "discount_code": "PSO86",
                "discount_amount_in_cents": 1000,
                "tax_amount_in_cents": 900
            }],
            "transactions": [{
                "date": datetime(2015, 12, 5, 7, 54, 2),
                "type": "payment",
                "result": "successful"
            }]
        }]
    }).then(lambda result: print(result)).get()

Retrieving Customers & Plans

While creating Invoice objects, you will use ChartMogul Customer and Plan UUIDs saved from the previous steps to reference the right customers and plans. If required, you can retrieve all imported customer and plan objects along with their ChartMogul UUIDs using the endpoints for listing Customers and listing Plans.

Completed import of billing data

As you complete the above steps successfully, ChartMogul processes your data and generates the metrics for your account. You can log in to your ChartMogul account to view the status of the import, and the generated analytics.

The next stage is to keep your ChartMogul data in sync with your billing data.

Keeping your billing data in sync

Once you have loaded your historical billing data into ChartMogul, you can prepare the integration to keep ChartMogul updated with events that happen in your billing system.

When a New Subscription is created

When a customer starts paying for a new subscription in your billing system, you can keep ChartMogul updated by following these steps.

If the customer is a new subscriber

  1. Create the customer object first using the endpoint to create a Customer.
  2. If the subscription plan that the customer bought does not exist in the ChartMogul platform, then create a new plan object using the endpoint to create a Plan.
  3. Send us the Invoice for this new subscription using the endpoint to import customer's Invoices.

If an existing customer purchases an additional subscription

  1. If the plan that the customer subscribed to doesn't exist in ChartMogul then create it using the endpoint to create a Plan.
  2. Send us the Invoice for the purchase using the endpoint to import customer's Invoices.
# When a New Subscription is created
# a. Create the customer object if it doesn't already exist
curl -X POST "https://api.chartmogul.com/v1/customers" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_KEY \
     -H "Content-Type: application/json" \
     -d '{
          "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
          "external_id": "cus_0002",
          "name": "Alice",
          "email": "[email protected]",
          "company": "Acme inc."
         }'

# b. Create the plan if it doesn't already exist
curl -X POST "https://api.chartmogul.com/v1/plans" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_KEY \
     -H "Content-Type: application/json" \
     -d '{ 
           "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
           "name": "Gold Plan",
           "interval_count": 1,
           "interval_unit": "year"
         }'

# c. Send invoice for the new subscription with customer and plan UUIDs
curl -X POST "https://api.chartmogul.com/v1/import/customers/cus_ee325d54-7ab4-421b-cdb2-eb6b9e546034/invoices" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_KEY \
     -H "Content-Type: application/json" \
     -d '{
     "invoices":[
       {
          "external_id": "INV0003",
          "date": "2016-01-01 00:00:00",
          "currency": "USD",
          "line_items": [
            {
              "type": "subscription",
              "subscription_external_id": "sub_0002",
              "plan_uuid":"pl_ab225d54-7ab4-421b-cdb2-eb6b9e553462",
              "service_period_start": "2016-01-01 00:00:00",
              "service_period_end": "2017-01-01 00:00:00",
              "amount_in_cents": 25000
            }
          ],
          "transactions": [
            {
              "date": "2016-01-05 10:00:00",
              "type": "payment",
              "result": "successful"
            }
          ]   
        }
       ]
}'
# When a New Subscription is created
# a. Create the customer object if it doesn't already exist
customer = ChartMogul::Customer.create!(
  data_source_uuid: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  external_id: "cus_0002",
  name: "Alice",
  email: "[email protected]",
  company: "Acme inc."
)

# b. Create the plan if it doesn't already exist
plan = ChartMogul::Plan.create!(
  data_source_uuid: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  name: "Gold Plan",
  interval_count: 1,
  interval_unit: "year"
)

# c. Create invoice for the new subscription with customer and plan UUIDs
line_item_1 = ChartMogul::LineItems::Subscription.new(
  subscription_external_id: "sub_0002",
  plan_uuid: plan.uuid,
  service_period_start: Time.utc(2016, 1, 1),
  service_period_end: Time.utc(2017, 1, 1),
  amount_in_cents: 25000
)
transaction = ChartMogul::Transactions::Payment.new(
  date: Time.utc(2016, 1, 5, 10, 00, 00),
  result: 'successful'
)
invoice = ChartMogul::Invoice.new(
  external_id: 'INV0003',
  date: Time.utc(2016, 1, 5),
  currency: 'USD',
  line_items: [line_item_1],
  transactions: [transaction]
)

ChartMogul::CustomerInvoices.create!(customer_uuid: customer.uuid, invoices: [invoice])

// When a New Subscription is created
// a. Create the customer object if it doesn't already exist
ChartMogul.Customer.create(config, {
    "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
    "external_id": "cus_0002",
    "name": "Alice",
    "email": "[email protected]",
    "company": "Acme inc."
}, function(err, res) {
    // asynchronously called
});

// b. Create the plan if it doesn't already exist
ChartMogul.Plan.create(config, {
    "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
    "name": "Gold Plan",
    "interval_count": 1,
    "interval_unit": "year"
}, function(err, res) {
    // asynchronously called
});

// c. Send invoice for the new subscription with customer and plan UUIDs
ChartMogul.Invoice.create(config,
    "cus_ee325d54-7ab4-421b-cdb2-eb6b9e546034", {
        "invoices": [{
            "external_id": "INV0003",
            "date": "2016-01-01 00:00:00",
            "currency": "USD",
            "line_items": [{
                "type": "subscription",
                "subscription_external_id": "sub_0002",
                "plan_uuid": "pl_ab225d54-7ab4-421b-cdb2-eb6b9e553462",
                "service_period_start": "2016-01-01 00:00:00",
                "service_period_end": "2017-01-01 00:00:00",
                "amount_in_cents": 25000
            }],
            "transactions": [{
                "date": "2016-01-05 10:00:00",
                "type": "payment",
                "result": "successful"
            }]
        }]
    },
    function(err, res) {
        // asynchronously called
    });
<?php

// When a New Subscription is created
// a. Create the customer object if it doesn't already exist
$customer = ChartMogul\Customer::create([
            "data_source_uuid" => "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
            "external_id" => "cus_0002",
            "name" => "Alice",
            "email" => "[email protected]",
            "company" => "Acme inc."
        ]);

// b. Create the plan if it doesn't already exist
$plan = ChartMogul\Plan::create([
            "data_source_uuid" => "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
            "name" => "Gold Plan",
            "interval_count" => 1,
            "interval_unit" => "year"
        ]);

// c. Send invoice for the new subscription with customer and plan UUIDs
$line_item = new ChartMogul\LineItems\Subscription([
    "subscription_external_id" => "sub_0002",
    "plan_uuid" => $plan->uuid,
    "service_period_start" => "2016-01-01T00:00:00.000Z",
    "service_period_end" => "2017-01-01T00:00:00Z",
    "amount_in_cents" => 25000,
        ]);
$transaction = new ChartMogul\Transactions\Payment([
    "date" => "2016-01-05T10:00:00.000Z",
    "result" => "successful"
        ]);
$invoice = new ChartMogul\Invoice([
    "external_id" => "INV0003",
    "date" => "2016-01-01T00:00:00.000Z",
    "currency" => "USD",
    "line_items" => [$line_item],
    "transactions" => [$transaction]
        ]);
ChartMogul\CustomerInvoices::create([
    "customer_uuid" => "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
    "invoices" => [$invoice]
]);
?>
// When a New Subscription is created
// a. Create the customer object if it doesn't already exist
api.CreateCustomer(&cm.NewCustomer{
  DataSourceUUID: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  ExternalID:     "cus_0002",
  Name:           "Alice",
  Email:          "[email protected]",
  Company:        "Acme inc.",
})

// b. Create the plan if it doesn't already exist
api.CreatePlan(&cm.Plan{
  DataSourceUUID: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  Name:           "Gold Plan",
  IntervalCount:  1,
  IntervalUnit:   "year",
})

// c. Send invoice for the new subscription with customer and plan UUIDs
api.CreateInvoices([]*cm.Invoice{&cm.Invoice{
  ExternalID: "INV0003",
  Date:       "2016-01-01 00:00:00",
  Currency:   "USD",
  LineItems: []*cm.LineItem{&cm.LineItem{
    Type: "subscription",
    SubscriptionExternalID: "sub_0002",
    PlanUUID:               "pl_ab225d54-7ab4-421b-cdb2-eb6b9e553462",
    ServicePeriodStart:     "2016-01-01 00:00:00",
    ServicePeriodEnd:       "2017-01-01 00:00:00",
    AmountInCents:          25000,
  }},
  Transactions: []*cm.Transaction{
    &cm.Transaction{
      Date:   "2016-01-05 10:00:00",
      Type:   "payment",
      Result: "successful",
    }},
}}, "cus_ee325d54-7ab4-421b-cdb2-eb6b9e546034")
# When a New Subscription is created
# a. Create the customer object if it doesn't already exist
chartmogul.Customer.create(config, data={
    "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
    "external_id": "cus_0002",
    "name": "Alice",
    "email": "[email protected]",
    "company": "Acme inc."
}).then(lambda result: print(result)).get()

# b. Create the plan if it doesn't already exist
chartmogul.Plan.create(config, data={
    "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
    "name": "Gold Plan",
    "interval_count": 1,
    "interval_unit": "year"
}).then(lambda result: print(result)).get()

# c. Send invoice for the new subscription with customer and plan UUIDs
chartmogul.Invoice.create(
    config,
    uuid="cus_ee325d54-7ab4-421b-cdb2-eb6b9e546034",
    data={
        "invoices": [{
            "external_id": "INV0003",
            "date": "2016-01-01 00:00:00",
            "currency": "USD",
            "line_items": [{
                "type": "subscription",
                "subscription_external_id": "sub_0002",
                "plan_uuid": "pl_ab225d54-7ab4-421b-cdb2-eb6b9e553462",
                "service_period_start": "2016-01-01 00:00:00",
                "service_period_end": "2017-01-01 00:00:00",
                "amount_in_cents": 25000
            }],
            "transactions": [{
                "date": "2016-01-05 10:00:00",
                "type": "payment",
                "result": "successful"
            }]
        }]
    }).then(lambda result: print(result)).get()

When a Subscription is renewed

When a customer renews their subscription, send us the renewal Invoice using the endpoint to import customer's Invoices, and specify the unique subscription_external_id referencing the subscription that was renewed.

Retrieving Subscription External ID for referencing

In order to renew or alter an existing subscription, you must always send us the subscription_external_id with the new invoice.

You can use the endpoint to list a customer's Subscriptions for retrieving the subscription_external_id specified by you, the subscription_uuid generated by us, and other basic information for each subscription.

ChartMogul assumes good faith with respect to renewals

If you do not send renewal invoices for a subscription to ChartMogul, the calculated MRR for the subscription is continued to be reported as is. ChartMogul assumes good faith if renewal invoices are not received on time, and only alters a subscription's MRR and status based on explicit subscription data that you send.

However, we highly recommend that you send all renewal invoices and transactions to ChartMogul so that the Cash Flow metrics, which use transaction data, are kept up-to-date and relevant.

Failed transactions

You can also include failed transaction attempts for an Invoice to enable reporting on failed charges in ChartMogul.

# When a Subscription is renewed
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": "INV0004",
          "date": "2016-01-01 00:00:00",
          "currency": "USD",
          "line_items": [
            {
              "type": "subscription",
              "subscription_external_id": "sub_0001",
              "plan_uuid":"pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
              "service_period_start": "2016-01-01 00:00:00",
              "service_period_end": "2016-02-01 00:00:00",
              "amount_in_cents": 5000
            }
          ],
          "transactions": [
            {
              "date": "2016-01-05 10:00:00",
              "type": "payment",
              "result": "successful"
            }
          ]   
        }
       ]
}'
# When a Subscription is renewed
customer = ChartMogul::Customer.all(external_id:"cus_0001").first
plan = ChartMogul::Plan.all(external_id:"plan_0001").first

line_item_1 = ChartMogul::LineItems::Subscription.new(
  subscription_external_id: "sub_0001",
  plan_uuid: plan.uuid,
  service_period_start: Time.utc(2016, 1, 1),
  service_period_end: Time.utc(2016, 2, 1),
  amount_in_cents: 5000
)
transaction = ChartMogul::Transactions::Payment.new(
  date: Time.utc(2016, 1, 5, 10, 00, 00),
  result: 'successful'
)
invoice = ChartMogul::Invoice.new(
  external_id: 'INV0004',
  date: Time.utc(2016, 1, 1),
  currency: 'USD',
  line_items: [line_item_1],
  transactions: [transaction]
)

ChartMogul::CustomerInvoices.create!(customer_uuid: customer.uuid, invoices: [invoice])
// When a Subscription is renewed
ChartMogul.Invoice.create(config,
   "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
   {
     "invoices":[
       {
          "external_id": "INV0004",
          "date": "2016-01-01 00:00:00",
          "currency": "USD",
          "line_items": [
            {
              "type": "subscription",
              "subscription_external_id": "sub_0001",
              "plan_uuid":"pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
              "service_period_start": "2016-01-01 00:00:00",
              "service_period_end": "2016-02-01 00:00:00",
              "amount_in_cents": 5000
            }
          ],
          "transactions": [
            {
              "date": "2016-01-05 10:00:00",
              "type": "payment",
              "result": "successful"
            }
          ]   
       }
     ]
     },
   function (err, res) {
   // asynchronously called
});
<?php

// When a Subscription is renewed
$customer = ChartMogul\Customer::all(["external_id" => "cus_0001"])->first();
$plan = ChartMogul\Plan::all(["external_id" => "plan_0001"])->first();

$line_item_1 = new ChartMogul\LineItems\Subscription([
    "subscription_external_id" => "sub_0001",
    "plan_uuid" => $plan->uuid,
    "service_period_start" => "2016-01-01",
    "service_period_end" => "2016-02-01",
    "amount_in_cents" => 5000
        ]);

$transaction = new ChartMogul\Transactions\Payment([
    "date" => "2016-01-05",
    "result" => "successful"
        ]);

$invoice = new ChartMogul\Invoice([
    "external_id" => "INV0004",
    "date" => "2016-01-01",
    "currency" => "USD",
    "line_items" => [$line_item_1],
    "transactions" => [$transaction]
        ]);

ChartMogul\CustomerInvoices::create(["customer_uuid" => $customer->uuid, "invoices" => [$invoice]]);
?>
// When a Subscription is renewed
api.CreateInvoices([]*cm.Invoice{&cm.Invoice{
  ExternalID: "INV0004",
  Date:       "2016-01-01 00:00:00",
  Currency:   "USD",
  LineItems: []*cm.LineItem{
    &cm.LineItem{
      Type: "subscription",
      SubscriptionExternalID: "sub_0001",
      PlanUUID:               "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
      ServicePeriodStart:     "2016-01-01 00:00:00",
      ServicePeriodEnd:       "2016-02-01 00:00:00",
      AmountInCents:          5000,
    }},
  Transactions: []*cm.Transaction{
    &cm.Transaction{
      Date:   "2016-01-05 10:00:00",
      Type:   "payment",
      Result: "successful",
    }},
}}, "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7")
# When a Subscription is renewed
chartmogul.Invoice.create(
    config,
    uuid="cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
    data={
        "invoices": [
         {
             "external_id": "INV0004",
             "date": "2016-01-01 00:00:00",
             "currency": "USD",
             "line_items": [
                 {
                     "type": "subscription",
                     "subscription_external_id": "sub_0001",
                     "plan_uuid": "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
                     "service_period_start": "2016-01-01 00:00:00",
                     "service_period_end": "2016-02-01 00:00:00",
                     "amount_in_cents": 5000
                 }
             ],
             "transactions": [
                 {
                     "date": "2016-01-05 10:00:00",
                     "type": "payment",
                     "result": "successful"
                 }
             ]
         }
        ]
    }).then(lambda result: print(result)).get()

When a Subscription is changed

When a customer's subscription changes in any way, e.g. the plan changes, the price they pay increases or decreases, the discount amount changes, etc. simply keep the subscription_external_id the same and generate new invoices to send to ChartMogul.

If a subscription is changed at the end of a previously invoiced service period

Create a new invoice for the subsequent service period using the endpoint to import customer's Invoices, and specify the unique subscription_external_id referencing the subscription that was changed.

If a subscription is changed in the middle of a service period

Most businesses charge their customers a prorated amount for subscriptions that change in the middle of the subscription service period.

In this case, send us the Invoice using the endpoint to import customer's Invoices, with the attribute prorate set to true, and the prorated service_period_start and service_period_end timestamps, on the relevant subscription line item. The service period end date must match the end date of another invoice line item with the same subscription_external_id.

# When a Subscription is changed at the end of a previously invoiced service period. Eg. Customer switches their subscription from a Monthly to a Yearly plan

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": "INV0005",
          "date": "2016-02-01 00:00:00",
          "currency": "USD",
          "line_items": [
            {
              "type": "subscription",
              "subscription_external_id": "sub_0001",
              "plan_uuid":"pl_ab225d54-7ab4-421b-cdb2-eb6b9e553462",
              "service_period_start": "2016-02-01 00:00:00",
              "service_period_end": "2017-02-01 00:00:00",
              "amount_in_cents": 50000
            }
          ],
          "transactions": [
            {
              "date": "2016-01-05 10:00:00",
              "type": "payment",
              "result": "successful"
            }
          ]   
        }
       ]
}'

# Note that the plan_uuid and amount_in_cents have changed for the customer (Adam Smith)
# When a Subscription is changed at the end of a previously invoiced service period. Eg. Customer switches their subscription from a Monthly to a Yearly plan

customer = ChartMogul::Customer.all(external_id:"cus_0001").first
plan = ChartMogul::Plan.all(external_id:"plan_0002").first

line_item_1 = ChartMogul::LineItems::Subscription.new(
  subscription_external_id: "sub_0001",
  plan_uuid: plan.uuid,
  service_period_start: Time.utc(2016, 2, 1),
  service_period_end: Time.utc(2017, 2, 1),
  amount_in_cents: 50000
)
transaction = ChartMogul::Transactions::Payment.new(
  date: Time.utc(2016, 1, 5, 10, 00, 00),
  result: 'successful'
)
invoice = ChartMogul::Invoice.new(
  external_id: 'INV0005',
  date: Time.utc(2016, 2, 1),
  currency: 'USD',
  line_items: [line_item_1],
  transactions: [transaction]
)

ChartMogul::CustomerInvoices.create!(customer_uuid: customer.uuid, invoices: [invoice])

# Note that the plan_uuid and amount_in_cents have changed for the customer (Adam Smith)
// When a Subscription is changed at the end of a previously invoiced service period. Eg. Customer switches their subscription from a Monthly to a Yearly plan
ChartMogul.Invoice.create(config,
   "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
   {
     "invoices":[
       {
          "external_id": "INV0005",
          "date": "2016-02-01 00:00:00",
          "currency": "USD",
          "line_items": [
            {
              "type": "subscription",
              "subscription_external_id": "sub_0001",
              "plan_uuid":"pl_ab225d54-7ab4-421b-cdb2-eb6b9e553462",
              "service_period_start": "2016-02-01 00:00:00",
              "service_period_end": "2017-02-01 00:00:00",
              "amount_in_cents": 50000
            }
          ],
          "transactions": [
            {
              "date": "2016-01-05 10:00:00",
              "type": "payment",
              "result": "successful"
            }
          ]   
        }
       ]
     },
   function (err, res) {
   // asynchronously called
});

// Note that the plan_uuid and amount_in_cents have changed for the customer (Adam Smith)
<?php

// When a Subscription is changed at the end of a previously invoiced service period. Eg. Customer switches their subscription from a Monthly to a Yearly plan
$customer = ChartMogul\Customer::all(["external_id" => "cus_0001"])->first();
$plan = ChartMogul\Plan::all(["external_id" => "plan_0002"])->first();

$line_item_1 = new ChartMogul\LineItems\Subscription([
    "subscription_external_id" => "sub_0001",
    "plan_uuid" => $plan->uuid,
    "service_period_start" => "2016-02-01",
    "service_period_end" => "2017-02-01",
    "amount_in_cents" => 50000
        ]);

$transaction = new ChartMogul\Transactions\Payment([
    "date" => "2016-01-05",
    "result" => "successful"
        ]);

$invoice = new ChartMogul\Invoice([
    "external_id" => "INV0005",
    "date" => "2016-02-01",
    "currency" => "USD",
    "line_items" => [$line_item_1],
    "transactions" => [$transaction]
        ]);

ChartMogul\CustomerInvoices::create(["customer_uuid" => $customer->uuid, "invoices" => [$invoice]]);

// Note that the plan_uuid and amount_in_cents have changed for the customer (Adam Smith)
?>
	// When a Subscription is changed at the end of a previously invoiced
	// service period. Eg. Customer switches their subscription from a Monthly
	// to a Yearly plan
	api.CreateInvoices([]*cm.Invoice{&cm.Invoice{
		ExternalID: "INV0005",
		Date:       "2016-02-01 00:00:00",
		Currency:   "USD",
		LineItems: []*cm.LineItem{
			&cm.LineItem{
				Type:                   "subscription",
				SubscriptionExternalID: "sub_0001",
				PlanUUID:               "pl_ab225d54-7ab4-421b-cdb2-eb6b9e553462",
				ServicePeriodStart:     "2016-02-01 00:00:00",
				ServicePeriodEnd:       "2017-02-01 00:00:00",
				AmountInCents:          50000,
			}},
		Transactions: []*cm.Transaction{
			&cm.Transaction{
				Date:   "2016-01-05 10:00:00",
				Type:   "payment",
				Result: "successful",
			}},
	}}, "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7")

	// Note that the plan_uuid and amount_in_cents have changed for
	// the customer (Adam Smith)
# When a Subscription is changed at the end of a previously invoiced
# service period. Eg. Customer switches their subscription from a Monthly
# to a Yearly plan
chartmogul.Invoice.create(
    config,
    uuid="cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
    data={
        "invoices": [
         {
             "external_id": "INV0005",
             "date": "2016-02-01 00:00:00",
             "currency": "USD",
             "line_items": [
                 {
                     "type": "subscription",
                     "subscription_external_id": "sub_0001",
                     "plan_uuid": "pl_ab225d54-7ab4-421b-cdb2-eb6b9e553462",
                     "service_period_start": "2016-02-01 00:00:00",
                     "service_period_end": "2017-02-01 00:00:00",
                     "amount_in_cents": 50000
                 }
             ],
             "transactions": [
                 {
                     "date": "2016-01-05 10:00:00",
                     "type": "payment",
                     "result": "successful"
                 }
             ]
         }
        ]
    }).then(lambda result: print(result)).get()

# Note that the plan_uuid and amount_in_cents have changed for
# the customer (Adam Smith)

When a Subscription is cancelled

Use the endpoint to cancel a customer's Subscription, and set the cancelled_at timestamp for the subscription.

# When a Subscription is cancelled
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"
        }'
# When a Subscription is cancelled
customer = ChartMogul::Customer.all(external_id:"cus_0001").first
subscription = customer.subscriptions.last
subscription.cancel(Time.utc(2016, 1, 15))
// When a Subscription is cancelled
ChartMogul.Subscription.cancel(config, "sub_e6bc5407-e258-4de0-bb43-61faaf062035", { 
   "cancelled_at": "2016-01-15 00:00:00"
   }, function(err, res) {
   // asynchronously called
});
<?php

// When a Subscription is cancelled
$customer = ChartMogul\Customer::all(["external_id" => "cus_0001"])->first();
$subscription = $customer->subscriptions()->last();
$subscription->cancel("2016-01-15")
?>
// When a Subscription is cancelled
api.CancelSubscription("sub_e6bc5407-e258-4de0-bb43-61faaf062035",
	&cm.CancelSubscriptionParams{CancelledAt: "2016-01-15 00:00:00"})
# When a Subscription is cancelled
chartmogul.Subscription.cancel(
    config,
    uuid="sub_e6bc5407-e258-4de0-bb43-61faaf062035",
    data={
        "cancelled_at": datetime(2016, 1, 15, 0, 0, 0)
    }).then(lambda result: print(result)).get()

If this is a historical subscription that's already been cancelled you can include the cancellation date on the invoice instead of making a separate API call. For example, if a churned customer had renewed each month for 2 months and then cancelled their monthly subscription, you can include the cancellation date in the invoice that you send to us.

# When importing invoices for a cancelled Subscription
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
            }
          ],
          "transactions": [
            {
              "date": "2015-11-05 00:14:23",
              "type": "payment",
              "result": "successful"
            }
          ]   
       },
       {
          "external_id": "INV0002",
          "date": "2015-12-01 00:00:00",
          "currency": "USD",
          "due_date": "2015-12-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-12-01 00:00:00",
              "service_period_end": "2016-01-01 00:00:00",
              "amount_in_cents": 5000,
              "quantity": 1,
              "discount_code": "PSO86",
              "discount_amount_in_cents": 1000,
              "tax_amount_in_cents": 900,
              "cancelled_at": "2016-01-02 00:00:00"
            }
          ],
          "transactions": [
            {
              "date": "2015-12-05 07:54:02",
              "type": "payment",
              "result": "successful"
            }
          ]   
       }
     ]
     }'
# When importing invoices for a cancelled Subscription
customer = ChartMogul::Customer.all(external_id:"cus_0001").first
plan = ChartMogul::Plan.all(external_id:"plan_0001").first

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

line_item_2 = ChartMogul::LineItems::Subscription.new(
  subscription_external_id: "sub_0001",
  plan_uuid: plan.uuid,
  service_period_start: Time.utc(2015, 12, 1),
  service_period_end: Time.utc(2016, 1, 1),
  amount_in_cents: 5000,
  quantity: 1,
  discount_code: "PSO86",
  discount_amount_in_cents: 1000,
  tax_amount_in_cents: 900,
  cancelled_at: Time.utc(2016, 1, 2)
)
transaction_2 = ChartMogul::Transactions::Payment.new(
  date: Time.utc(2015, 12, 5, 7, 54, 02),
  result: 'successful'
)
invoice_2 = ChartMogul::Invoice.new(
  external_id: 'INV0002',
  date: Time.utc(2015, 12, 1),
  currency: 'USD',
  due_date: Time.utc(2015, 12, 15),
  line_items: [line_item_2],
  transactions: [transaction_2]
)

ChartMogul::CustomerInvoices.create!(customer_uuid: customer.uuid, invoices: [invoice_1, invoice_2])
// When importing invoices for a cancelled Subscription
ChartMogul.Invoice.create(config,
    "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7", {
        "invoices": [{
            "external_id": "INV0001",
            "date": "2015-11-01 00:00:00",
            "currency": "USD",
            "due_date": "2015-11-15 00:00:00",
            "line_items": [{
                "type": "subscription",
                "subscription_external_id": "sub_0001",
                "plan_uuid": "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
                "service_period_start": "2015-11-01 00:00:00",
                "service_period_end": "2015-12-01 00:00:00",
                "amount_in_cents": 5000,
                "quantity": 1,
                "discount_code": "PSO86",
                "discount_amount_in_cents": 1000,
                "tax_amount_in_cents": 900
            }],
            "transactions": [{
                "date": "2015-11-05 00:14:23",
                "type": "payment",
                "result": "successful"
            }]
        }, {
            "external_id": "INV0002",
            "date": "2015-12-01 00:00:00",
            "currency": "USD",
            "due_date": "2015-12-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-12-01 00:00:00",
                "service_period_end": "2016-01-01 00:00:00",
                "amount_in_cents": 5000,
                "quantity": 1,
                "discount_code": "PSO86",
                "discount_amount_in_cents": 1000,
                "tax_amount_in_cents": 900,
              	"cancelled_at": "2016-01-02 00:00:00"
            }],
            "transactions": [{
                "date": "2015-12-05 07:54:02",
                "type": "payment",
                "result": "successful"
            }]
        }]
    },
    function(err, res) {
        // asynchronously called
    });
<?php

// When importing invoices for a cancelled Subscription
$customer = ChartMogul\Customer::all(["external_id" => "cus_0001"])->first();
$plan = ChartMogul\Plan::all(["external_id" => "plan_0001"])->first();

$line_item_1 = new ChartMogul\LineItems\Subscription([
    "subscription_external_id" => "sub_0001",
    "plan_uuid" => $plan->uuid,
    "service_period_start" => "2015-11-01",
    "service_period_end" => "2015-12-01",
    "amount_in_cents" => 5000,
    "quantity" => 1,
    "discount_code" => "PSO86",
    "discount_amount_in_cents" => 1000,
    "tax_amount_in_cents" => 900
        ]);

$transaction_1 = new ChartMogul\Transactions\Payment([
    "date" => "2015-11-05",
    "result" => "successful"
        ]);

$invoice_1 = new ChartMogul\Invoice([
    "external_id" => "INV0001",
    "date" => "2015-11-01",
    "currency" => "USD",
    "due_date" => "2015-11-15",
    "line_items" => [$line_item_1],
    "transactions" => [$transaction_1]
        ]);

$line_item_2 = new ChartMogul\LineItems\Subscription([
    "subscription_external_id" => "sub_0001",
    "plan_uuid" => $plan->uuid,
    "service_period_start" => "2015-12-01",
    "service_period_end" => "2016-01-01",
    "amount_in_cents" => 5000,
    "quantity" => 1,
    "discount_code" => "PSO86",
    "discount_amount_in_cents" => 1000,
    "tax_amount_in_cents" => 900,
  	"cancelled_at" => "2016-01-02"
        ]);

$transaction_2 = new ChartMogul\Transactions\Payment([
    "date" => "2015-12-05",
    "result" => "successful"
        ]);

$invoice_2 = new ChartMogul\Invoice([
    "external_id" => "INV0002",
    "date" => "2015-12-01",
    "currency" => "USD",
    "due_date" => "2015-12-15",
    "line_items" => [$line_item_2],
    "transactions" => [$transaction_2]
        ]);

ChartMogul\CustomerInvoices::create([
    "customer_uuid" => $customer->uuid,
    "invoices" => [$invoice_1, $invoice_2]
]);
?>
// When importing invoices for a cancelled Subscription
lineItem1 := &cm.LineItem{
  SubscriptionExternalID: "sub_0001",
  PlanUUID:               "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
  ServicePeriodStart:     "2015-11-01 00:00:00",
  ServicePeriodEnd:       "2015-12-01 00:00:00",
  AmountInCents:          5000,
  Quantity:               1,
  DiscountCode:           "PSO86",
  DiscountAmountInCents:  1000,
  TaxAmountInCents:       900,
  Type:                   "subscription",
}
transaction1 := &cm.Transaction{
  Date:   "2015-11-05 00:14:23",
  Type:   "payment",
  Result: "successful",
}
invoice1 := &cm.Invoice{
  ExternalID:   "INV0001",
  Date:         "2015-11-01 00:00:00",
  Currency:     "USD",
  DueDate:      "2015-11-15 00:00:00",
  LineItems:    []*cm.LineItem{lineItem1},
  Transactions: []*cm.Transaction{transaction1},
}

lineItem2 := &cm.LineItem{
  SubscriptionExternalID: "sub_0001",
  PlanUUID:               "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
  ServicePeriodStart:     "2015-12-01 00:00:00",
  ServicePeriodEnd:       "2016-01-01 00:00:00",
  AmountInCents:          5000,
  Quantity:               1,
  DiscountCode:           "PSO86",
  DiscountAmountInCents:  1000,
  TaxAmountInCents:       900,
  Type:                   "subscription",
  CancelledAt:       			"2016-01-02 00:00:00"
}
transaction2 := &cm.Transaction{
  Date:   "2015-12-05 07:54:02",
  Type:   "payment",
  Result: "successful",
}
invoice2 := &cm.Invoice{
  ExternalID:   "INV0002",
  Date:         "2015-12-01 00:00:00",
  Currency:     "USD",
  DueDate:      "2015-12-15 00:00:00",
  LineItems:    []*cm.LineItem{lineItem2},
  Transactions: []*cm.Transaction{transaction2},
}

api.CreateInvoices([]*cm.Invoice{invoice1, invoice2},
                   "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7")
# When importing invoices for a cancelled Subscription
chartmogul.Invoice.create(
    config,
    uuid="cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
    data={
        "invoices": [{
            "external_id": "INV0001",
            "date": datetime(2015, 11, 1, 0, 0, 0),
            "currency": "USD",
            "due_date": datetime(2015, 11, 15, 0, 0, 0),
            "line_items": [{
                "type": "subscription",
                "subscription_external_id": "sub_0001",
                "plan_uuid": "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
                "service_period_start": datetime(2015, 11, 1, 0, 0, 0),
                "service_period_end": datetime(2015, 12, 1, 0, 0, 0),
                "amount_in_cents": 5000,
                "quantity": 1,
                "discount_code": "PSO86",
                "discount_amount_in_cents": 1000,
                "tax_amount_in_cents": 900
            }],
            "transactions": [{
                "date": datetime(2015, 11, 5, 0, 14, 23),
                "type": "payment",
                "result": "successful"
            }]
        }, {
            "external_id": "INV0002",
            "date": datetime(2015, 12, 1, 0, 0, 0),
            "currency": "USD",
            "due_date": datetime(2015, 12, 15, 0, 0, 0),
            "line_items": [{
                "type": "subscription",
                "subscription_external_id": "sub_0001",
                "plan_uuid": "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
                "service_period_start": datetime(2015, 12, 1, 0, 0, 0),
                "service_period_end": datetime(2016, 1, 1, 0, 0, 0),
                "amount_in_cents": 5000,
                "quantity": 1,
                "discount_code": "PSO86",
                "discount_amount_in_cents": 1000,
                "tax_amount_in_cents": 900,
            		"cancelled_at": datetime(2016, 1, 2, 0, 0, 0)
            }],
            "transactions": [{
                "date": datetime(2015, 12, 5, 7, 54, 2),
                "type": "payment",
                "result": "successful"
            }]
        }]
    }).then(lambda result: print(result)).get()

When a Subscription is re-activated

Upon successful payment for a re-activation, use the endpoint to import customer's Invoices, and specify the unique subscription_external_id referencing the previously cancelled subscription which was re-activated.

# When a Subscription is re-activated
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": "INV0005",
          "date": "2016-02-01 00:00:00",
          "currency": "USD",
          "line_items": [
            {
              "type": "subscription",
              "subscription_external_id": "sub_0001",
              "plan_uuid":"pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
              "service_period_start": "2016-02-01 00:00:00",
              "service_period_end": "2016-03-01 00:00:00",
              "amount_in_cents": 5000
            }
          ],
          "transactions": [
            {
              "date": "2016-02-05 10:00:00",
              "type": "payment",
              "result": "successful"
            }
          ]   
        }
       ]
}'
# Note that subscription with external_id `sub_0001` refers to a cancelled subscription from the previous step.
# When a Subscription is re-activated
customer = ChartMogul::Customer.all(external_id:"cus_0001").first
plan = ChartMogul::Plan.all(external_id:"plan_0001").first

line_item_1 = ChartMogul::LineItems::Subscription.new(
  subscription_external_id: "sub_0001",
  plan_uuid: plan.uuid,
  service_period_start: Time.utc(2016, 2, 1),
  service_period_end: Time.utc(2016, 3, 1),
  amount_in_cents: 5000
)
transaction = ChartMogul::Transactions::Payment.new(
  date: Time.utc(2016, 2, 5, 10, 00, 00),
  result: 'successful'
)
invoice = ChartMogul::Invoice.new(
  external_id: 'INV0005',
  date: Time.utc(2016, 2, 1),
  currency: 'USD',
  line_items: [line_item_1],
  transactions: [transaction]
)

ChartMogul::CustomerInvoices.create!(customer_uuid: customer.uuid, invoices: [invoice])

# Note that subscription with external_id `sub_0001` refers to a cancelled subscription from the previous step.
// When a Subscription is re-activated
ChartMogul.Invoice.create(config,
   "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
   {
     "invoices":[
       {
          "external_id": "INV0005",
          "date": "2016-02-01 00:00:00",
          "currency": "USD",
          "line_items": [
            {
              "type": "subscription",
              "subscription_external_id": "sub_0001",
              "plan_uuid":"pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
              "service_period_start": "2016-02-01 00:00:00",
              "service_period_end": "2016-03-01 00:00:00",
              "amount_in_cents": 5000
            }
          ],
          "transactions": [
            {
              "date": "2016-02-05 10:00:00",
              "type": "payment",
              "result": "successful"
            }
          ]   
        }
       ]
     },
   function (err, res) {
   // asynchronously called
});

// Note that subscription with external_id `sub_0001` refers to a cancelled subscription from the previous step.
<?php

// When a Subscription is re-activated
$customer = ChartMogul\Customer::all(["external_id" => "cus_0001"])->first();
$plan = ChartMogul\Plan::all(["external_id" => "plan_0001"])->first();

$line_item_1 = new ChartMogul\LineItems\Subscription([
    "subscription_external_id" => "sub_0001",
    "plan_uuid" => $plan->uuid,
    "service_period_start" => "2016-02-01",
    "service_period_end" => "2017-02-01",
    "amount_in_cents" => 50000
        ]);

$transaction = new ChartMogul\Transactions\Payment([
    "date" => "2016-02-05",
    "result" => "successful"
        ]);

$invoice = new ChartMogul\Invoice([
    "external_id" => "INV0005",
    "date" => "2016-02-01",
    "currency" => "USD",
    "line_items" => [$line_item_1],
    "transactions" => [$transaction]
        ]);

ChartMogul\CustomerInvoices::create(["customer_uuid" => $customer->uuid, "invoices" => [$invoice]]);
// Note that subscription with external_id `sub_0001` refers to a cancelled subscription from the previous step.
?>
// When a Subscription is re-activated
api.CreateInvoices([]*cm.Invoice{&cm.Invoice{
  ExternalID: "INV0005",
  Date:       "2016-02-01 00:00:00",
  Currency:   "USD",
  LineItems: []*cm.LineItem{
    &cm.LineItem{
      Type: 					"subscription",
      SubscriptionExternalID: "sub_0001",
      PlanUUID:               "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
      ServicePeriodStart:     "2016-02-01 00:00:00",
      ServicePeriodEnd:       "2016-03-01 00:00:00",
      AmountInCents:          5000,
    }},
  Transactions: []*cm.Transaction{
    &cm.Transaction{
      Date:   "2016-02-05 10:00:00",
      Type:   "payment",
      Result: "successful",
    }},
}}, "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7")

// Note that subscription with external_id `sub_0001`
// refers to a cancelled subscription from the previous step.
# When a Subscription is re-activated
chartmogul.Invoice.create(
    config,
    uuid="cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
    data={
        "invoices": [
         {
             "external_id": "INV0005",
             "date": "2016-02-01 00:00:00",
             "currency": "USD",
             "line_items": [
                 {
                     "type": "subscription",
                     "subscription_external_id": "sub_0001",
                     "plan_uuid": "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
                     "service_period_start": "2016-02-01 00:00:00",
                     "service_period_end": "2016-03-01 00:00:00",
                     "amount_in_cents": 5000
                 }
             ],
             "transactions": [
                 {
                     "date": "2016-02-05 10:00:00",
                     "type": "payment",
                     "result": "successful"
                 }
             ]
         }
        ]
    }).then(lambda result: print(result)).get()

# Note that subscription with external_id `sub_0001` refers to a cancelled
# subscription from the previous step.

Completed sync setup

Once you complete the above steps to automatically update ChartMogul when billing events happen in your system, the analytics in your ChartMogul account will stay updated in real-time.

Congratulations! Your integration with our Import API is now complete.

Getting started with the Import API

You can use the ChartMogul Import API to import your customer and billing data.