Adding a non-recurring payment using the Import API

This tutorial describes how you can register a one-time or non-recurring payment using the ChartMogul Import API.

📘

One-time payments and ChartMogul metrics

In ChartMogul, one-time payments contribute towards Gross Cash Flow, Net Cash flow and Non-Recurring Cash Flow charts. They do not contribute to MRR, Churn or LTV metrics.

Example use case

Let's imagine that:

  • You charged your customer Adam Smith a one-time consultation fee of $25 on November 1st, 2015.
  • Adam successfully paid for it on November 5th, 2015.

To add this, you must send us an invoice with a line_item of type one_time, an amount_in_cents of 2500, and a transaction with successful payment on November 5th, 2015.

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

  • ChartMogul UUID of Adam Smith - cus_f466e33d-ff2b-4a11-8f85-417eb02157a7
# Example for registering a one time payment
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",
          "customer_external_id": "cus_0001",
          "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
          "line_items": [
            {
              "type": "one_time",
              "description": "Consultation Fees",
              "amount_in_cents": 2500,
              "quantity": 1
            }
          ],
          "transactions": [
            {
              "date": "2015-11-05 00:14:23",
              "type": "payment",
              "result": "successful"
            }
          ]   
       }
     ]
     }'
# Example for registering a one time payment
line_item = ChartMogul::LineItems::OneTime.new(
  description: "Consultation Fees",
  amount_in_cents: 2500,
  quantity: 1
)
transaction = ChartMogul::Transactions::Payment.new(
  date: Time.utc(2015, 11, 5, 0, 14, 23),
  result: 'successful'
)
invoice = ChartMogul::Invoice.new(
  external_id: 'INV0001',
  date: Time.utc(2015, 11, 1),
  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])
// Example for registering a one time payment
ChartMogul.Invoice.create(config,
    "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7", {
        "invoices": [{
            "external_id": "INV0001",
            "date": "2015-11-01 00:00:00",
            "currency": "USD",
            "customer_external_id": "cus_0001",
            "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
            "line_items": [{
                "type": "one_time",
                "description": "Consultation Fees",
                "amount_in_cents": 2500,
                "quantity": 1
            }],
            "transactions": [{
                "date": "2015-11-05 00:14:23",
                "type": "payment",
                "result": "successful"
            }]
        }]
    },
    function(err, res) {
        // asynchronously called
    });
<?php

// Example of a prorated downgrade with reduction in subscription quantity
$line_item = new ChartMogul\LineItems\OneTime([
    "description" => "Consultation Fees",
    "amount_in_cents" => 2500,
    "quantity" => 1
        ]);

$transaction = new ChartMogul\Transactions\Payment([
    "date" => "2015-11-05T00:14:23.000Z",
    "result" => "successful"
        ]);

$invoice = new ChartMogul\Invoice([
    "external_id" => "INV0001",
    "date" => "2015-11-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]
]);
?>
// Example for registering a one time payment
api.CreateInvoices([]*cm.Invoice{{
  ExternalID: "INV0001",
  Date:       "2015-11-01 00:00:00",
  Currency:   "USD",
  CustomerExternalID: "cus_0001",
  DataSourceUUID: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
  LineItems: []*cm.LineItem{{
      Type:          "one_time",
      Description:   "Consultation Fees",
      AmountInCents: 2500,
      Quantity:      1,
    }},
  Transactions: []*cm.Transaction{{
      Date:   "2015-11-05 00:14:23",
      Type:   "payment",
      Result: "successful",
    }},
}}, "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7")
# Example for registering a one time payment
chartmogul.Invoice.create(
    config,
    uuid="cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
    data={
        "invoices": [{
            "external_id": "INV0001",
            "date": "2015-11-01 00:00:00",
            "currency": "USD",
            "customer_external_id": "cus_0001",
            "data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
            "line_items": [{
                "type": "one_time",
                "description": "Consultation Fees",
                "amount_in_cents": 2500,
                "quantity": 1
            }],
            "transactions": [{
                "date": "2015-11-05 00:14:23",
                "type": "payment",
                "result": "successful"
            }]
        }]
    }).then(lambda result: print(result)).get()

In some cases, you could have one-time payments for specific subscription plans. You can include the plan_uuid for the one_time line item in such cases, and ChartMogul will attribute non-recurring revenue towards the specified plan. This will allow for filtering non-recurring revenue by plan.

👍

Non-recurring payment specified correctly

If specified correctly as demonstrated, this example non-recurring payment will result in the Gross Cash Flow, Net Cash flow and Non-Recurring Cash Flow for Adam Smith increasing by $25 on November 5th.