Update an Invoice
PATCH https://api.chartmogul.com/v1/invoices/{INVOICE_UUID}
Updates the details of an invoice, such as the due date or currency.
curl -X PATCH "https://api.chartmogul.com/v1/invoices/inv_f466e33d-ff2b-4a11-8f85-417eb02157a7" \
-u YOUR_API_KEY: \
-H "Content-Type: application/json" \
-d '{
"date": "2024-11-10T00:00:00Z",
"due_date": "2024-12-02T00:00:00Z",
"currency": "EUR"
}'
{
"uuid": "inv_f466e33d-ff2b-4a11-8f85-417eb02157a7",
"external_id": "inv_0001",
"date": "2024-11-10T00:00:00Z",
"due_date": "2024-12-02T00:00:00Z",
"currency": "EUR",
"customer_external_id": "cus_RBFK8utRj5BZIN",
"collection_method": null,
"status": "paid",
"errors":
{},
"disabled": false,
"disabled_at": null,
"disabled_by": null,
"user_created": false,
"line_items": [
{
"uuid": "li_d72e6843-5793-41d0-bfdf-0269514c9c56",
"external_id": null,
"type": "subscription",
"amount_in_cents": 5000,
"quantity": 1,
"discount_code": "PSO86",
"discount_amount_in_cents": 1000,
"tax_amount_in_cents": 900,
"transaction_fees_in_cents": 200,
"account_code": null,
"plan_uuid": "pl_eed05d54-75b4-431b-adb2-eb6b9e543206",
"plan_external_id": "gold_plan",
"transaction_fees_currency": "USD",
"discount_description": "New signup promo",
"event_order": 5,
"balance_transfer": false,
"subscription_uuid": "sub_e6bc5407-e258-4de0-bb43-61faaf062035",
"subscription_external_id": "sub_0001",
"prorated": false,
"proration_type": "full",
"service_period_start": "2022-11-01T00:00:00.000Z",
"service_period_end": "2022-12-01T00:00:00.000Z",
"subscription_set_external_id": "set_0001",
"disabled": false,
"disabled_at": null,
"disabled_by": null,
"user_created": false
},
{
"uuid": "li_d72e6843-5793-41d0-bfdf-0269514c9c56",
"external_id": null,
"type": "one_time",
"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",
"description": "Setup Fees",
"disabled": false,
"disabled_at": null,
"disabled_by": null,
"user_created": false
}
],
"transactions": [
{
"uuid": "tr_879d560a-1bec-41bb-986e-665e38a2f7bc",
"external_id": null,
"type": "payment",
"date": "2022-11-05T00:14:23.000Z",
"result": "successful",
"amount_in_cents": null,
"transaction_fees_in_cents": 350,
"transaction_fees_currency": "EUR",
"disabled": false,
"disabled_at": null,
"disabled_by": null,
"user_created": false
}
]
}
Scope of this action.
This endpoint is meant for updating invoice details such as due_date
or currency
. To update line items and transactions associated with an invoice, use the Update a Line Item and Update a Transaction endpoints.
Path parameters
invoice_uuid
string- The ChartMogul UUID of the invoice to be updated.
Query parameters
handle_as_user_edit
boolean optional default: false- Valid only for automatic sources (Stripe, Chargebee, Recurly, Braintree); ignored for others.
true
— The invoice is updated as a user edit and persist through resyncs and reimports.false
— The invoice update is treated as system-generated and may be overwritten or removed during resyncs and reimports.
Body parameters
date
string optional-
The date and time when this invoice was raised. Must be an ISO 8601-formatted date and time.
due_date
string optional-
The date by which this invoice must be paid. Must be an ISO 8601-formatted time.
currency
string optional-
The three-letter currency code of the currency in which this invoice is being billed, e.g. USD, EUR, GBP. Refer to the full list of supported currencies.
collection_method
string optional default: "automatic"-
Specifies how the payment for the invoice is collected.
automatic
— Payments are processed within the billing system without manual intervention (e.g., credit cards, PayPal, direct debits).manual
— Payments are handled outside the billing system and require customer or business action (e.g., checks, manual bank transfers). s
Response
The response contains 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.
customer_uuid
-
The UUID of the customer that the invoice belongs to.
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.
customer_external_id
-
The unique identifier for the customer associated with this invoice. Typically an identifier from your internal system.
collection_method
-
Specifies how the payment for the invoice is collected, with possible values
automatic
ormanual
. status
-
Specifies the status of the invoice, with possible values
open
,paid
,refunded
,voided
orwritten_off
. errors
-
Specifies if there are any validation errors.
disabled
-
A boolean stating whether or not the invoice was disabled.
disabled_at
-
The date and time when the invoice was disabled (
null
for non-disabled records). disabled_by
-
The email address of the user who disabled the invoice (
null
for non-disabled records). user_created
-
A boolean stating whether or not the invoice was created by the user for sources like Stripe, Chargebee, Recurly and Braintree (the latest version of the integration).
line_items
-
contains an array of
line_item
objects of this invoice with the following data:uuid
- The UUID of the
line_item
object generated by ChartMogul. external_id
- The unique external identifier for this line item, as specified by you.
type
- The type of line item, either
subscription
orone_time
, 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.
account_code
- The accounting code for the line item, as specified by you.
plan_uuid
- The UUID of the plan object associated with the above subscription object, generated by ChartMogul.
plan_external_id
- The unique identifier for the plan associated with this invoice. Typically an identifier from your internal system.
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.
balance_transfer
- A boolean stating whether or not this represents a value returned to customer balance.
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.
prorated
- A boolean stating whether or not this is a prorated charge for the subscription object, as specified by you.
proration_type
- A string defining the type of proration, with possible values
differential
,full
ordifferential_mrr
. 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_time
line item being charged to the customer, as specified by you. disabled
- A boolean stating whether or not the line item was disabled.
disabled_at
- The date and time when the line item was disabled (
null
for non-disabled records). disabled_by
- The email address of the user who disabled the line item (
null
for non-disabled records). user_created
- A boolean stating whether or not the line item was created by the user for sources like Stripe, Chargebee, Recurly and Braintree (the latest version of the integration).
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.
transaction_fees_in_cents
- The final total transaction fees paid to a billing provider and/or payment processor for this line item. Expressed in cents (or pence for GBP, etc.).
transaction_fees_currency
- The three-letter currency code for
transaction_fees_in_cents
. Refer to the full list of supported currencies. disabled
- A boolean stating whether or not the transaction was disabled.
disabled_by
- The email address of the user who disabled the transaction (
null
for non-disabled records). disabled_at
- The date and time when the transaction was disabled (
null
for non-disabled records). user_created
- A boolean stating whether or not the transaction was created by the user for sources like Stripe, Chargebee, Recurly and Braintree (the latest version of the integration).