Guides
Help Center

Adding a non-recurring payment using the ChartMogul API

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

Suggest Edits

📘

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",
        },
      ],
    },
  ],
});

// Example for registering a one-time payment

$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",
          }
        ],
      }
    ]
  },
)

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 4 months ago