Adding refunds using the ChartMogul API
This tutorial describes how you can add refunds using the ChartMogul 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 of 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_API_KEY: \
-H "Content-Type: application/json" \
-d '{
"invoices":[
{
"external_id": "INV0004",
"date": "2016-01-01 00:00:00",
"currency": "USD",
"customer_external_id": "cus_0002",
"data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
"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",
"customer_external_id": "cus_0002",
"data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
"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 of 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",
customer_external_id: "cus_0002",
data_source_uuid: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
line_items: [line_item],
transactions: [transaction_1],
)
invoice_2 = ChartMogul::Invoice.new(
external_id: "INV0005",
date: Time.utc(2016, 1, 5),
currency: "USD",
customer_external_id: "cus_0002",
data_source_uuid: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
line_items: [line_item],
transactions: [transaction_2],
)
ChartMogul::CustomerInvoices.create!(
customer_uuid: "cus_ee325d54-7ab4-421b-cdb2-eb6b9e546034",
invoices: [invoice_1, invoice_2],
)
// Example of 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",
customer_external_id: "cus_0002",
data_source_uuid: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
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",
customer_external_id: "cus_0002",
data_source_uuid: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
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 of 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",
"customer_external_id" => "cus_0002",
"data_source_uuid" => "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
"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",
"customer_external_id" => "cus_0002",
"data_source_uuid" => "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
"line_items" => [$line_item2],
"transactions" => [$transaction2]
]);
ChartMogul\CustomerInvoices::create([
"customer_uuid" => "cus_ee325d54-7ab4-421b-cdb2-eb6b9e546034",
"invoices" => [$invoice1, $invoice2]
]);
// Example of adding a refund from the past
api.CreateInvoices(
[]*cm.Invoice{{
ExternalID: "INV0004",
Date: "2016-01-01 00:00:00",
Currency: "USD",
CustomerExternalID: "cus_0002",
DataSourceUUID: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
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",
CustomerExternalID: "cus_0002",
DataSourceUUID: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
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 of adding a refund in real time
chartmogul.Invoice.create(
config,
uuid="cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
data={
"invoices": [
{
"external_id": "INV0006",
"date": "2016-01-25 00:00:00",
"currency": "USD",
"customer_external_id": "cus_0001",
"data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
"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",
}
],
}
]
},
)
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 of 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_API_KEY: \
-H "Content-Type: application/json"
-d '{
"invoices":[
{
"external_id": "INV0006",
"date": "2016-01-25 00:00:00",
"currency": "USD",
"customer_external_id": "cus_0001",
"data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
"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 of 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",
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 of 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",
customer_external_id: "cus_0001",
data_source_uuid: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
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 of 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",
"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 of adding a refund in real time
api.CreateInvoices(
[]*cm.Invoice{{
ExternalID: "INV0006",
Date: "2016-01-25 00:00:00",
Currency: "USD",
CustomerExternalID: "cus_0001",
DataSourceUUID: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
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",
"customer_external_id": "cus_0001",
"data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
"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"
}]
}]
})
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 of adding a partial refund
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": "INV0006",
"date": "2016-01-25 00:00:00",
"currency": "USD",
"customer_external_id": "cus_0001",
"data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
"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 of 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",
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 of 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",
customer_external_id: "cus_0001",
data_source_uuid: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
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 of 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",
"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 of adding a partial refund
api.CreateInvoices(
[]*cm.Invoice{{
ExternalID: "INV0006",
Date: "2016-01-25 00:00:00",
Currency: "USD",
CustomerExternalID: "cus_0001",
DataSourceUUID: "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
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 of adding a partial refund
chartmogul.Invoice.create(
config,
uuid="cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
data={
"invoices": [
{
"external_id": "INV0006",
"date": "2016-01-25 00:00:00",
"currency": "USD",
"customer_external_id": "cus_0001",
"data_source_uuid": "ds_fef05d54-47b4-431b-aed2-eb6b9e545430",
"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",
}
],
}
]
},
)
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 typerefund
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.
Updated 3 months ago