Bill Pending Items

POST

/api/:account_id/invoices/bill-pending-items

Bill pending floating items on-demand. Creates standalone invoice(s) from all pending (floating) invoice items for a customer, finalizes them, and attempts immediate collection.

Floating items are charges created mid-cycle (e.g., SMS usage) that would otherwise be swept into the next subscription renewal invoice. This endpoint provides an off-cycle mechanism to collect these charges immediately.

Behavior:

Items from PAUSED subscriptions are excluded
One invoice is created per currency
If payment fails, the invoice is left OPEN for dunning
Empty response (no invoices) if no pending items exist

Idempotency: Use the Idempotency-Key header to guarantee at-most-once semantics. Without it, duplicate calls will create duplicate invoices.

Bill pending floating items on-demand. Creates standalone invoice(s) from all pending (floating) invoice items for a customer, finalizes them, and attempts immediate collection. Floating items are charges created mid-cycle (e.g., SMS usage) that would otherwise be swept into the next subscription renewal invoice. This endpoint provides an off-cycle mechanism to collect these charges immediately. **Behavior:** - Items from PAUSED subscriptions are excluded - One invoice is created per currency - If payment fails, the invoice is left OPEN for dunning - Empty response (no invoices) if no pending items exist **Idempotency:** Use the `Idempotency-Key` header to guarantee at-most-once semantics. Without it, duplicate calls will create duplicate invoices.

Authentication

AuthorizationBearer

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

Path parameters

account_idstringRequired

Request

This endpoint expects an object.

customer_idstringRequired

ID of the customer whose pending items should be billed

item_idslist of strings or nullOptional

Optional: specific invoice item IDs to sweep. If provided, only these items will be included (must be floating items belonging to this customer). Other filters (subscription_id, currency) are ignored when item_ids is set.

subscription_idstring or nullOptional

Optional: narrow sweep to a single subscription

currencyenum or nullOptional

Optional: if omitted, creates one invoice per currency

tax_amount_atomintegerOptional>=0Defaults to 0

Tax amount to apply (default 0)

discount_idstring or nullOptional

Optional: discount to apply to the invoice

collection_methodstring or nullOptional

Optional: ‘charge_automatically’ or ‘send_invoice’. Defaults to customer’s collection method

descriptionstring or nullOptional

Optional: invoice memo/description

Response

Successful Response

invoiceslist of objectsOptional

Invoices created from pending items (one per currency)

Errors

422

Unprocessable Entity Error

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

1	{
2	"invoices": [
3	{
4	"id": "inv_01F8MECHZX3TBDSZ7XRADM79XV",
5	"currency": "aed",
6	"status": "open",
7	"total_amount_atom": 125000,
8	"items_swept": 3
9	}
10	]
11	}