Update Invoice Item

PATCH

/api/:account_id/invoice-items/:external_id

PATCH

/api/:account_id/invoice-items/:external_id

$ curl -X PATCH https://app.paymentkit.com/api/account_id/invoice-items/external_id \
>      -H "Authorization: Bearer <token>" \
>      -H "Content-Type: application/json" \
>      -d '{}'

1 {
2   "id": "invitem_9f8b7c6d5e4a3b2c1d0e",
3   "invoice_id": "inv_1234567890abcdef",
4   "description": "Usage for April 2024 billing cycle",
5   "quantity": 1234.5,
6   "amount": 6172500,
7   "currency": "usd",
8   "metadata": {},
9   "created_at": "2024-04-20T11:00:00Z",
10   "updated_at": "2024-04-20T12:00:00Z",
11   "price": {
12     "id": "price_9876543210fedcba",
13     "account_id": "acct_0011223344556677",
14     "product_id": "prod_1122334455667788",
15     "name": "SMS Tiered Pricing",
16     "unit_amount_atom": 5000,
17     "currency": "usd",
18     "is_active": true,
19     "unit_label": "message",
20     "pricing_type": "tiered",
21     "recurring_interval": "month",
22     "recurring_interval_count": 1,
23     "auto_renew": true,
24     "contract_term_multiple": 1,
25     "trial_days": 14,
26     "usage_type": "metered",
27     "metered_id": "metered_sms_001",
28     "billing_scheme": "tiered",
29     "tier_amount_info": {
30       "mode": "volume",
31       "amount_atoms": [
32         {
33           "unit_amount_atom": 5000,
34           "units_upto": 1000,
35           "flat_amount_atom": 0
36         },
37         {
38           "unit_amount_atom": 4500,
39           "units_upto": 5000,
40           "flat_amount_atom": 0
41         },
42         {
43           "unit_amount_atom": 4000,
44           "units_upto": 10000,
45           "flat_amount_atom": 0
46         },
47         {
48           "unit_amount_atom": 3500,
49           "units_upto": 1000000,
50           "flat_amount_atom": 0
51         }
52       ]
53     },
54     "prerequisite_price_ids": [
55       "price_basic_sms_001"
56     ],
57     "exclusive_customer_ids": [
58       "cust_9988776655"
59     ],
60     "metadata": {},
61     "created_at": "2024-01-15T09:30:00Z",
62     "updated_at": "2024-04-20T12:00:00Z",
63     "product_name": "Premium SMS Package",
64     "product_description": "Bulk SMS messaging service with tiered pricing",
65     "custom_fields": {},
66     "quantity_divisor": 1,
67     "quantity_rounding": "ceil"
68   },
69   "product_name": "Premium SMS Package",
70   "proration": false,
71   "period_start": "2024-04-01T00:00:00Z",
72   "period_end": "2024-04-30T23:59:59Z",
73   "subscription_id": "sub_4455667788990011",
74   "subscription_item_id": "subitem_2233445566778899",
75   "tier_breakdown": [
76     {
77       "label": "1-1000 messages",
78       "quantity": 1000,
79       "amount_atom": 5000000,
80       "units_from": 1,
81       "unit_amount_atom": 5000,
82       "flat_fee": false,
83       "units_to": 1000
84     },
85     {
86       "label": "1001-1234 messages",
87       "quantity": 234.5,
88       "amount_atom": 1055250,
89       "units_from": 1001,
90       "unit_amount_atom": 4500,
91       "flat_fee": false,
92       "units_to": 1234
93     }
94   ]
95 }

Update a floating invoice item.

Only floating items (not yet attached to an invoice) can be updated. Once an item is swept into an invoice, it becomes immutable.

For priced items, updating quantity will recalculate the amount using the price’s pricing model (tiered, package, per-unit, etc.).

For amount-only items (no price_id), you can update quantity, unit_amount, or amount directly.

Use cases:

Update quantity as usage accumulates (e.g., SMS metering)
Correct description before invoice generation
Adjust amount for custom pricing

Works for both User and API Key authentication. Account access is automatically validated via endpoint dependency.

Update a floating invoice item. Only floating items (not yet attached to an invoice) can be updated. Once an item is swept into an invoice, it becomes immutable. For priced items, updating quantity will recalculate the amount using the price's pricing model (tiered, package, per-unit, etc.). For amount-only items (no price_id), you can update quantity, unit_amount, or amount directly. Use cases: - Update quantity as usage accumulates (e.g., SMS metering) - Correct description before invoice generation - Adjust amount for custom pricing Works for both User and API Key authentication. Account access is automatically validated via endpoint dependency.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

external_idstringRequired

account_idstringRequired

Request

This endpoint expects an object.

quantitydouble or nullOptional

descriptionstring or nullOptional

unit_amountdouble or nullOptional

amountdouble or nullOptional

Response

Successful Response

idstring

invoice_idstring or null

descriptionstring or null

quantitydouble

amountinteger

currencystring

metadatamap from strings to any or null

created_atdatetime

updated_atdatetime

priceobject or nullOptional

product_namestring or nullOptional

prorationbooleanOptionalDefaults to false

period_startdatetime or nullOptional

period_enddatetime or nullOptional

subscription_idstring or nullOptional

subscription_item_idstring or nullOptional

tier_breakdownlist of objects or nullOptional

Errors

422

Unprocessable Entity Error