Finalize Invoice

POST

/api/:account_id/invoices/:external_id/finalize

POST

/api/:account_id/invoices/:external_id/finalize

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

1 {
2   "id": "inv_8f3b2c9d7a1e4b6f",
3   "customer_id": "cus_4a7d9e2f1b3c4d5e",
4   "status": "open",
5   "currency": "usd",
6   "subtotal_amount_atom": 150000,
7   "tax_amount_atom": 12000,
8   "total_amount_atom": 162000,
9   "due_amount_atom": 162000,
10   "paid_amount_atom": 0,
11   "remaining_amount_atom": 162000,
12   "issued_at": "2024-04-10T14:00:00Z",
13   "due_date": "2024-05-10T14:00:00Z",
14   "description": "Monthly subscription invoice for April 2024",
15   "metadata": {
16     "project": "website_redesign",
17     "department": "marketing"
18   },
19   "created_at": "2024-04-10T13:55:00Z",
20   "updated_at": "2024-04-10T14:00:00Z",
21   "applied_balance_amount_atom": 0,
22   "total_discount_amount_atom": 5000,
23   "period_start": "2024-04-01T00:00:00Z",
24   "period_end": "2024-04-30T23:59:59Z",
25   "collection_method": "charge_automatically",
26   "custom_fields": {
27     "sales_rep": "jane.doe",
28     "region": "north_america"
29   },
30   "items": [
31     {
32       "id": "item_9c8d7e6f5a4b3c2d",
33       "invoice_id": "inv_8f3b2c9d7a1e4b6f",
34       "description": "Monthly subscription fee for April 2024",
35       "quantity": 1,
36       "amount": 150000,
37       "currency": "usd",
38       "metadata": {},
39       "created_at": "2024-04-01T00:00:00Z",
40       "updated_at": "2024-04-10T14:00:00Z",
41       "price": {
42         "id": "price_1a2b3c4d5e6f7g8h",
43         "account_id": "acct_1234567890abcdef",
44         "product_id": "prod_0987654321fedcba",
45         "name": "Pro Plan Monthly",
46         "unit_amount_atom": 150000,
47         "currency": "usd",
48         "is_active": true,
49         "unit_label": "month",
50         "pricing_type": "recurring",
51         "recurring_interval": "month",
52         "recurring_interval_count": 1,
53         "auto_renew": true,
54         "contract_term_multiple": 1,
55         "trial_days": 14,
56         "usage_type": "licensed",
57         "metered_id": null,
58         "billing_scheme": "per_unit",
59         "tier_amount_info": {
60           "mode": "volume",
61           "amount_atoms": [
62             {
63               "unit_amount_atom": 150000,
64               "units_upto": null,
65               "flat_amount_atom": 0
66             }
67           ]
68         },
69         "prerequisite_price_ids": [],
70         "exclusive_customer_ids": [],
71         "metadata": {
72           "feature_set": "all_premium"
73         },
74         "created_at": "2023-12-01T10:00:00Z",
75         "updated_at": "2024-03-01T10:00:00Z",
76         "product_name": "Pro Plan Subscription",
77         "product_description": "Access to all premium features",
78         "custom_fields": {},
79         "quantity_divisor": 1,
80         "quantity_rounding": "ceil"
81       },
82       "product_name": "Pro Plan Subscription",
83       "proration": false,
84       "period_start": "2024-04-01T00:00:00Z",
85       "period_end": "2024-04-30T23:59:59Z",
86       "subscription_id": "sub_7e6f5a4b3c2d1e0f",
87       "subscription_item_id": "si_1234567890abcdef",
88       "tier_breakdown": [
89         {
90           "label": "1-∞ units",
91           "quantity": 1,
92           "amount_atom": 150000,
93           "units_from": 1,
94           "unit_amount_atom": 150000,
95           "flat_fee": false,
96           "units_to": null
97         }
98       ]
99     }
100   ],
101   "invoice_number": 1024,
102   "billing_reason": "subscription_cycle",
103   "subscription_id": "sub_7e6f5a4b3c2d1e0f",
104   "payment_method_id": "pm_1a2b3c4d5e6f7g8h",
105   "invoice_pdf_url": "https://app.paymentkit.com/invoices/inv_8f3b2c9d7a1e4b6f.pdf",
106   "receipt_pdf_url": null,
107   "hosted_invoice_url": "https://app.paymentkit.com/invoices/inv_8f3b2c9d7a1e4b6f",
108   "show_payment_link": true
109 }

Finalize an invoice (transition from DRAFT to OPEN).

Triggers PDF generation after finalization. Validates domain invariants post-finalization.

Requirements:

Invoice must be in DRAFT state
Invoice must have at least one line item (unless setup mode)

Returns:

The finalized invoice with OPEN status

Finalize an invoice (transition from DRAFT to OPEN). Triggers PDF generation after finalization. Validates domain invariants post-finalization. Requirements: - Invoice must be in DRAFT state - Invoice must have at least one line item (unless setup mode) Returns: - The finalized invoice with OPEN status

Authentication

AuthorizationBearer

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

Path parameters

external_idstringRequired

account_idstringRequired

Response

Successful Response

idstring

customer_idstring

statusenum

currencyenum

ISO 4217 currency codes.

subtotal_amount_atominteger or null

tax_amount_atominteger or null

total_amount_atominteger or null

due_amount_atominteger or null

paid_amount_atominteger or null

remaining_amount_atominteger or null

issued_atdatetime

due_datedatetime or null

descriptionstring or null

metadatamap from strings to any or null

created_atdatetime

updated_atdatetime

applied_balance_amount_atominteger or nullOptional

total_discount_amount_atominteger or nullOptional

period_startdatetime or nullOptional

period_enddatetime or nullOptional

collection_methodenumOptional

custom_fieldsmap from strings to any or nullOptional

Custom field values. Only included when expand=custom_fields is specified.

itemslist of objectsOptional

invoice_numberinteger or nullOptional

billing_reasonenum or nullOptional

subscription_idstring or nullOptional

payment_method_idstring or nullOptional

invoice_pdf_urlstring or nullOptional

receipt_pdf_urlstring or nullOptional

hosted_invoice_urlstring or nullOptional

show_payment_linkbooleanOptionalDefaults to false

Errors

422

Unprocessable Entity Error