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.
Updated over 1 year ago