Back to ChartMogulAPI referenceGuides and tutorialsSupportContact

Getting started with the Import API

This tutorial describes how you can import billing data into your ChartMogul account, and keep your data in sync for real-time analytics.

Suggest Edits

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 creating a data source using the Create a Data Source endpoint. This will return a Data Source UUID for each data source that's created in ChartMogul. Save this UUID for use in subsequent API requests.

# 1. Create a Data Source
curl -X POST "https://api.chartmogul.com/v1/data_sources" \
     -u YOUR_API_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 via the UI

You can also create a data source by going to Data platform > Home, clicking on the Add a data source button, and choosing Custom data source as the system.

2. Create Customers

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

# 2. Create Customers
curl -X POST "https://api.chartmogul.com/v1/customers" \
     -u YOUR_API_KEY: \
     -H "Content-Type: application/json" \
     -d '{
          "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
          "external_id": "cus_0001",
          "name": "Adam Smith",
          "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()

📘

Creating a Customer via the UI

You can also create individual customers by going to Customers, clicking on the New Customer link, and choosing the Custom data source you want to add the customer to.

3. Create Plans

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

# 3. Create Subscription Plans
curl -X POST "https://api.chartmogul.com/v1/plans" \
     -u YOUR_API_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 via the UI

You can also create a plan by navigating to the Custom data source > Plans tab in Data platform > Home and click the "NEW PLAN" button at the top. Alternatively, you can create a plan by going to Admin > Plans, clicking on the New Plan button and choosing the Custom data source you want to add a plan to.

4. Send Invoices

Send all of your customers' invoices to ChartMogul using the Import Invoices endpoint.

🚧

Invoices are the crucial component

  • ChartMogul Invoice objects are explicitly designed for generating subscription analytics. We auto-generate subscriptions 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 can 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 invoices or transactions through the API. If you want to make changes to an invoice, you have to delete it first and import the invoice with updated data. Alternatively, you can navigate to the Custom data source in Data platform > Home and use the spreadsheet-style editor to make any corrections to invoices, line items or transactions.
# 4. Send Invoices
curl -X POST "https://api.chartmogul.com/v1/import/customers/cus_f466e33d-ff2b-4a11-8f85-417eb02157a7/invoices" \
     -u YOUR_API_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",
          "customer_external_id": "cus_0001",
          "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
          "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",
          "customer_external_id": "cus_0001",
          "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
          "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),
  customer_external_id: "cus_0001",
  data_source_uuid: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  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),
  customer_external_id: "cus_0001",
  data_source_uuid: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  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",
            "customer_external_id": "cus_0001",
            "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",

            "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",
            "customer_external_id": "cus_0001",
            "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",

            "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",
    "customer_external_id" => "cus_0001",
    "data_source_uuid" => "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
    "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",
    "customer_external_id" => "cus_0001",
    "data_source_uuid" => "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
    "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",
  CustomerExternalID: "cus_0001",
  DataSourceUUID: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  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",
  CustomerExternalID: "cus_0001",
  DataSourceUUID: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  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),
            "customer_external_id": "cus_0001",
            "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",

            "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),
            "customer_external_id": "cus_0001",
            "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",

            "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 List Customers and List Plans endpoints

👍

Completing your billing data import

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 ChartMogul in sync as new data is generated in your billing system.

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 record first using the Create a Customer endpoint.
  2. If the subscription plan that the customer purchased does not yet exist in ChartMogul, then create a new plan object using the Create a Plan endpoint.
  3. Send us an invoice for this new subscription using the Import Invoices endpoint.

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 Create a Plan endpoint.
  2. Send us an Invoice for the purchase using the Import Invoices endpoint.
# 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_API_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_API_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_API_KEY: \
     -H "Content-Type: application/json" \
     -d '{
     "invoices":[
       {
          "external_id": "INV0003",
          "date": "2016-01-01 00:00:00",
          "currency": "USD",
          "customer_external_id": "cus_0001",
          "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
          "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',
  customer_external_id: "cus_0001",
  data_source_uuid: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  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",
            "customer_external_id": "cus_0001",
            "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
            "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",
    "customer_external_id": "cus_0001",
    "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
    "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",
  CustomerExternalID: "cus_0001",
  DataSourceUUID: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  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",
            "customer_external_id": "cus_0001",
            "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
            "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 Import Invoices endpoint, and specify the unique subscription_external_id referencing the subscription that was renewed.

📘

Referencing the right subscriptions in invoices

Since customers can have multiple subscriptions, ChartMogul uses the subscription_external_id in invoices to identify the right subscription.

If a certain subscription_external_id specified in an invoice does not already exist in your ChartMogul account, then a new subscription will be generated with that ID. In order to renew or alter an existing subscription, you must send the correct subscription_external_id of the subscription in question with each invoice.

You can use the List Customer's Subscriptions endpoint at any time 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 status based on explicit requests that you send.

However, we highly recommend that you send all renewal invoices and transactions to ChartMogul so that the Cash Flow metrics, which are generated from 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_API_KEY: \
     -H "Content-Type: application/json" \
     -d '{
     "invoices":[
       {
          "external_id": "INV0004",
          "date": "2016-01-01 00:00:00",
          "currency": "USD",
          "customer_external_id": "cus_0001",
          "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
          "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',
  customer_external_id: "cus_0001",
  data_source_uuid: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  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",
          "customer_external_id": "cus_0001",
          "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
          "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",
    "customer_external_id": "cus_0001",
    "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
    "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",
  CustomerExternalID: "cus_0001",
  DataSourceUUID: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  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",
             "customer_external_id": "cus_0001",
             "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
             "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 Import Invoices endpoint, and specify the unique subscription_external_id referencing the subscription that was changed. If the plan was changed, then specify the UUID of the new plan as the plan_uuid in the invoice.

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 Import Invoices endpoint, 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_API_KEY: \
     -H "Content-Type: application/json" \
     -d '{
     "invoices":[
       {
          "external_id": "INV0005",
          "date": "2016-02-01 00:00:00",
          "currency": "USD",
          "customer_external_id": "cus_0001",
          "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
          "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',
  customer_external_id: "cus_0001",
  data_source_uuid: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  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",
          "customer_external_id": "cus_0001",
          "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
          "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",
    "customer_external_id": "cus_0001",
    "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
    "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",
    CustomerExternalID: "cus_0001",
    DataSourceUUID: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
        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",
             "customer_external_id": "cus_0001",
             "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
             "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)

For detailed instructions on how to support all the different use-cases of prorated billing, read this tutorial.

When a Subscription is cancelled

Use the Cancel a Subscription endpoint, 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_API_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 on 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_API_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",
          "customer_external_id": "cus_0001",
          "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",         
          "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",
          "customer_external_id": "cus_0001",
          "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
          "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),
  customer_external_id: "cus_0001",
  data_source_uuid: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  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),
  customer_external_id: "cus_0001",
  data_source_uuid: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  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",
            "customer_external_id": "cus_0001",
            "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
            "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",
            "customer_external_id": "cus_0001",
            "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
            "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",
    "customer_external_id": "cus_0001",
    "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
    "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",
    "customer_external_id": "cus_0001",
    "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
    "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", 
  CustomerExternalID: "cus_0001",
  DataSourceUUID: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  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", 
  CustomerExternalID: "cus_0001",
  DataSourceUUID: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  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),
            "customer_external_id": "cus_0001",
            "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
            "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),
            "customer_external_id": "cus_0001",
            "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
            "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 Import Invoices endpoint, 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_API_KEY: \
     -H "Content-Type: application/json" \
     -d '{
     "invoices":[
       {
          "external_id": "INV0005",
          "date": "2016-02-01 00:00:00",
          "currency": "USD",
          "customer_external_id": "cus_0001",
          "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
          "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',
  customer_external_id: "cus_0001",
  data_source_uuid: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  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",
          "customer_external_id": "cus_0001",
          "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
          "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",
    "customer_external_id": "cus_0001",
    "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
    "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",  
  CustomerExternalID: "cus_0001",
  DataSourceUUID: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  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",
             "customer_external_id": "cus_0001",
             "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
             "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.

📘

Support

Don't see your business use-case covered here? Got questions regarding the integration? Write to us at [email protected].

Updated 11 months ago