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 refunds using the Import API

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

Refunds and ChartMogul metrics

In ChartMogul, refunds contribute to the Net Cash Flow and Refunds charts. They do not contribute to MRR, Churn or LTV.

Please specify refunds as positive amounts in the API. The transaction type set to refund is what ChartMogul uses in order to process them correctly.

Example use case - Adding a refund from the past

While importing your historical billing data into ChartMogul, if you want to register a refund for a paid invoice, you can do so by creating an invoice with just a refund transaction.

Let's imagine that:

  • Your customer Alice bought an Annual Plan on January 1st, 2016 and paid $250.
  • She decided to cancel her subscription and requested a full refund within a few days.
  • You refunded the full amount of $250 on January 5th, 2016.

To add this, you must send us two invoice objects with a line_item of type subscription, the subscription_external_id, plan_uuid, service_period_start and service_period_end dates, and amount_in_cents of 25000. One invoice must have a transaction of type payment, and the other invoice must have a transaction of type refund.

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

  • ChartMogul UUID of Alice - cus_ee325d54-7ab4-421b-cdb2-eb6b9e546034
  • ChartMogul UUID of the Annual Plan - pl_ab225d54-7ab4-421b-cdb2-eb6b9e553462
  • Subscription external ID for this subscription - sub_0002
# Example for adding a refund from the past
curl -X POST "https://api.chartmogul.com/v1/import/customers/cus_ee325d54-7ab4-421b-cdb2-eb6b9e546034/invoices" \
     -u YOUR_ACCOUNT_TOKEN:YOUR_SECRET_KEY \
     -H "Content-Type: application/json" \
     -d '{
     "invoices":[
       {
          "external_id": "INV0004",
          "date": "2016-01-01 00:00:00",
          "currency": "USD",
          "line_items": [
            {
              "type": "subscription",
              "subscription_external_id": "sub_0002",
              "plan_uuid": "pl_ab225d54-7ab4-421b-cdb2-eb6b9e553462",
              "service_period_start": "2016-01-01 00:00:00",
              "service_period_end": "2017-01-01 00:00:00",
              "amount_in_cents": 25000
            }
          ],
          "transactions": [
            {
              "date": "2016-01-01 00:00:00",
              "type": "payment",
              "result": "successful"
            }
          ]   
       },
       {
          "external_id": "INV0005",
          "date": "2016-01-05 00:00:00",
          "currency": "USD",
          "line_items": [
            {
              "type": "subscription",
              "subscription_external_id": "sub_0002",
              "plan_uuid": "pl_ab225d54-7ab4-421b-cdb2-eb6b9e553462",
              "service_period_start": "2016-01-01 00:00:00",
              "service_period_end": "2017-01-01 00:00:00",
              "amount_in_cents": 25000
            }
          ],
          "transactions": [
            {
              "date": "2016-01-05 00:00:00",
              "type": "refund",
              "result": "successful"
            }
          ]   
       }
     ]
     }'
# Example for adding a refund from the past
line_item = ChartMogul::LineItems::Subscription.new(
  subscription_external_id: "sub_0002",
  plan_uuid: "pl_ab225d54-7ab4-421b-cdb2-eb6b9e553462",
  service_period_start: Time.utc(2016, 1, 1),
  service_period_end: Time.utc(2017, 1, 1),
  amount_in_cents: 25000
)
transaction_1 = ChartMogul::Transactions::Payment.new(
  date: Time.utc(2016, 1, 1),
  result: 'successful'
)
transaction_2 = ChartMogul::Transactions::Refund.new(
  date: Time.utc(2016, 1, 5),
  result: 'successful'
)
invoice_1 = ChartMogul::Invoice.new(
  external_id: 'INV0004',
  date: Time.utc(2016, 1, 1),
  currency: 'USD',
  line_items: [line_item],
  transactions: [transaction_1]
)
invoice_2 = ChartMogul::Invoice.new(
  external_id: 'INV0005',
  date: Time.utc(2016, 1, 5),
  currency: 'USD',
  line_items: [line_item],
  transactions: [transaction_2]
)

ChartMogul::CustomerInvoices.create!(customer_uuid: "cus_ee325d54-7ab4-421b-cdb2-eb6b9e546034", invoices: [invoice_1, invoice_2])
// Example for adding a refund from the past
ChartMogul.Invoice.create(config,
    "cus_ee325d54-7ab4-421b-cdb2-eb6b9e546034", {
        "invoices": [{
            "external_id": "INV0004",
            "date": "2016-01-01 00:00:00",
            "currency": "USD",
            "line_items": [{
                "type": "subscription",
                "subscription_external_id": "sub_0002",
                "plan_uuid": "pl_ab225d54-7ab4-421b-cdb2-eb6b9e553462",
                "service_period_start": "2016-01-01 00:00:00",
                "service_period_end": "2017-01-01 00:00:00",
                "amount_in_cents": 25000
            }],
            "transactions": [{
                "date": "2016-01-01 00:00:00",
                "type": "payment",
                "result": "successful"
            }]
        }, {
            "external_id": "INV0005",
            "date": "2016-01-05 00:00:00",
            "currency": "USD",
            "line_items": [{
                "type": "subscription",
                "subscription_external_id": "sub_0002",
                "plan_uuid": "pl_ab225d54-7ab4-421b-cdb2-eb6b9e553462",
                "service_period_start": "2016-01-01 00:00:00",
                "service_period_end": "2017-01-01 00:00:00",
                "amount_in_cents": 25000
            }],
            "transactions": [{
                "date": "2016-01-05 00:00:00",
                "type": "refund",
                "result": "successful"
            }]
        }]
    },
    function(err, res) {
        // asynchronously called
    });
<?php

// Example for adding a refund from the past
$line_item1 = new ChartMogul\LineItems\Subscription([
    'subscription_external_id' => "sub_0002",
    'plan_uuid' => 'pl_ab225d54-7ab4-421b-cdb2-eb6b9e553462',
    'prorated' => true,
    'service_period_start' => "2016-01-01T00:00:00Z",
    'service_period_end' => "2017-01-01T00:00:00Z",
    'amount_in_cents' => 25000
        ]);
$transaction1 = new ChartMogul\Transactions\Payment([
    "date" => "2016-01-01T00:00:00.000Z",
    "result" => "successful"
        ]);
$invoice1 = new ChartMogul\Invoice([
    "external_id" => "INV0004",
    "date" => "2016-01-01T00:00:00.000Z",
    "currency" => "USD",
    "line_items" => [$line_item1],
    "transactions" => [$transaction1]
        ]);

$line_item2 = new ChartMogul\LineItems\Subscription([
    'subscription_external_id' => "sub_0002",
    'plan_uuid' => 'pl_ab225d54-7ab4-421b-cdb2-eb6b9e553462',
    'prorated' => true,
    'service_period_start' => "2016-01-01T00:00:00Z",
    'service_period_end' => "2017-01-01T00:00:00Z",
    'amount_in_cents' => 25000
        ]);
$transaction2 = new ChartMogul\Transactions\Refund([
    "date" => "2016-01-05T00:00:00.000Z",
    "result" => "successful"
        ]);
$invoice2 = new ChartMogul\Invoice([
    "external_id" => "INV0001",
    "date" => "2016-01-05T00:00:00.000Z",
    "currency" => "USD",
    "line_items" => [$line_item2],
    "transactions" => [$transaction2]
        ]);

ChartMogul\CustomerInvoices::create([
    "customer_uuid" => "cus_ee325d54-7ab4-421b-cdb2-eb6b9e546034",
    "invoices" => [$invoice1, $invoice2]
]);
?>
// Example for adding a refund from the past
api.CreateInvoices(
  []*cm.Invoice{{
    ExternalID: "INV0004",
    Date:       "2016-01-01 00:00:00",
    Currency:   "USD",
    LineItems: []*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{{
        Date:   "2016-01-01 00:00:00",
        Type:   "payment",
        Result: "successful",
      }},
  }, {
    ExternalID: "INV0005",
    Date:       "2016-01-05 00:00:00",
    Currency:   "USD",
    LineItems: []*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{{
        Date:   "2016-01-05 00:00:00",
        Type:   "refund",
        Result: "successful",
      }},
  }}, "cus_ee325d54-7ab4-421b-cdb2-eb6b9e546034")
# Example for adding a refund from the past
chartmogul.Invoice.create(
config,
    uuid="cus_ee325d54-7ab4-421b-cdb2-eb6b9e546034",
    data={
        "invoices": [{
            "external_id": "INV0004",
            "date": "2016-01-01 00:00:00",
            "currency": "USD",
            "line_items": [{
                "type": "subscription",
                "subscription_external_id": "sub_0002",
                "plan_uuid": "pl_ab225d54-7ab4-421b-cdb2-eb6b9e553462",
                "service_period_start": "2016-01-01 00:00:00",
                "service_period_end": "2017-01-01 00:00:00",
                "amount_in_cents": 25000
            }],
            "transactions": [{
                "date": "2016-01-01 00:00:00",
                "type": "payment",
                "result": "successful"
            }]
        }, {
            "external_id": "INV0005",
            "date": "2016-01-05 00:00:00",
            "currency": "USD",
            "line_items": [{
                "type": "subscription",
                "subscription_external_id": "sub_0002",
                "plan_uuid": "pl_ab225d54-7ab4-421b-cdb2-eb6b9e553462",
                "service_period_start": "2016-01-01 00:00:00",
                "service_period_end": "2017-01-01 00:00:00",
                "amount_in_cents": 25000
            }],
            "transactions": [{
                "date": "2016-01-05 00:00:00",
                "type": "refund",
                "result": "successful"
            }]
        }]
    }).then(lambda result: print(result)).get()

Adding a past refund correctly

If specified correctly as demonstrated, this example will result in:

  • Gross Cash Flow and Net Cash Flow increasing by $250 on January 1st, 2016.
  • Net Cash Flow reducing by $250, and Refunds increasing by $250, on January 5th, 2016.

Example use case - Adding a refund in real-time

You can also generate and send invoices with only a refund transaction on a real-time basis.

Let's imagine that:

  • Your customer Adam bought a monthly subscription to the Bronze Plan on January 1st, 2016 and paid $50.
  • You send an invoice capturing this payment to ChartMogul.
  • Adam requests a refund on January 25th, 2016, and you grant a full refund on the same day.

To add this refund that happened on January 25th, you can send us an invoice with a line_item reflecting the original payment, and a transaction of type refund.

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 for adding a refund in real-time
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": "INV0006",
          "date": "2016-01-25 00:00:00",
          "currency": "USD",
          "line_items": [
            {
              "type": "subscription",
              "subscription_external_id": "sub_0001",
              "plan_uuid": "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
              "service_period_start": "2016-01-01 00:00:00",
              "service_period_end": "2016-02-01 00:00:00",
              "amount_in_cents": 5000
            }
          ],
          "transactions": [
            {
              "date": "2016-01-25 00:00:00",
              "type": "refund",
              "result": "successful"
            }
          ]   
       }
     ]
     }'
# Example for adding a refund in real-time
line_item = ChartMogul::LineItems::Subscription.new(
  subscription_external_id: "sub_0001",
  plan_uuid: "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
  service_period_start: Time.utc(2016, 1, 1),
  service_period_end: Time.utc(2016, 2, 1),
  amount_in_cents: 5000
)
transaction = ChartMogul::Transactions::Refund.new(
  date: Time.utc(2016, 1, 25),
  result: 'successful'
)
invoice = ChartMogul::Invoice.new(
  external_id: 'INV0006',
  date: Time.utc(2016, 1, 25),
  currency: 'USD',
  line_items: [line_item],
  transactions: [transaction]
)

ChartMogul::CustomerInvoices.create!(customer_uuid: "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7", invoices: [invoice])
// Example for adding a refund in real-time
ChartMogul.Invoice.create(config,
    "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7", {
        "invoices": [{
            "external_id": "INV0006",
            "date": "2016-01-25 00:00:00",
            "currency": "USD",
            "line_items": [{
                "type": "subscription",
                "subscription_external_id": "sub_0001",
                "plan_uuid": "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
                "service_period_start": "2016-01-01 00:00:00",
                "service_period_end": "2016-02-01 00:00:00",
                "amount_in_cents": 5000
            }],
            "transactions": [{
                "date": "2016-01-25 00:00:00",
                "type": "refund",
                "result": "successful"
            }]
        }]
    },
    function(err, res) {
        // asynchronously called
    });
<?php

// Example for adding a refund in real-time
$line_item = new ChartMogul\LineItems\Subscription([
    'subscription_external_id' => "sub_0001",
    'plan_uuid' => 'pl_eed05d54-75b4-431b-adb2-eb6b9e543206',
    'service_period_start' => "2016-01-01T00:00:00Z",
    'service_period_end' => "2017-02-01T00:00:00Z",
    'amount_in_cents' => 5000
        ]);

$transaction = new ChartMogul\Transactions\Refund([
    "date" => "2016-01-25T00:00:00.000Z",
    "result" => "successful"
        ]);

$invoice = new ChartMogul\Invoice([
    "external_id" => "INV0006",
    "date" => "2016-01-25T00:00:00.000Z",
    "currency" => "USD",
    "line_items" => [$line_item],
    "transactions" => [$transaction]
        ]);


ChartMogul\CustomerInvoices::create([
    "customer_uuid" => "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
    "invoices" => [$invoice]
]);
?>
// Example for adding a refund in real-time
api.CreateInvoices(
	[]*cm.Invoice{{
		ExternalID: "INV0006",
		Date:       "2016-01-25 00:00:00",
		Currency:   "USD",
		LineItems: []*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{{
				Date:   "2016-01-25 00:00:00",
				Type:   "refund",
				Result: "successful",
			}},
	}}, "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7")
# Example for adding a refund in real-time
chartmogul.Invoice.create(
    config,
    uuid="cus_f466e33d-ff2b-4a11-8f85-417eb02157a7", {
        "invoices": [{
            "external_id": "INV0006",
            "date": "2016-01-25 00:00:00",
            "currency": "USD",
            "line_items": [{
                "type": "subscription",
                "subscription_external_id": "sub_0001",
                "plan_uuid": "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
                "service_period_start": "2016-01-01 00:00:00",
                "service_period_end": "2016-02-01 00:00:00",
                "amount_in_cents": 5000
            }],
            "transactions": [{
                "date": "2016-01-25 00:00:00",
                "type": "refund",
                "result": "successful"
            }]
        }]
    }).then(lambda result: print(result)).get()

Adding a refund correctly in real-time

If specified correctly as demonstrated, this example will result in Net Cash Flow reducing by $50, and Refunds increasing by $50, on January 25th, 2016.

Example use case - Adding a partial refund

You can register a partial refund for a subscription that was paid earlier, by setting the amount_in_cents in the refund invoice to the amount that was refunded.

Taking the previous example, let's imagine that:

  • Your customer Adam bought a monthly subscription to the Bronze Plan on January 1st, 2016 and paid $50.
  • You send an invoice capturing this payment to ChartMogul.
  • Adam requests a refund on January 25th, 2016, and you grant a partial refund of $10 for the amount of time left unused, instead of a full refund.

To add this partial refund that happened on January 25th, you can send us an invoice with a line_item reflecting the original payment, the amount_in_cents set to the refund amount, and a transaction of type refund.

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 for adding a partial refund
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": "INV0006",
          "date": "2016-01-25 00:00:00",
          "currency": "USD",
          "line_items": [
            {
              "type": "subscription",
              "subscription_external_id": "sub_0001",
              "plan_uuid": "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
              "service_period_start": "2016-01-01 00:00:00",
              "service_period_end": "2016-02-01 00:00:00",
              "amount_in_cents": 1000
            }
          ],
          "transactions": [
            {
              "date": "2016-01-25 00:00:00",
              "type": "refund",
              "result": "successful"
            }
          ]   
       }
     ]
     }'
# Example for adding a partial refund
line_item = ChartMogul::LineItems::Subscription.new(
  subscription_external_id: "sub_0001",
  plan_uuid: "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
  service_period_start: Time.utc(2016, 1, 1),
  service_period_end: Time.utc(2016, 2, 1),
  amount_in_cents: 1000
)
transaction = ChartMogul::Transactions::Refund.new(
  date: Time.utc(2016, 1, 25),
  result: 'successful'
)
invoice = ChartMogul::Invoice.new(
  external_id: 'INV0006',
  date: Time.utc(2016, 1, 25),
  currency: 'USD',
  line_items: [line_item],
  transactions: [transaction]
)

ChartMogul::CustomerInvoices.create!(customer_uuid: "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7", invoices: [invoice])
// Example for adding a partial refund
ChartMogul.Invoice.create(config,
    "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7", {
        "invoices": [{
            "external_id": "INV0006",
            "date": "2016-01-25 00:00:00",
            "currency": "USD",
            "line_items": [{
                "type": "subscription",
                "subscription_external_id": "sub_0001",
                "plan_uuid": "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
                "service_period_start": "2016-01-01 00:00:00",
                "service_period_end": "2016-02-01 00:00:00",
                "amount_in_cents": 1000
            }],
            "transactions": [{
                "date": "2016-01-25 00:00:00",
                "type": "refund",
                "result": "successful"
            }]
        }]
    },
    function(err, res) {
        // asynchronously called
    });
<?php

// Example for adding a partial refund
$line_item = new ChartMogul\LineItems\Subscription([
    'subscription_external_id' => "sub_0001",
    'plan_uuid' => 'pl_eed05d54-75b4-431b-adb2-eb6b9e543206',
    'service_period_start' => "2016-01-01T00:00:00Z",
    'service_period_end' => "2017-02-01T00:00:00Z",
    'amount_in_cents' => 1000
        ]);

$transaction = new ChartMogul\Transactions\Refund([
    "date" => "2016-01-25T00:00:00.000Z",
    "result" => "successful"
        ]);

$invoice = new ChartMogul\Invoice([
    "external_id" => "INV0006",
    "date" => "2016-01-25T00:00:00.000Z",
    "currency" => "USD",
    "line_items" => [$line_item],
    "transactions" => [$transaction]
        ]);

ChartMogul\CustomerInvoices::create([
    "customer_uuid" => "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
    "invoices" => [$invoice]
]);
?>
// Example for adding a partial refund
api.CreateInvoices(
  []*cm.Invoice{{
    ExternalID: "INV0006",
    Date:       "2016-01-25 00:00:00",
    Currency:   "USD",
    LineItems: []*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:          1000,
      }},
    Transactions: []*cm.Transaction{{
        Date:   "2016-01-25 00:00:00",
        Type:   "refund",
        Result: "successful",
      }},
  }}, "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7")
# Example for adding a partial refund
chartmogul.Invoice.create(
    config,
    uuid="cus_f466e33d-ff2b-4a11-8f85-417eb02157a7", {
        "invoices": [{
            "external_id": "INV0006",
            "date": "2016-01-25 00:00:00",
            "currency": "USD",
            "line_items": [{
                "type": "subscription",
                "subscription_external_id": "sub_0001",
                "plan_uuid": "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
                "service_period_start": "2016-01-01 00:00:00",
                "service_period_end": "2016-02-01 00:00:00",
                "amount_in_cents": 1000
            }],
            "transactions": [{
                "date": "2016-01-25 00:00:00",
                "type": "refund",
                "result": "successful"
            }]
        }]
    }).then(lambda result: print(result)).get()

Adding a partial refund correctly

If specified correctly as demonstrated, this example will result in Net Cash Flow reducing by $10, and Refunds increasing by $10, on January 25th, 2016.

Adding refund transactions to existing invoice objects in ChartMogul

You can also concatenate a transaction object of type refund to an invoice already imported into ChartMogul, by using the endpoint to import an invoice transaction. However, we do not recommend this approach as it is not best practice and does not support partial refunds.