ChartMogul Developer Hub

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

Get Started    

Adding pro-rated invoices using the Import API

This tutorial describes how you can add prorated charges using the ChartMogul Import API.

When a subscription is altered in the middle of a service period, many businesses charge their customers a prorated amount for the remainder of the service period. ChartMogul supports this use case with a flag on a subscription line item called prorated. This flag can be set to true to indicate a prorated charge.

Prorations and ChartMogul metrics

Prorations need to be communicated correctly to ChartMogul, for us to calculate MRR metrics accurately. If the prorated flag is not set when it should be, then it will result in MRR values that are not representative of your true revenue.

Example use case - Prorated charge for an additional subscription

Let's imagine that:

  • Your customer Adam Smith bought a monthly subscription to the Bronze Plan on January 1st, 2016 and paid $50.
  • Adam then upgraded his subscription by subscribing to another Bronze Plan on March 16th.
  • You charged him a prorated amount of $25 for the additional subscription for the remaining service period ending March 31st.

To add this prorated charge, you must send us an invoice containing a line_item of type subscription, with the subscription_external_id, plan_uuid, prorated set to true, the prorated service_period_start and service_period_end timestamps, the amount_in_cents, and the quantity set to 1.

Note - For the purposes of this example, we are using the following UUIDs,

  • ChartMogul UUID of Adam Smith - cus_f466e33d-ff2b-4a11-8f85-417eb02157a7
  • ChartMogul UUID of the Bronze Plan - pl_eed05d54-75b4-431b-adb2-eb6b9e543206
  • Subscription external ID for this subscription - sub_0001
# Example of a prorated charge for an additional 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": "INV0004",
          "date": "2016-03-16 00:00:00",
          "currency": "USD",
          "line_items": [
            {
              "type": "subscription",
              "subscription_external_id": "sub_0001",
              "plan_uuid":"pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
              "prorated": true,
              "service_period_start": "2016-03-16 12:00:00",
              "service_period_end": "2016-04-01 00:00:00",
              "amount_in_cents": 2500,
              "quantity": 1
            }
          ],
          "transactions": [
            {
              "date": "2016-03-17 10:00:00",
              "type": "payment",
              "result": "successful"
            }
          ]   
        }
       ]
}'
# Example of a prorated charge for an additional subscription
line_item = ChartMogul::LineItems::Subscription.new(
  subscription_external_id: "sub_0001",
  plan_uuid: "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
  prorated: true,
  service_period_start: Time.utc(2016, 3, 16, 12, 00, 00),
  service_period_end: Time.utc(2016, 4, 1),
  amount_in_cents: 2500,
  quantity: 1
)
transaction = ChartMogul::Transactions::Payment.new(
  date: Time.utc(2015, 3, 17, 10, 00, 00),
  result: 'successful'
)
invoice = ChartMogul::Invoice.new(
  external_id: 'INV0004',
  date: Time.utc(2016, 3, 16),
  currency: 'USD',
  line_items: [line_item],
  transactions: [transaction]
)

ChartMogul::CustomerInvoices.create!(customer_uuid: "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7", invoices: [invoice])
// Example of a prorated charge for an additional subscription
ChartMogul.Invoice.create(config,
    "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7", {
        "invoices": [{
            "external_id": "INV0004",
            "date": "2016-03-16 00:00:00",
            "currency": "USD",
            "line_items": [{
                "type": "subscription",
                "subscription_external_id": "sub_0001",
                "plan_uuid": "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
                "prorated": true,
                "service_period_start": "2016-03-16 12:00:00",
                "service_period_end": "2016-04-01 00:00:00",
                "amount_in_cents": 2500,
                "quantity": 1
            }],
            "transactions": [{
                "date": "2016-03-17 10:00:00",
                "type": "payment",
                "result": "successful"
            }]
        }]
    },
    function(err, res) {
        // asynchronously called
    });
<?php

// Example of a prorated charge for an additional subscription
$line_item = new ChartMogul\LineItems\Subscription([
    "subscription_external_id" => "sub_0001",
    "plan_uuid" => "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
    "prorated" => true,
    "service_period_start" => "2016-03-16",
    "service_period_end" => "2016-04-01",
    "amount_in_cents" => 2500,
    "quantity" => 1
        ]);

$transaction = new ChartMogul\Transactions\Payment([
    "date" => "2015-03-17",
    "result" => "successful"
        ]);

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

ChartMogul\CustomerInvoices::create(["customer_uuid" => "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7", "invoices" => [$invoice]])
?>
// Example of a prorated charge for an additional subscription
api.CreateInvoices([]*cm.Invoice{{
  ExternalID: "INV0004",
  Date:       "2016-03-16 00:00:00",
  Currency:   "USD",
  LineItems: []*cm.LineItem{{
      Type: 					"subscription",
      SubscriptionExternalID: "sub_0001",
      PlanUUID:               "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
      Prorated:               true,
      ServicePeriodStart:     "2016-03-16 12:00:00",
      ServicePeriodEnd:       "2016-04-01 00:00:00",
      AmountInCents:          2500,
      Quantity:               1,
    }},
  Transactions: []*cm.Transaction{{
      Date:   "2016-03-17 10:00:00",
      Type:   "payment",
      Result: "successful",
    }},
}}, "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7")
# Example of a prorated charge for an additional subscription
chartmogul.Invoice.create(
    config,
    uuid="cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
    data={
        "invoices": [{
            "external_id": "INV0004",
            "date": "2016-03-16 00:00:00",
            "currency": "USD",
            "line_items": [{
                "type": "subscription",
                "subscription_external_id": "sub_0001",
                "plan_uuid": "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
                "prorated": True,
                "service_period_start": "2016-03-16 12:00:00",
                "service_period_end": "2016-04-01 00:00:00",
                "amount_in_cents": 2500,
                "quantity": 1
            }],
            "transactions": [{
                "date": "2016-03-17 10:00:00",
                "type": "payment",
                "result": "successful"
            }]
        }]
    }).then(lambda result: print(result)).get()

Prorations specified correctly

If specified correctly as demonstrated, this example prorated charge will result in the MRR for Adam Smith expanding by $50, from $50 to $100 MRR on March 16th.

Example use case - Prorated charge with plan change

Let's imagine that:

  • Your customer Adam Smith bought a monthly subscription to the Bronze Plan on January 1st, 2016 and paid $50.
  • Adam then changed his plan to the Copper Plan, which costs $60 a month, on March 16th.
  • You invoice Adam a prorated amount of $30 for the Copper Plan until end of March, and credit him a prorated amount of $25 for the unused time on the Bronze Plan.
  • He pays the difference of $5 for the remaining service period ending March 31st.

To add this prorated charge, you must send us an invoice containing two line_items of type subscription. Both must have the same subscription_external_id, the same prorated service_period_start and service_period_end timestamps, and prorated set to true. One line item will have the plan_uuid, amount_in_cents and quantity for the original plan. The other will have the plan_uuid,amount_in_cents and quantity for the new plan.

Note - For the purposes of this example, we are using the following UUIDs,

  • ChartMogul UUID of Adam Smith - cus_f466e33d-ff2b-4a11-8f85-417eb02157a7
  • ChartMogul UUID of the Bronze Plan - pl_eed05d54-75b4-431b-adb2-eb6b9e543206
  • ChartMogul UUID of the Copper Plan - pl_b2cc1314-9e4b-4437-8056-c4b79294b8bb
  • Subscription external ID for this subscription - sub_0001
# Example of a prorated charge with plan change
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-03-16 00:00:00",
          "currency": "USD",
          "line_items": [
            {
              "type": "subscription",
              "subscription_external_id": "sub_0001",
              "plan_uuid":"pl_b2cc1314-9e4b-4437-8056-c4b79294b8bb",
              "prorated": true,
              "service_period_start": "2016-03-16 12:00:00",
              "service_period_end": "2016-04-01 00:00:00",
              "amount_in_cents": 3000,
              "quantity": 1
            },
            {
              "type": "subscription",
              "subscription_external_id": "sub_0001",
              "plan_uuid":"pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
              "prorated": true,
              "service_period_start": "2016-03-16 12:00:00",
              "service_period_end": "2016-04-01 00:00:00",
              "amount_in_cents": -2500,
              "quantity": 1
            }
          ],
          "transactions": [
            {
              "date": "2016-03-17 10:00:00",
              "type": "payment",
              "result": "successful"
            }
          ]   
        }
       ]
}'
# Example of a prorated charge with plan change
line_item_1 = ChartMogul::LineItems::Subscription.new(
  subscription_external_id: "sub_0001",
  plan_uuid: "pl_b2cc1314-9e4b-4437-8056-c4b79294b8bb",
  prorated: true,
  service_period_start: Time.utc(2016, 3, 16, 12, 00, 00),
  service_period_end: Time.utc(2016, 4, 1),
  amount_in_cents: 3000,
  quantity: 1
)
line_item_2 = ChartMogul::LineItems::Subscription.new(
  subscription_external_id: "sub_0001",
  plan_uuid: "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
  prorated: true,
  service_period_start: Time.utc(2016, 3, 16, 12, 00, 00),
  service_period_end: Time.utc(2016, 4, 1),
  amount_in_cents: -2500,
  quantity: 1
)
transaction = ChartMogul::Transactions::Payment.new(
  date: Time.utc(2015, 3, 17, 10, 00, 00),
  result: 'successful'
)
invoice = ChartMogul::Invoice.new(
  external_id: 'INV0004',
  date: Time.utc(2016, 3, 16, 00, 00, 00),
  currency: 'USD',
  line_items: [line_item_1, line_item_2],
  transactions: [transaction]
)

ChartMogul::CustomerInvoices.create!(customer_uuid: "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7", invoices: [invoice])
// Example of a prorated charge with plan change
ChartMogul.Invoice.create(config,
    "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7", {
        "invoices": [{
            "external_id": "INV0004",
            "date": "2016-03-16 00:00:00",
            "currency": "USD",
            "line_items": [{
                "type": "subscription",
                "subscription_external_id": "sub_0001",
                "plan_uuid": "pl_b2cc1314-9e4b-4437-8056-c4b79294b8bb",
                "prorated": true,
                "service_period_start": "2016-03-16 12:00:00",
                "service_period_end": "2016-04-01 00:00:00",
                "amount_in_cents": 3000,
                "quantity": 1
            }, {
                "type": "subscription",
                "subscription_external_id": "sub_0001",
                "plan_uuid": "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
                "prorated": true,
                "service_period_start": "2016-03-16 12:00:00",
                "service_period_end": "2016-04-01 00:00:00",
                "amount_in_cents": -2500,
                "quantity": 1
            }],
            "transactions": [{
                "date": "2016-03-17 10:00:00",
                "type": "payment",
                "result": "successful"
            }]
        }]
    },
    function(err, res) {
        // asynchronously called
    });
<?php

// Example of a prorated charge with plan change
$line_item_1 = new ChartMogul\LineItems\Subscription([
    "subscription_external_id" => "sub_0001",
    "plan_uuid" => "pl_b2cc1314-9e4b-4437-8056-c4b79294b8bb",
    "prorated" => true,
    "service_period_start" => "2016-03-16T12:00:00.000Z",
    "service_period_end" => "2016-04-01T00:00:00.000Z",
    "amount_in_cents" => 3000,
    "quantity" => 1
        ]);

$line_item_2 = new ChartMogul\LineItems\Subscription([
    "subscription_external_id" => "sub_0001",
    "plan_uuid" => "pl_b2cc1314-9e4b-4437-8056-c4b79294b8bb",
    "prorated" => true,
    "service_period_start" => "2016-03-16T12:00:00.000Z",
    "service_period_end" => "2016-04-01T00:00:00.000Z",
    "amount_in_cents" => -2500,
    "quantity" => 1
        ]);

$transaction = new ChartMogul\Transactions\Payment([
    "date" => "2016-03-17T10:00:00.000Z",
    "result" => "successful"
        ]);

$invoice = new ChartMogul\Invoice([
    "external_id" => "INV0004",
    "date" => "2016-03-16T00:00:00.000Z",
    "currency" => "USD",
    "line_items" => [$line_item_1, $line_item_2],
    "transactions" => [$transaction]
        ]);

ChartMogul\CustomerInvoices::create([
    "customer_uuid" => "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
    "invoices" => [$invoice]
]);
?>
// Example of a prorated charge with plan change
api.CreateInvoices([]*cm.Invoice{{
  ExternalID: "INV0004",
  Date:       "2016-03-16 00:00:00",
  Currency:   "USD",
  LineItems: []*cm.LineItem{{
      Type:                   "subscription",
      SubscriptionExternalID: "sub_0001",
      PlanUUID:               "pl_b2cc1314-9e4b-4437-8056-c4b79294b8bb",
      Prorated:               true,
      ServicePeriodStart:     "2016-03-16 12:00:00",
      ServicePeriodEnd:       "2016-04-01 00:00:00",
      AmountInCents:          3000,
      Quantity:               1,
    }, {
      Type:                   "subscription",
      SubscriptionExternalID: "sub_0001",
      PlanUUID:               "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
      Prorated:               true,
      ServicePeriodStart:     "2016-03-16 12:00:00",
      ServicePeriodEnd:       "2016-04-01 00:00:00",
      AmountInCents:          -2500,
      Quantity:               1,
    }},
  Transactions: []*cm.Transaction{{
      Date:   "2016-03-17 10:00:00",
      Type:   "payment",
      Result: "successful",
    }},
}}, "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7")
# Example of a prorated charge with plan change
chartmogul.Invoice.create(
    config,
    uuid="cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
    data={
        "invoices": [{
            "external_id": "INV0004",
            "date": "2016-03-16 00:00:00",
            "currency": "USD",
            "line_items": [{
                "type": "subscription",
                "subscription_external_id": "sub_0001",
                "plan_uuid": "pl_b2cc1314-9e4b-4437-8056-c4b79294b8bb",
                "prorated": True,
                "service_period_start": "2016-03-16 12:00:00",
                "service_period_end": "2016-04-01 00:00:00",
                "amount_in_cents": 3000,
                "quantity": 1
            }, {
                "type": "subscription",
                "subscription_external_id": "sub_0001",
                "plan_uuid": "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
                "prorated": True,
                "service_period_start": "2016-03-16 12:00:00",
                "service_period_end": "2016-04-01 00:00:00",
                "amount_in_cents": -2500,
                "quantity": 1
            }],
            "transactions": [{
                "date": "2016-03-17 10:00:00",
                "type": "payment",
                "result": "successful"
            }]
        }]
    }).then(lambda result: print(result)).get()

Credit for unused service

As you can see in the example, you can send a credit line_item to ChartMogul by specifying a negative value for amount_in_cents. In this case, the Bronze Plan and the unused service period are also referenced in the line_item object. Discount and tax amounts for credit items are not required and can be left out.

Prorations specified correctly

If specified correctly as demonstrated, this example prorated charge will result in the MRR for Adam Smith expanding by $10, from $50 to $60 MRR on March 16th. The transaction will contribute $5 to the Gross Cash Flow and Net Cash Flow on March 17th.

Example use case - Prorated downgrade with reduction in subscription quantity

Let's imagine that:

  • Your customer Adam Smith bought an annual subscription to the Gold Plan on January 1st, 2015 and paid $200 for 20 seats.
  • Adam decided to reduce the number of seats midway through his annual subscription to 10, on July 1st.
  • You gave Adam a prorated amount of $50 for the unused time on the Gold Plan for 10 seats, as credit.

To add this prorated credit and register the downgrade in ChartMogul, you must send us an invoice with a line_item of type subscription, reference the correct subscription_external_id, the service_period_start and service_period_end timestamps for the unused time, a negative amount_in_cents indicating the credit amount, a negative quantity indicating the reduction in seats, and prorated set to true. Since no payment or refund is made, we will expect no transactions for this invoice.

Note - For the purposes of this example, we are using the following UUIDs,

  • ChartMogul UUID of Adam Smith - cus_f466e33d-ff2b-4a11-8f85-417eb02157a7
  • ChartMogul UUID of the Gold Plan - pl_ab225d54-7ab4-421b-cdb2-eb6b9e553462
  • Subscription external ID for this subscription - sub_0001
# Example of a prorated downgrade with reduction in subscription quantity
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": "INV0037",
          "date": "2015-07-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": "2015-07-01 00:00:00",
              "service_period_end": "2016-01-01 00:00:00",
              "amount_in_cents": -5000,
              "quantity": -10,
              "prorated": true
            }
          ]  
       }
     ]
}'
# Example of a prorated downgrade with reduction in subscription quantity
line_item = ChartMogul::LineItems::Subscription.new(
  subscription_external_id: "sub_0001",
  plan_uuid: "pl_ab225d54-7ab4-421b-cdb2-eb6b9e553462",
  prorated: true,
  service_period_start: Time.utc(2015, 7, 1),
  service_period_end: Time.utc(2016, 1, 1),
  amount_in_cents: -5000,
  quantity: -10
)
invoice = ChartMogul::Invoice.new(
  external_id: 'INV0037',
  date: Time.utc(2015, 7, 1),
  currency: 'USD',
  line_items: [line_item],
  transactions: [transaction]
)

ChartMogul::CustomerInvoices.create!(customer_uuid: "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7", invoices: [invoice])
// Example of a prorated downgrade with reduction in subscription quantity
ChartMogul.Invoice.create(config,
    "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7", {
        "invoices": [{
            "external_id": "INV0037",
            "date": "2015-07-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": "2015-07-01 00:00:00",
                "service_period_end": "2016-01-01 00:00:00",
                "amount_in_cents": -5000,
                "quantity": -10,
                "prorated": true
            }]
        }]
    },
    function(err, res) {
        // asynchronously called
    });
<?php

// Example of a prorated downgrade with reduction in subscription quantity
$line_item = new ChartMogul\LineItems\Subscription([
    "subscription_external_id" => "sub_0001",
    "plan_uuid" => "pl_ab225d54-7ab4-421b-cdb2-eb6b9e553462",
    "prorated" => true,
    "service_period_start" => "2015-07-01T00:00:00.000Z",
    "service_period_end" => "2016-01-01T00:00:00Z",
    "amount_in_cents" => -5000,
    "quantity" => -10
        ]);

$invoice = new ChartMogul\Invoice([
    "external_id" => "INV0037",
    "date" => "2015-07-01T00:00:00.000Z",
    "currency" => "USD",
    "line_items" => [$line_item]
        ]);

ChartMogul\CustomerInvoices::create([
    "customer_uuid" => "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
    "invoices" => [$invoice]
]);
?>
// Example of a prorated downgrade with reduction in subscription quantity
api.CreateInvoices([]*cm.Invoice{{
  ExternalID: "INV0037",
  Date:       "2015-07-01 00:00:00",
  Currency:   "USD",
  LineItems: []*cm.LineItem{{
      Type:					"subscription",
      SubscriptionExternalID: "sub_0001",
      PlanUUID:               "pl_ab225d54-7ab4-421b-cdb2-eb6b9e553462",
      ServicePeriodStart:     "2015-07-01 00:00:00",
      ServicePeriodEnd:       "2016-01-01 00:00:00",
      AmountInCents:          -5000,
      Quantity:               -10,
      Prorated:               true,
    }},
}}, "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7")
# Example of a prorated downgrade with reduction in subscription quantity
chartmogul.Invoice.create(
    config,
    uuid="cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
    data={
        "invoices": [{
            "external_id": "INV0037",
            "date": "2015-07-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": "2015-07-01 00:00:00",
                "service_period_end": "2016-01-01 00:00:00",
                "amount_in_cents": -5000,
                "quantity": -10,
                "prorated": True
            }]
        }]
    }).then(lambda result: print(result)).get()

Prorations specified correctly

If specified correctly as demonstrated, this example prorated credit will result in the MRR for Adam Smith contracting by $8.27, from $16.67 to $8.40 MRR on July 1st.

Adding pro-rated invoices using the Import API

This tutorial describes how you can add prorated charges using the ChartMogul Import API.