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
    }
  ]
}

Behavior with different types of sources. For automatic sources like Stripe, Chargebee, Recurly and Braintree (the latest version of the integration), we now permanently store all records added, edited or disabled using the API. Such edits are preserved after customer re-syncs and automatic updates.

For these sources, use the include_edit_histories query parameter when retrieving or listing invoices to fetch both the original values imported from the billing system and the edited values. The with_disabled query parameter allows you to include disabled records in the response.

For other automatic sources, edits done via the API may be overwritten during customer re-syncs or automatic updates.

For custom sources, edits are not stored separately from the original data.

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.

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 or manual.

status

Specifies the status of the invoice, with possible values open, paid, refunded, voided or written_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 or one_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 or differential_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).