Instalment Plans Use Case

An instalment plan lets a customer settle several open claims over a schedule of monthly payments instead of one lump sum. Receive computes the offer from the customer's own claims, tracks the schedule, and reconciles every payment back to the underlying invoices for you.

Before you start: the offer is configured by us

You cannot create an instalment plan definition through the API. The definition — how many instalments, how the amounts are computed, what you ask the customer, what they are allowed to change — is configured per client by InDebted. Until one exists for your client, instalment_plan_definitions returns an empty list and nothing else on this page will work.

Contact your InDebted representative to have a definition set up. Tell us what the offer should look like:

• how many instalments, and how each amount should be derived from the balance
• what you want to ask the customer first, and how their answers should change the offer — see The form is yours to define
• whether the customer may move a due date themselves
• how many days late an instalment may be before the plan cancels

We configure it, and you then drive it through the three calls below. Once your definitions exist you can choose between them yourself, including which one a landing page offers a given customer.

Be sure to include the Authorization header with the Bearer authentication scheme and the access_token as the credentials. The access_token is provided by the authentication request.

The flow

Three calls, in order. The middle one is the part people get wrong.

1. List the definitions configured for your client, and pick one.
2. Compute that definition against a specific account and set of claims. This runs the offer and stores the result as a new definition with its own id.
3. Create the plan from the computed id — not the one you listed.

The instalment endpoints live under /finance/v1/{clientId}/..., not /v1/{clientId}/... like the account and claim endpoints.

1. List the definitions

GET /finance/v1/3d132b18-6b6f-4f7c-b464-6a8ee7ca5235/instalment_plan_definitions HTTP/1.1
Host: api.receive-demo.com
Authorization: {{access_token}}

{
  "success": true,
  "data": {
    "results": [
      {
        "id": "f88994f7-8d97-4259-837c-3686db10037f",
        "type": "programmatic",
        "description": { "en_US": "Spread arrears over monthly payments" }
      }
    ]
  }
}

This endpoint is client-wide. It takes limit and paginationId only — passing accountReference is rejected with query should NOT have additional properties. (instalment_plans, further down, is the opposite: there accountReference is required.)

2. Compute the offer

POST /finance/v1/3d132b18-6b6f-4f7c-b464-6a8ee7ca5235/compute_instalment_plan_definition HTTP/1.1
Host: api.receive-demo.com
Content-Type: application/json
Authorization: {{access_token}}

{
  "instalmentPlanDefinitionId": "f88994f7-8d97-4259-837c-3686db10037f",
  "accountReference": "ACCOUNT_REFERENCE_001",
  "externalClaimReferences": [
    "ACCOUNT_REFERENCE_001-INVOICE_A_JUN",
    "ACCOUNT_REFERENCE_001-INVOICE_B_JUN",
    "ACCOUNT_REFERENCE_001-INVOICE_A_JUL"
  ],
  "form": { "mobileNumber": "+4915100000001" }
}

{
  "success": true,
  "data": {
    "id": "b2b9241a-da1a-4f5c-b373-2612fed03c06",
    "type": "fixedAmounts",
    "configuration": [
      { "amount": 10269, "date": "2026-09-15" },
      { "amount": 10269, "date": "2026-10-15" },
      { "amount": 10269, "date": "2026-11-15" }
    ]
  }
}

data.configuration is the offer to show the customer. data.id is what you pass to create_instalment_plan.

externalClaimReferences is required. Without it the call fails with Invalid Context to Compute Instalment Plan Definition, however well-formed the rest is.

Check data.type before continuing. A successful compute returns a concrete offer such as fixedAmounts. If it comes back as programmatic — the same type as the definition you asked for — the offer did not compute, usually because a value the form requires was missing or sent under the wrong key. The call still returns 200 with success: true, and the problem only surfaces at the next step as Instalment plan definition is not a fixed amount definition.

Compute is safe to repeat. Call it again each time the customer changes an input, and use the id from the last response.

The form is yours to define

A definition can declare a form: a set of fields you specify, asked of the customer before the offer is computed. The fields are whatever your process needs — a first payment date, a mobile number, a reason for falling behind, how much they can afford this month — and you send the answers under form when you compute.

Those answers feed the offer. The definition can read them and decide what to return, so the plan a customer is shown can depend on what they told you: a date they chose becomes the schedule's anchor, an affordability figure selects a longer arrangement, an answer about their circumstances routes them to a different set of options entirely. The form is not just data capture bolted onto the front — it is an input to the calculation.

That also makes the form a natural wizard. Compute after each answer, show the customer what it produces, and compute again when they change their mind. Only the last computed id needs to reach create_instalment_plan.

Tell us the fields and how they should shape the offer when you ask us to set the definition up. Anything you send outside instalmentPlanDefinitionId and accountReference is passed through as context, so form sits at the top level of the request body alongside them.

What you can build with this

The offer is computed from two things: the customer's own claims, and whatever you asked them. That is enough for most arrangements a collections team actually wants. Some shapes clients run today:

A choice of arrangements. Compute returns several options and the customer picks one — settle now at a discount, spread over twelve months at a smaller discount, or spread over thirty-six at none. The discount is expressed in the offer, so what the customer accepts is what they are held to.

Sized by what they can afford. Ask what they can manage each month, and let that decide the length rather than fixing the number of instalments. Two customers with the same balance get different schedules because they told you different things.

A schedule anchored on their payday. Ask for a first payment date and build the run of monthly dates from it, so every instalment falls when money is actually in the account.

Covering what is still falling due. For subscriptions or rentals, the arrangement can cover the arrears and the charges that will fall due while it runs, so the customer makes one payment a month that both clears the backlog and keeps the current period paid. This needs care about what the balance in Receive will be by the middle of the plan — talk to us about it rather than assuming.

Only part of the debt. Bring specific claims into the plan and leave the others out, so a disputed invoice or a product still in use is not swept into an arrangement.

A settlement. A single reduced payment, or a short run of them, in full and final satisfaction. Mechanically the same flow.

Routing on circumstances. Ask why they have fallen behind and branch: a customer who says their situation is temporary can be shown a short arrangement, one who says otherwise can be routed to a longer one or to a human, without either seeing an offer that will not work for them.

These are configuration, not development — the whole shape lives in the definition we set up for you. If the arrangement you want is not on this list, describe it to us and we will tell you whether it fits.

3. Create the plan

POST /finance/v1/3d132b18-6b6f-4f7c-b464-6a8ee7ca5235/create_instalment_plan HTTP/1.1
Host: api.receive-demo.com
Content-Type: application/json
Authorization: {{access_token}}

{
  "instalmentPlanDefinitionId": "b2b9241a-da1a-4f5c-b373-2612fed03c06",
  "accountReference": "ACCOUNT_REFERENCE_001"
}

{
  "success": true,
  "messages": ["Successfully created instalment plan"],
  "data": {
    "id": "43531835-27cf-4a53-9e0f-dc0c17686e0d",
    "status": "ACTIVE",
    "totalAmount": 61614
  }
}

instalmentPlanDefinitionId here is the id returned by compute, not the one you listed in step 1. They are different records. Passing the wrong one gives Instalment plan definition is not a fixed amount definition.

An account holds one active plan over a given claim. A second attempt returns Cannot create a new ComputedInstalmentPlanDefinition with a Claim that is the context of an Active Instalment Plan from that Account.

Depending on how your definition is configured, creating the plan can also stop collections activity on the claims it covers, so the customer is not chased for something they have just committed to.

Reading the plan back

GET /finance/v1/3d132b18-6b6f-4f7c-b464-6a8ee7ca5235/instalment_plans?accountReference=ACCOUNT_REFERENCE_001 HTTP/1.1
Host: api.receive-demo.com
Authorization: {{access_token}}

Choosing which plan a Landing Page offers

The three calls above are how you create a plan. When you send a customer to a Receive landing page, the customer creates it, and the page offers them one of your definitions. This is how you choose which one.

POST /landing_page/v1/3d132b18-6b6f-4f7c-b464-6a8ee7ca5235/set_instalment_plan_definition HTTP/1.1
Host: api.receive-demo.com
Content-Type: application/json
Authorization: {{access_token}}

{
  "claimReference": "ACCOUNT_REFERENCE_001-INV-2024-0042",
  "instalmentPlanDefinitionId": "0b1f79e6-b7a4-4674-b40b-b7e27b5ed7d3"
}

{
  "success": true,
  "messages": [
    "Successfully set instalment plan definition 0b1f79e6-b7a4-4674-b40b-b7e27b5ed7d3 for claim ACCOUNT_REFERENCE_001-INV-2024-0042"
  ],
  "messageIds": ["a1183bf5-4f0d-4eb7-8786-14a4d2a0b848"]
}

This endpoint lives under /landing_page/v1/{clientId}/..., not /finance/v1/... or /v1/....

Use the id you listed in step 1, not the one compute returns. The page runs the compute itself, so it needs the template.

The definition has to be yours and it has to be enabled. Both are checked before anything changes:

what you send	answer
an id that does not exist, or belongs to another client	404 — Instalment Plan Definition Not Found
one of yours that is switched off	400 — Instalment plan definition is not enabled

A wrong id would otherwise leave the page offering nothing at all, and you would find out from the customer rather than from the call.

It applies to one claim. The setting is stored against the claim, so point a portfolio at a definition by calling this once per claim. There is no client-wide equivalent.

This setting is not permanent

A dunning journey can overwrite it. The endpoint writes the same per-claim page settings that a journey step writes, so if the customer's journey later runs a step that touches those settings, your choice is replaced by whatever that step sets.

Treat it as something you apply close to the moment you direct the customer to the page, not as a permanent piece of configuration. If a setting you made earlier appears to have vanished, this is why. To fix which offer a page shows for good, ask us to change the definition configured for the client.

What a plan looks like

A plan after its first instalment has been paid, trimmed to the fields you will use:

{
  "id": "43531835-27cf-4a53-9e0f-dc0c17686e0d",
  "status": "ACTIVE",
  "type": "fixedAmounts",
  "currency": "EUR",
  "totalAmount": 61614,
  "paidAmount": 10269,
  "externalClaimRef": "43531835-27cf-4a53-9e0f-dc0c17686e0d",
  "accountId": "ACCOUNT_REFERENCE_001",
  "instalments": [
    {
      "id": "46382f4e-87da-49f1-8f83-b634eb1c871d",
      "amount": 10269,
      "paidAmount": 10269,
      "dueDate": "2026-09-15",
      "startDate": "2026-09-09",
      "currency": "EUR",
      "status": "RESOLVED"
    },
    {
      "id": "9f1c07a2-4c0e-4d7a-bb3e-2a8d5e6f1b40",
      "amount": 10269,
      "paidAmount": 0,
      "dueDate": "2026-10-15",
      "startDate": "2026-09-15",
      "currency": "EUR",
      "status": "STARTED"
    }
  ],
  "scope": {
    "externalClaimReferences": ["ACCOUNT_REFERENCE_001-INVOICE_A_JUN", "..."],
    "externalClaimAmounts": [{ "amount": 3390, "totalFees": 594, "fees": [] }],
    "externalProductReferences": ["CONTRACT_A", "CONTRACT_B"],
    "form": { "mobileNumber": "+4915100000001" }
  },
  "createdAt": "2026-09-09T15:31:49.151Z",
  "updatedAt": "2026-09-09T17:16:31.201Z",
  "statusCheckedAt": "2026-09-09T17:16:31.201Z"
}

The plan itself

Field	Means
status	ACTIVE while it runs, then RESOLVED when fully paid, INVALIDATED when it cancels through non-payment, CANCELLED when cancelled outright
totalAmount	the sum of the instalments — what the customer committed to pay, which is not necessarily the balance they owed
paidAmount	money received against the plan so far
externalClaimRef	the plan's own claim. A plan creates a claim representing the whole arrangement, and its reference is the plan's id. This is what you credit to pay the plan rather than an individual invoice
statusCheckedAt	when the schedule was last evaluated. Plans are reviewed daily

Each instalment

Field	Means
amount	what is due on this instalment
paidAmount	how much of it is covered. Money fills instalments in due-date order, so a part-payment shows up here
dueDate	when it is due
startDate	when it became the instalment being collected — the previous one's due date
status	CREATED not yet reached, STARTED currently due, RESOLVED covered, INVALIDATED missed

scope is the context the offer was computed from, kept with the plan so you can see what it was based on:

Field	Means
externalClaimReferences	the claims this plan covers
externalClaimAmounts	what each of those claims owed at the moment the plan was created, principal and fees. This is the baseline payments are reconciled against, so it does not change as the plan is paid
externalProductReferences	the products or contracts those claims belong to
form	the answers the customer gave, exactly as you sent them — see The form is yours to define

The full scope also carries a snapshot of the claims and debtor references the offer was computed from. Treat externalClaimAmounts as the authoritative baseline and the rest as context.

How payments reconcile

A plan creates its own claim representing the whole arrangement. Payments work from either side, and you do not have to choose.

Paying the plan reduces the original claims. Money paid against the plan's claim is spread across the claims the plan covers, oldest due date first, fees before principal. The claim the payment stops in keeps the correct residual. A payment of 205.38 against six invoices of 33.90 plus a 5.94 fee settles the first five outright and leaves 3.96 on the sixth.

Paying an original claim counts towards the plan. Credit any claim the plan covers and the amount registers against the plan and fills its instalments in due-date order. It does not matter which invoice was paid.

If your account is ledger-managed — you push invoices as Ledger Entries — note that crediting claims does not write payment Ledger Entries for you. Receive tells you what happened through the webhooks below; posting the corresponding entries on your side remains yours to do.

Webhooks

Subscribe to these to follow a plan and reconcile its payments:

Event	What it tells you
event.instalmentPlan.created.v2	a customer accepted a plan, with the full schedule
event.instalmentPlan.updated.v2	any change to the plan or its instalments
event.instalmentPlan.invalidated.v2	the plan cancelled, typically a missed instalment
event.instalmentPlan.resolved.v2	the plan completed
event.instalmentPlan.cancelled.v2	the plan cancelled explicitly
event.claim.credited.v1	every partial credit applied to a claim, with the amount
event.claim.resolved.v1	a claim closed by those credits

event.claim.credited.v1 is the one to be sure about. An instalment usually settles some invoices outright and part-pays the next one. event.claim.resolved.v1 tells you about the first group and says nothing about the last, so on its own it under-reports every payment that does not land on a claim boundary.

If a definition is configured to keep a plan alive for a few days after a missed instalment, the plan's own paidAmount can lag during that window — it catches up once the instalment is covered. The claim events are accurate throughout, which is the other reason to subscribe to them rather than reconcile from the plan totals.

Plan events do not repeat. The daily status check writes nothing when there is nothing new, so a payment produces one set of events, not one per day.

See the Webhook Validation Use Case for verifying signatures, and the list of webhooks for the full catalogue.

Notes

• Amounts are in cents throughout, as everywhere else in the API.
• Claim references for ledger-managed accounts are <accountReference>-<ledgerEntryReference>.
• A claim's amount does not shrink when it is paid. Payments are recorded separately and the claim's status becomes RESOLVED once covered, so read the status rather than diffing the amount.
• There is no endpoint that advances a plan through time. To exercise later instalments in a demo environment, ask us — we can move a test plan's schedule for you.
• Whether the customer may move a due date themselves is part of the definition. Where it is switched off, the attempt is rejected rather than silently ignored.

FAQ

• How can I get an Access Token? You can get a token using the Authentication Use Case
• How do I get an instalment plan definition created? Contact your InDebted representative. Definitions are configured by us per client and cannot be created through the API. Choosing between the ones you already have is yours to do, including which one a landing page offers.
• Can we control which plan a customer is offered on their landing page? Yes, per claim, with set_instalment_plan_definition. The id must be one of yours and enabled. Note that a dunning journey step can overwrite it later, so apply it close to when you send the customer to the page.
• Compute returned 200 and success: true, but create says it is "not a fixed amount definition". The offer did not actually compute. Check data.type on the compute response: if it still shows the definition's own type, a value the definition's form requires was missing or sent under the wrong key. Send form values under form.
• Which id does create_instalment_plan take? The data.id from the compute response. The id you passed into compute is the template, not the offer.
• Can we ask the customer something before showing them a plan? Yes. A definition can declare a form of your own fields, and the answers are an input to the offer, so what you ask can change what the customer is shown. Tell us the fields and the logic when you ask us to set the definition up.
• Can we offer different plans to different customers? Yes, on two axes: the offer is computed from the customer's own claims, and it can branch on their form answers. Someone who says they can afford more can be shown a shorter arrangement than someone who cannot.
• Can a customer have two plans at once? Not over the same claims. Resolve or cancel the existing plan first.
• The customer paid one of the original invoices directly. Does the plan know? Yes. Any credit to a claim the plan covers registers against the plan.
• Do I need to send updated claim balances after a payment? No. Crediting the plan updates the underlying claims itself. Sending recomputed balances for the same payment would apply it twice.
• How do I know which invoices a payment settled? From event.claim.credited.v1 for the amounts applied, and event.claim.resolved.v1 for the ones it closed.

Related Pages

• Register Payments Use Case
• Allocate Account Payment Use Case
• Get Account Claims Use Case
• Webhook Validation Use Case