Set the payment plan of an invoice
Splits the amount due into dated installments, replacing any existing plan. Send an empty list to remove the plan. On an issued invoice, installments that are already paid cannot change.
Splits the amount due into dated installments, replacing any existing plan. Send an empty list to remove the plan. On an issued invoice, installments that are already paid cannot change.
Authorization
api-key API key for merchant integrations. Send as Authorization: Bearer <your key>.
In: header
Path Parameters
Invoice ID
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X PUT "https://example.com/invoices/string/installments" \ -H "Content-Type: application/json" \ -d '{ "installments": [ { "amount": 1, "dueDate": "string" } ] }'{ "id": "in_3Nf8a2kLmPq9", "object": "invoice", "merchantId": "string", "livemode": true, "status": "draft", "displayStatus": "draft", "number": "INV-000127", "collectionMethod": "send_invoice", "billingReason": "manual", "currency": "EGP", "customerId": "string", "customerName": "string", "customerEmail": "string", "customerPhone": "string", "issueDate": "string", "dueDate": "string", "daysUntilDue": -9007199254740991, "isOverdue": true, "daysOverdue": -9007199254740991, "total": -9007199254740991, "amountDue": -9007199254740991, "amountPaid": -9007199254740991, "amountRemaining": -9007199254740991, "statusTransitions": { "finalizedAt": "string", "paidAt": "string", "markedUncollectibleAt": "string", "voidedAt": "string" }, "sentAt": "string", "firstViewedAt": "string", "automaticallyFinalizesAt": "string", "createdAt": "string", "updatedAt": "string", "customerAddress": { "line1": "string", "line2": "string", "city": "string", "state": "string", "postalCode": "string", "country": "string", "property1": null, "property2": null }, "customerShipping": { "line1": "string", "line2": "string", "city": "string", "state": "string", "postalCode": "string", "country": "string", "property1": null, "property2": null }, "customerTaxIds": [ { "type": "string", "value": "string" } ], "customerLocale": "ar", "accountName": "string", "accountTaxNumber": "string", "subtotal": -9007199254740991, "totalDiscountAmounts": [ { "amount": -9007199254740991, "name": "string" } ], "subtotalExcludingTax": -9007199254740991, "totalExcludingTax": -9007199254740991, "totalTaxes": [ { "amount": -9007199254740991, "taxableAmount": -9007199254740991, "taxBehavior": "exclusive", "taxRateDetails": {} } ], "amountShipping": -9007199254740991, "shippingCost": { "amountSubtotal": -9007199254740991, "amountTax": -9007199254740991, "amountTotal": -9007199254740991, "taxRateIds": [ "string" ] }, "startingBalance": -9007199254740991, "endingBalance": -9007199254740991, "prePaymentCreditNotesAmount": -9007199254740991, "postPaymentCreditNotesAmount": -9007199254740991, "amountOverpaid": -9007199254740991, "description": "string", "footer": "string", "customFields": [ { "name": "string", "value": "string" } ], "discounts": [ { "type": "percent", "percent": 0, "amount": -9007199254740991, "name": "string", "couponId": "string", "appliedAmount": -9007199254740991 } ], "defaultTaxRateIds": [ "string" ], "lines": [ { "id": "il_3Nf8a2kLmPq9", "object": "line_item", "position": -9007199254740991, "description": "string", "quantity": 0, "unitLabel": "string", "pricing": { "priceDetails": {} }, "period": {}, "discounts": [ null ], "taxRateIds": [ null ], "inheritsDefaultTaxRates": true, "subtotal": -9007199254740991, "discountAmounts": [ {} ], "amount": -9007199254740991, "taxes": [ null ], "amountExcludingTax": -9007199254740991, "amountTotal": -9007199254740991, "metadata": {} } ], "installments": [ { "id": "inst_3Nf8a2kLmPq9", "object": "invoice_installment", "position": -9007199254740991, "description": "string", "amountDue": -9007199254740991, "amountPaid": -9007199254740991, "dueDate": "string", "status": "open" } ], "payments": [ { "id": "inpay_3Nf8a2kLmPq9", "object": "invoice_payment", "invoiceId": "string", "status": "open", "amountRequested": -9007199254740991, "amountPaid": -9007199254740991, "amountRefunded": -9007199254740991, "currency": "EGP", "payment": { "paymentRecord": {} }, "statusTransitions": {}, "installmentId": "string", "receiptNumber": "string", "receiptUrl": "string", "merchantId": "string", "createdAt": "string", "updatedAt": "string" } ], "paymentSettings": { "paymentMethodTypes": [ "card" ] }, "allowPartialPayments": true, "minimumPartialAmount": -9007199254740991, "locale": "auto", "pdfLanguage": "ar", "delivery": { "channels": [ "email" ], "additionalRecipients": [ "string" ], "message": "string" }, "autoAdvance": true, "templateId": "string", "fromInvoice": { "action": "revision", "invoiceId": "string" }, "latestRevisionId": "string", "hostedInvoiceUrl": "string", "hostedInvoiceUrlExpiresAt": "string", "metadata": { "property1": null, "property2": null }}Replace the link of an invoice POST
Creates a new link to the invoice page. The old link stops working at once.
Attach a payment to an invoice POST
Records money you received outside XPay, such as cash or a cheque, and adds it to the invoice's payments. No money moves. An amount above what remains becomes credit for the customer.