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 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_ACCOUNT_TOKEN:YOUR_SECRET_KEY \
     -H "Content-Type: application/json" \
     -d '{
     "invoices":[
       {
          "external_id": "INV0001",
          "date": "2015-11-01 00:00:00",
          "currency": "USD",
          "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::Import::LineItems::OneTime.new(
  description: "Consultation Fees",
  amount_in_cents: 2500,
  quantity: 1
)
transaction = ChartMogul::Import::Transactions::Payment.new(
  date: Time.utc(2015, 11, 5, 0, 14, 23),
  result: 'successful'
)
invoice = ChartMogul::Import::Invoice.new(
  external_id: 'INV0001',
  date: Time.utc(2015, 11, 1),
  currency: 'USD',
  line_items: [line_item],
  transactions: [transaction]
)

ChartMogul::Import::CustomerInvoices.create!(customer_uuid: "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7", invoices: [invoice])
// Example for registering a one time payment
ChartMogul.Import.Invoice.create(config,
    "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7", {
        "invoices": [{
            "external_id": "INV0001",
            "date": "2015-11-01 00:00:00",
            "currency": "USD",
            "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\Import\LineItems\OneTime([
    "description" => "Consultation Fees",
    "amount_in_cents" => 2500,
    "quantity" => 1
        ]);

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

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

ChartMogul\Import\CustomerInvoices::create([
    "customer_uuid" => "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
    "invoices" => [$invoice]
]);
?>

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.

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.