Create payment allocations
Applies a posted payment to one or more invoice lines. Each allocation names a line (invoiceLineId, from List an invoice's lines) and an amount in integer minor units, no more than that line's balanceAmount, and no more than what's left to pay on its invoice: the invoice's total less what's already allocated to it, since its credit lines take their share off the total (400 otherwise); together they can't exceed the payment's balance (409 CONFLICT). The lines must be on posted, unpaid invoices of the payment's customer, in the payment's currency (400 otherwise), and a draft or failed payment can't be allocated (400). The request is all or nothing: if any allocation is refused, none is made. When an invoice's allocations reach its total, or its last line is settled, the invoice becomes paid (credit lines, such as discounts and adjustments, already take their share off the total, so the charges' lines needn't each be paid in full). An invoice Stripe issued or is collecting is first marked paid outside Stripe there, so Stripe stops collecting; if Stripe refuses, the request answers 400 INVALID_REQUEST with Stripe's message and nothing changes. Once paid, its paymentStatus turns paid, credits the order grants on payment become available, a receipt is emailed when the order sends payment emails, and billing-invoice-paid is sent (billing-payment-succeeded was sent when the payment was recorded). An invoice settled in part becomes partiallyPaid. 404 when the payment or a line doesn't exist. Responds 201 with the allocations made, in the order you sent them.
Body·
- Type: array of object 1…allocationsrequiredProperties: 3
One entry per invoice line to settle. All are made, or none.
- Type: stringpayment
Id requiredThe posted payment to allocate.
Responses
- application/json
- application/json
- application/json
- application/json
curl https://billing.getspondo.com/api/v1/payment-allocations \
--request POST \
--header "Authorization: Bearer $SPONDO_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"paymentId": "pay_6Nc1Rf8Hs3Kd9Vg4",
"allocations": [
{ "invoiceLineId": "inv_3Rk8Wq1Zp6Ty0Xm2-0", "amount": 10692 },
{ "invoiceLineId": "inv_3Rk8Wq1Zp6Ty0Xm2-1", "amount": 1296, "currency": "USD" }
]
}'
{
"data": [
{
"id": "pal_9Df2Gh5Jk8Lm1Np3",
"paymentId": "pay_6Nc1Rf8Hs3Kd9Vg4",
"invoiceId": "inv_3Rk8Wq1Zp6Ty0Xm2",
"invoiceLineId": "inv_3Rk8Wq1Zp6Ty0Xm2-0",
"amount": 10692,
"currency": "USD",
"type": "allocated",
"status": "applied",
"allocationDate": "2026-11-10T09:15:22.104Z",
"createdAt": "2026-11-10T09:15:22.104Z"
},
{
"id": "pal_4Qr7St0Uv3Wx6Yz9",
"paymentId": "pay_6Nc1Rf8Hs3Kd9Vg4",
"invoiceId": "inv_3Rk8Wq1Zp6Ty0Xm2",
"invoiceLineId": "inv_3Rk8Wq1Zp6Ty0Xm2-1",
"amount": 1296,
"currency": "USD",
"type": "allocated",
"status": "applied",
"allocationDate": "2026-11-10T09:15:22.104Z",
"createdAt": "2026-11-10T09:15:22.104Z"
}
]
}