Goal

This guide explains how to manage customer invoice payment schedules through the Company API when connecting to an ERP or invoicing system to Pennylane.

You will learn how to :

Add a payment schedule when creating a customer service
Add a payment schedule when importing a customer invoice
Update the payment schedule of an existing invoice
Retrieve invoice installments and their statuses

A payment schedule splits the total invoice amount, including tax, into multiple payments with different due dates. It does not create multiple invoices.

✅
End result
Your customer invoice has a payment schedule that you can create, update, and retrieve through the Company API.

Who is this for?
Developers and integrators connecting an ERP or invoicing system to Pennylane.

Before You Get Started

Access requirements

Have access to the Company API and a subscription plan that supports invoices with multiple installments.
Make sure the installments feature is enabled for your company.

Required scopes (Company API)

Scope	Permissions
`customer_invoices:all`	Create and update payment schedules
`customer_invoices:all` or `customer_invoices:readonly`	Retrieve invoice installments

Check feature availability

The installments feature is currently available in alpha and is being rolled out gradually, company by company.

Call GET /company/features and check that the installments field is set to true.

⚠️
Important
Until the feature is enabled, the installments field may be silently ignored when creating, importing, or updating an invoice. Retrieving installments returns a 404 Not Found error.
If your subscription plan does not support multiple installments, the API may return 403 Forbidden: Company does not have access to installments.

Step 1 | Add a Payment Schedule When Creating an Invoice

Use the POST /customer_invoices endpoint to create a customer invoice with a payment schedule.

Prepare your request to POST /customer_invoices.
Add an installments array to the request body.
For each installment, specify:
- deadline: the payment due date.
- amount: the installment amount, including tax.
- payment_methods (optional): the expected payment methods.
Submit the request.
Verify that the invoice and its payment schedule have been created successfully.

✅ Result
The customer invoice is created with the installments specified in your request.

⚠️
Important
The installments array supports between 1 and 60 installments.

To split an invoice payment across multiple due dates, provide at least two installments.

If you provide only one installment, its amount must equal the invoice's total amount, including tax.

Step 2 | Add a Payment Schedule When Importing an Invoice

You can also provide a payment schedule when importing a customer invoice.

The request format depends on the import endpoint.

Import type	Endpoint	Where to provide `installments`
Customer invoice import	`POST /customer_invoices/import`	At the root of the JSON request body
Electronic invoice import (Factur-X, UBL, or CII)	`POST /customer_invoices/e_invoices/imports`	In a separate `multipart/form-data` field, encoded as JSON

To import an invoice with a payment schedule:

Prepare your request using the appropriate endpoint.
Add the installments array with the following fields for each installment:
- deadline: the payment due date.
- amount: the installment amount, including tax.
- payment_methods (optional): the expected payment methods.
Submit the request.
Verify that the imported invoice and its payment schedule have been created successfully.

✅ Result
The imported customer invoice is created with the payment schedule provided in the request.

Step 3 | Update an Existing Invoice Payment Schedule

Use the appropriate update endpoint to add, modify, or delete installments on an existing customer invoice.

Invoice type	Endpoint
Customer invoice	`PUT /customer_invoices/{id}`
Imported customer invoice	`PUT /customer_invoices/{id}/update_imported`

To update a payment schedule:

Prepare your request using the appropriate endpoint.
Add an installments object to the request body.
Use one or more of the following keys, depending on the changes you need to make:

Key	Action	Required information
`create`	Add installments	`deadline`, `amount`, and optionally `payment_methods`
`update`	Update an existing installment	Installment `id` and the fields to update
`delete`	Delete an installment	Installment `id`

Submit the request.
Check the response to confirm that the invoice has been updated.

✅ Result
The invoice's payment schedule reflects the permitted changes submitted through the API.

⚠️
Important
An installment cannot be updated or deleted if it is paid, cancelled, partially paid, partially cancelled, or awaiting funds.
You cannot update the payment schedule of a fully paid invoice or replace multiple installments with a single installment.

Step 4 | Retrieve Invoice Installments

Use GET /customer_invoices/{customer_invoice_id}/installments to retrieve the installments associated with a customer invoice.

Call the endpoint using the customer invoice ID.
Read the fields returned for each installment:

Field	Description
`id`	Installment identifier
`deadline`	Payment due date
`amount`	Installment amount
`currency_amount`	Amount expressed in the invoice currency
`currency`	Currency
`remaining_amount_with_tax`	Outstanding amount, including tax
`status`	Installment status
`payment_methods`	Payment methods associated with the installment

Use the sort parameter to order installments by due date:
- deadline (default): ascending order, from earliest to latest.
- -deadline: descending order, from latest to earliest.
If the response is paginated, use the returned cursor to retrieve subsequent pages. The limit parameter controls the number of results per page (20 by default, up to 100).

Installment statuses

The status field can have one of the following values:

Value	Meaning
`upcoming`	Payment is upcoming
`late`	Payment is overdue
`paid`	Installment is paid
`cancelled`	Installment is cancelled
`waiting_funds`	Payment is awaiting funds

✅ Result
You can retrieve the invoice's installments, their due dates, amounts, remaining balances, payment methods, and statuses.

Validation Rules and Limitations

Before submitting a payment schedule, make sure it meets the following requirements.

Installment amounts

The sum of all installment amounts must equal the invoice's total amount, including tax.
For a partially paid invoice, the sum of the outstanding amounts of active installments must equal the invoice's outstanding balance.
Each installment amount must be strictly greater than zero.

Invoice eligibility

Multiple installments are supported only for invoices issued in euros.
Invoices generated from an invoicing subscription cannot have multiple installments.

Payment method requirements

SEPA direct debit requires a SEPA Creditor Identifier configured for the company.
E-bank transfer requires a Pennylane Business Account with Fintecture enabled.
The Business Account payment link cannot be used for an installment.

Other payment methods may also be subject to eligibility requirements.

Common Errors

Error	Possible cause
`403 Forbidden` — `Company does not have access to installments`	The company subscription does not support multiple installments
`404 Not Found` when retrieving installments	The installments feature has not been enabled for the company
`422 Unprocessable Content`	A payment schedule validation rule has not been met

💡
Tip
Before creating, importing, or updating a payment schedule, check feature availability with GET /company/features and make sure the installment amounts comply with the validation rules.
A 422 Unprocessable Content response may include a message explaining why the request was rejected.