List Customer’s Invoices
GET https://api.chartmogul.com/v1/import/customers/{CUSTOMER_UUID}/invoices
Returns a list of invoice objects created using the API for a given customer.
curl -X GET "https://api.chartmogul.com/v1/import/customers/cus_f466e33d-ff2b-4a11-8f85-417eb02157a7/invoices" \
-u YOUR_API_KEY: \
-H "Content-Type: application/json"ChartMogul::CustomerInvoices.all("cus_7388fd53-1ecf-481e-97e6-28adb653f6c0", per_page: 2)ChartMogul.Invoice.all(config, "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7");ChartMogul\CustomerInvoices::all([
"customer_uuid" => "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7"
]);api.ListInvoices(&cm.Cursor{PerPage: 2}, "cus_c0dc8d74-edfd-11e6-a357-832dddba822f")chartmogul.Invoice.all(
config, uuid="cus_c0dc8d74-edfd-11e6-a357-832dddba822f", per_page=2
){
"customer_uuid": "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
"invoices": [
{
"uuid": "inv_565c73b2-85b9-49c9-a25e-2b7df6a677c9",
"customer_uuid": "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
"external_id": "inv_0001",
"date": "2022-11-01T00:00:00.000Z",
"due_date": "2022-11-15T00:00:00.000Z",
"currency": "USD",
"line_items": [
{
"uuid": "li_d72e6843-5793-41d0-bfdf-0269514c9c56",
"external_id": null,
"type": "subscription",
"subscription_uuid": "sub_e6bc5407-e258-4de0-bb43-61faaf062035",
"subscription_external_id": "sub_0001",
"subscription_set_external_id": "set_0001",
"plan_uuid": "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
"prorated": false,
"service_period_start": "2022-11-01T00:00:00.000Z",
"service_period_end": "2022-12-01T00:00:00.000Z",
"amount_in_cents": 5000,
"quantity": 1,
"discount_code": "PSO86",
"discount_amount_in_cents": 1000,
"tax_amount_in_cents": 900,
"transaction_fees_in_cents": 200,
"transaction_fees_currency": "USD",
"discount_description": "New signup promo",
"event_order": 5,
"account_code": null
},
{
"uuid": "li_0cc8c112-beac-416d-af11-f35744ca4e83",
"external_id": null,
"type": "one_time",
"description": "Setup Fees",
"amount_in_cents": 2500,
"quantity": 1,
"discount_code": "PSO86",
"discount_amount_in_cents": 500,
"tax_amount_in_cents": 450,
"transaction_fees_in_cents": 0,
"transaction_fees_currency": "USD",
"discount_description": "New signup promo",
"account_code": null
}
],
"transactions": [
{
"uuid": "tr_879d560a-1bec-41bb-986e-665e38a2f7bc",
"external_id": null,
"type": "payment",
"date": "2022-11-05T00:14:23.000Z",
"result": "successful"
}
]
}
],
"current_page": 1, // deprecated
"total_pages": 1, // deprecated
"cursor": "AjMx90kC0yMVQwNNwoYToyNC4wMDAwMDAwMDBgks68k",
"has_more": true
}#<ChartMogul::CustomerInvoices:0x007fb49884b850
@customer_uuid="cus_f466e33d-ff2b-4a11-8f85-417eb02157a7"
@invoices=[
#<ChartMogul::Invoice:0x007fb498a04660
@uuid="inv_565c73b2-85b9-49c9-a25e-2b7df6a677c9",
@date=2022-11-01 00:00:00 UTC,
@currency="USD",
@external_id="inv_0001",
@due_date=2022-11-15 00:00:00 UTC,
@line_items=[
#<ChartMogul::LineItems::Subscription:0x007fb4994d23f8
@uuid="li_d72e6843-5793-41d0-bfdf-0269514c9c56",
@external_id=nil,
@type="subscription",
@subscription_uuid="sub_e6bc5407-e258-4de0-bb43-61faaf062035",
@subscription_external_id="sub_0001",
@subscription_set_external_id="set_0001",
@plan_uuid="pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
@service_period_start=2022-11-01 00:00:00 UTC,
@service_period_end=2022-12-01 00:00:00 UTC,
@amount_in_cents=5000,
@quantity=1,
@discount_code="PSO86",
@discount_amount_in_cents=1000,
@tax_amount_in_cents=900,
@transaction_fees_in_cents=200,
@cancelled_at=nil,
@prorated=false,
@invoice_uuid="inv_565c73b2-85b9-49c9-a25e-2b7df6a677c9",
@transaction_fees_currency="USD",
@discount_description="New signup promo",
@event_order=5,
@account_code=nil
>,
#<ChartMogul::LineItems::OneTime:0x007fb499149358
@uuid="li_0cc8c112-beac-416d-af11-f35744ca4e83",
@external_id=nil,
@type="one_time",
@amount_in_cents=2500,
@description="Setup Fees",
@quantity=1,
@discount_amount_in_cents=500,
@discount_code="PSO86",
@tax_amount_in_cents=450,
@transaction_fees_in_cents=0,
@invoice_uuid="inv_565c73b2-85b9-49c9-a25e-2b7df6a677c9",
@transaction_fees_currency="USD",
@discount_description="New signup promo",
@account_code=nil
>
],
@transactions=[
#<ChartMogul::Transactions::Payment:0x007fb4991013f0
@uuid="tr_879d560a-1bec-41bb-986e-665e38a2f7bc",
@external_id=nil,
@date=2022-11-05 14:23:00 UTC,
@result="successful",
@type="payment",
@invoice_uuid="inv_565c73b2-85b9-49c9-a25e-2b7df6a677c9"
>
]>,
],
@current_page=1, # deprecated with version 4.0.0
@total_pages=1, # deprecated with version 4.0.0
@cursor="AjMx90kC0yMVQwNNwoYToyNC4wMDAwMDAwMDBgks68k",
@has_more=true
>{
customer_uuid: "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
invoices: [
{
uuid: "inv_565c73b2-85b9-49c9-a25e-2b7df6a677c9",
customer_uuid: "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
external_id: "inv_0001",
date: "2022-11-01T00:00:00.000Z",
due_date: "2022-11-15T00:00:00.000Z",
currency: "USD",
line_items: [
{
uuid: "li_d72e6843-5793-41d0-bfdf-0269514c9c56",
external_id: null,
type: "subscription",
subscription_uuid: "sub_e6bc5407-e258-4de0-bb43-61faaf062035",
subscription_external_id: "sub_0001",
subscription_set_external_id: "set_0001",
plan_uuid: "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
prorated: false,
service_period_start: "2022-11-01T00:00:00.000Z",
service_period_end: "2022-12-01T00:00:00.000Z",
amount_in_cents: 5000,
quantity: 1,
discount_code: "PSO86",
discount_amount_in_cents: 1000,
tax_amount_in_cents: 900,
transaction_fees_in_cents: 200,
transaction_fees_currency: "USD",
discount_description: "New signup promo",
event_order: 5,
account_code: null
},
{
uuid: "li_0cc8c112-beac-416d-af11-f35744ca4e83",
external_id: null,
type: "one_time",
description: "Setup Fees",
amount_in_cents: 2500,
quantity: 1,
discount_code: "PSO86",
discount_amount_in_cents: 500,
tax_amount_in_cents: 450,
transaction_fees_in_cents: 0,
transaction_fees_currency: "USD",
discount_description: "New signup promo",
account_code: null
}
],
transactions: [
{
uuid: "tr_879d560a-1bec-41bb-986e-665e38a2f7bc",
external_id: null,
type: "payment",
date: "2022-11-05T00:14:23.000Z",
result: "successful"
}
]
}
],
current_page: 1, // deprecated with version 3.0.0
total_pages: 2, // deprecated with version 3.0.0
cursor: "AjMx90kC0yMVQwNNwoYToyNC4wMDAwMDAwMDBgks68k",
has_more: true
}ChartMogul\CustomerInvoices::__set_state(array(
"customer_uuid" => "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
"current_page" => 1, # deprecated with version 6.0.0
"total_pages" => 2, # deprecated with version 6.0.0
"cursor" => "AjMx90kC0yMVQwNNwoYToyNC4wMDAwMDAwMDBgks68k",
"has_more" => true,
"invoices" => Doctrine\Common\Collections\ArrayCollection::__set_state(array(
"elements" => array(
0 => ChartMogul\Invoice::__set_state(array(
"uuid" => "inv_565c73b2-85b9-49c9-a25e-2b7df6a677c9",
"date" => "2022-11-01T00:00:00.000Z",
"external_id" => "INV0001",
"due_date" => "2022-11-15T00:00:00.000Z",
"currency" => "USD",
"line_items" => Doctrine\Common\Collections\ArrayCollection::__set_state(array(
"elements" => array(
0 => ChartMogul\LineItems\Subscription::__set_state(array(
"type" => "subscription",
"service_period_start" => "2022-11-01T00:00:00.000Z",
"service_period_end" => "2022-12-01T00:00:00.000Z",
"cancelled_at" => NULL,
"prorated" => false,
"subscription_uuid" => "sub_e6bc5407-e258-4de0-bb43-61faaf062035",
"subscription_external_id" => "sub_0001",
"subscription_set_external_id" => "set_0001",
"plan_uuid" => "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
"uuid" => "li_d72e6843-5793-41d0-bfdf-0269514c9c56",
"amount_in_cents" => 5000,
"quantity" => 1,
"discount_amount_in_cents" => 1000,
"discount_code" => "PS086",
"tax_amount_in_cents" => 900,
"transaction_fees_in_cents" => 200,
"external_id" => NULL,
"invoice_uuid" => NULL,
"transaction_fees_currency" => "USD",
"discount_description" => "New signup promo",
"event_order" => 5,
"account_code" => ""
)),
1 => ChartMogul\LineItems\OneTime::__set_state(array(
"type" => "one_time",
"description" => "Setup Fees",
"uuid" => "li_0cc8c112-beac-416d-af11-f35744ca4e83",
"amount_in_cents" => 2500,
"quantity" => 1,
"discount_amount_in_cents" => 500,
"discount_code" => "PSO86",
"tax_amount_in_cents" => 450,
"transaction_fees_in_cents" => 0,
"external_id" => NULL,
"invoice_uuid" => NULL,
"transaction_fees_currency" => "USD",
"discount_description" => "New signup promo",
"account_code" => ""
)),
),
)),
"transactions" => Doctrine\Common\Collections\ArrayCollection::__set_state(array(
"elements" => array(
0 => ChartMogul\Transactions\Payment::__set_state(array(
"type" => "payment",
"uuid" => "tr_879d560a-1bec-41bb-986e-665e38a2f7bc",
"date" => "2022-11-05T00:14:23.000Z",
"result" => "successful"
))
)
))
))
)
))
));(*chartmogul.Invoices)(0xc04204a380)({
CustomerUUID: (string) (len=40) "cus_c0dc8d74-edfd-11e6-a357-832dddba822f",
TotalPages: (uint32) 1, // deprecated with version v4
CurrentPage: (uint32) 1, // deprecated with version v4
Cursor: (string) (len=44) "AjMx90kC0yMVQwNNwoYToyNC4wMDAwMDAwMDBgks68k",
HasMore: (bool) true,
Error: (string) "",
Invoices: ([]*chartmogul.Invoice) (len=1 cap=4) {
(*chartmogul.Invoice)(0xc0420f0320)({
UUID: (string) (len=40) "inv_565c73b2-85b9-49c9-a25e-2b7df6a677c9",
Currency: (string) (len=3) "USD",
Date: (string) (len=24) "2022-11-01T00:00:00.000Z",
DueDate: (string) (len=24) "2022-11-15T00:00:00.000Z",
ExternalID: (string) (len=7) "inv_0001",
LineItems: ([]*chartmogul.LineItem) (len=2 cap=4) {
(*chartmogul.LineItem)(0xc0420e60f0)({
UUID: (string) (len=39) "li_d72e6843-5793-41d0-bfdf-0269514c9c56",
AccountCode: (string) "",
AmountInCents: (int) 5000,
CancelledAt: (string) "",
Description: (string) "",
DiscountAmountInCents: (int) 1000,
DiscountCode: (string) (len=5) "PSO86",
ExternalID: (string) "",
PlanUUID: (string) (len=39) "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
Prorated: (bool) false,
Quantity: (int) 1,
ServicePeriodEnd: (string) (len=24) "2022-12-01T00:00:00.000Z",
ServicePeriodStart: (string) (len=24) "2022-11-01T00:00:00.000Z",
SubscriptionExternalID: (string) "sub_0001",
SubscriptionSetExternalID: (string) (len=8) "set_0001",
SubscriptionUUID: (string) (len=40) "sub_e6bc5407-e258-4de0-bb43-61faaf062035",
TaxAmountInCents: (int) 900,
TransactionFeesInCents: (int) 200,
TransactionFeesCurrency: (string) "USD",
DiscountDescription: (string) "New signup promo",
EventOrder: (int) 5,
Type: (string) (len=12) "subscription"
}),
(*chartmogul.LineItem)(0xc0420e61e0)({
UUID: (string) (len=39) "li_0cc8c112-beac-416d-af11-f35744ca4e83",
AccountCode: (string) "",
AmountInCents: (int) 2500,
CancelledAt: (string) "",
Description: (string) (len=10) "Setup Fees",
DiscountAmountInCents: (int) 500,
DiscountCode: (string) (len=5) "PSO86",
ExternalID: (string) "",
PlanUUID: (string) "",
Prorated: (bool) false,
Quantity: (int) 1,
ServicePeriodEnd: (string) "",
ServicePeriodStart: (string) "",
SubscriptionExternalID: (string) "",
SubscriptionUUID: (string) "",
TaxAmountInCents: (int) 450,
TransactionFeesInCents: (int) 0,
TransactionFeesCurrency: (string) "USD",
DiscountDescription: (string) "New signup promo",
Type: (string) (len=8) "one_time"
})
},
Transactions: ([]*chartmogul.Transaction) (len=1 cap=4) {
(*chartmogul.Transaction)(0xc04200fc80)({
UUID: (string) (len=39) "tr_879d560a-1bec-41bb-986e-665e38a2f7bc",
Date: (string) (len=24) "2022-11-05T00:14:23.000Z",
ExternalID: (string) "",
Result: (string) (len=10) "successful",
Type: (string) (len=7) "payment",
Errors: (chartmogul.Errors) chartmogul: map[]
})
},
Errors: (*chartmogul.Errors)(<nil>)
})
}
})Invoices(
invoices=[
<Invoice{currency="USD",
date=datetime.datetime(2022, 11, 1, 0, 0, tzinfo=tzutc()),
due_date=datetime.datetime(2022, 11, 15, 0, 0, tzinfo=tzutc()),
external_id="inv_0001",
line_items=[
<LineItem{account_code=None,
amount_in_cents=5000,
discount_amount_in_cents=1000,
discount_code="PSO86",
external_id=None,
plan_uuid="pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
prorated=False,
quantity=1,
service_period_end=datetime.datetime(2022, 12, 1, 0, 0, tzinfo=tzutc()),
service_period_start=datetime.datetime(2022, 11, 1, 0, 0, tzinfo=tzutc()),
subscription_uuid="sub_e6bc5407-e258-4de0-bb43-61faaf062035",
subscription_external_id="sub_0001",
subscription_set_external_id="set_0001",
tax_amount_in_cents=900,
transaction_fees_in_cents=200,
transaction_fees_currency="USD",
discount_description="New signup promo",
event_order=5,
type="subscription",
uuid="li_d72e6843-5793-41d0-bfdf-0269514c9c56"
}>,
<LineItem{account_code=None,
amount_in_cents=2500,
discount_amount_in_cents=500,
discount_code="PSO86",
external_id=None,
quantity=1,
tax_amount_in_cents=450,
transaction_fees_in_cents=0,
transaction_fees_currency="USD",
discount_description="New signup promo",
type="one_time",
uuid="li_0cc8c112-beac-416d-af11-f35744ca4e83"
}>
],
transactions=[
<Transaction{date=datetime.datetime(2022, 11, 5, 0, 14, 23, tzinfo=tzutc()),
external_id=None,
result="successful",
type="payment",
uuid="tr_879d560a-1bec-41bb-986e-665e38a2f7bc"
}>
],
uuid="inv_565c73b2-85b9-49c9-a25e-2b7df6a677c9"
}>
],
customer_uuid="cus_c0dc8d74-edfd-11e6-a357-832dddba822f",
current_page=1, # deprecated with version 4.0.0
total_pages=1, # deprecated with version 4.0.0
cursor="AjMx90kC0yMVQwNNwoYToyNC4wMDAwMDAwMDBgks68k",
has_more=True
)Path parameters
customer_uuidstring required- The ChartMogul UUID of the Customer whose invoices are requested.
Query parameters
cursorstring optional- A value that fetches the next page of Customer's Invoices. To fetch the next page of Customer's Invoices, set
cursorto the value received in the previous page response. per_pageint32 optional default: 200- A limit on number of subscriptions to return per page. The default and maximum value is
200. validation_typestring optional default: "valid"- The validation type of the invoices to be retrieved. Accepts the following values:
valid,invalid, andall. Based on this value, returns valid, invalid, or both valid and invalid invoices. The default value isvalid. This parameter applies to read (GET) requests only. For update and delete operations, the value defaults toall, so records with validation errors can always be found and modified.
Response
In the response, the customer_uuid is the UUID of the customer whose invoices are listed.
invoices contains an array of invoice objects with the following data:
uuid-
The UUID of the invoice object generated by ChartMogul.
external_id-
The unique external identifier for this invoice, as specified by you.
date-
The date on which this invoice was raised, as specified by you.
due_date-
The date by which this invoice must be paid, as specified by you.
currency-
The three-letter code of the currency of this invoice, as specified by you.
line_items-
contains an array of
line_itemobjects of this invoice with the following data:uuid- The UUID of the
line_itemobject generated by ChartMogul. external_id- The unique external identifier for this line item, as specified by you.
type- The type of line item, one of
subscription,one_time, ortrial. as specified by you. On October 2, 2025, we introducedtrialas an invoice line item type. We’re gradually making the functionality available to all accounts. Learn more. subscription_uuid- The UUID of the subscription object generated by ChartMogul.
subscription_external_id- The unique external identifier for this subscription, as specified by you.
subscription_set_external_id- An optional unique external identifier for the subscription set to which this subscription belongs, as specified by you.
plan_uuid- The UUID of the plan object associated with the above subscription object, generated by ChartMogul.
prorated- A boolean stating whether or not this is a prorated charge for the subscription object, as specified by you.
service_period_start- The start of the service period for which the subscription is being charged, as specified by you.
service_period_end- The end of the service period for which the subscription is being charged, as specified by you.
description- A short description of the
one_timeline item being charged to the customer, as specified by you. amount_in_cents- The amount in cents charged towards this line item for the specified service period, after discounts and taxes have been applied, as specified by you.
quantity- The quantity of this line item being billed.
discount_code- A reference code for any discount applied to this line item, as specified by you.
discount_amount_in_cents- The discount amount in cents for this line item, as specified by you.
tax_amount_in_cents- The tax amount in cents for this line item, as specified by you.
transaction_fees_in_cents- The transaction fees in cents for this line item, as specified by you.
transaction_fees_currency- The transaction fees currency for this line item, as specified by you.
discount_description- The discount amount in cents description for this line item, as specified by you.
event_order- A numeric value that determines the sequence in which events are processed when multiple events occur at the same timestamp, as specified by you.
account_code- The accounting code for the line item, as specified by you.
transactions-
contains an array of transaction objects of this invoice with the following data:
uuid- The UUID of the transaction object generated by ChartMogul.
external_id- The unique external identifier for this transaction, as specified by you.
type- One of payment or refund, as specified by you.
date- The timestamp of when the transaction was attempted, as specified by you.
result- The result of the transaction attempt. One of successful or failed, as specified by you.
amount_in_cents- The amount partially paid/refunded for this transaction.
The other keys represent pagination attributes:
cursor- A value that should be used in the next API request to fetch the next page of customer's invoices. Request for next page should be initiated only if has_more is set to true indicating that there are more customer's invoices to list.
has_more- One of true or false depending on whether there are more pages with results for this request.