Payment plans

GET `/v1/customers/{customerId}/payment-plan-terms`

What the customer may be offered

paymentplans:read

Parameter	In	Type	Required	Description
`customerId`	path	`string`	Yes

Request exampleNo request body

curl https://api.rieckflow.com/v1/customers/9b2f1c1e-…/payment-plan-terms \
  -H "Authorization: Bearer $RIECK_API_KEY"

const svar = await rieck.request("GET", "/v1/customers/9b2f1c1e-…/payment-plan-terms");

{
  "data": {}
}

200 eligible, the open invoices a plan would cover (ALL of them — a plan is per customer), the SUGGESTED plans (3/6/12/… within your instalment terms — any instalments from 2 to maxInstalments with an instalment of at least minInstalmentOere is admissible), firstInstalmentDate, maxInstalments, minInstalmentOere. reason is terms_disabled or nothing_admissible when not eligible.application/json

Possible errors 5

HTTP	Code	Meaning
401	`invalid_api_key`	The API key is missing, invalid, expired or revoked.
403	`api_not_included`	The organisation’s plan does not include API access.
403	`insufficient_scope`	The key does not have the required scope.
404	`customer_not_found`	The customer does not exist or belongs to another organisation.
429	`rate_limited`	The organisation’s rate budget is exhausted.

GET `/v1/payment-plans`

List payment plans

paymentplans:read

Parameter	In	Type	Required	Description
`status`	query	`string`	No	proposed \| active \| fulfilled \| defaulted \| cancelled
`customerId`	query	`string`	No	Filter by customer
`limit`	query	`integer`	No	Page size, 1-200 (default 50)
`cursor`	query	`string`	No	Opaque cursor from meta.nextCursor

Request exampleNo request body

curl https://api.rieckflow.com/v1/payment-plans \
  -H "Authorization: Bearer $RIECK_API_KEY"

const svar = await rieck.request("GET", "/v1/payment-plans");

{
  "data": [
    {}
  ],
  "meta": {
    "nextCursor": null
  }
}

200 Success envelopeapplication/json

Possible errors 5

HTTP	Code	Meaning
400	`invalid_cursor`	The cursor is malformed, expired or belongs to another list shape.
401	`invalid_api_key`	The API key is missing, invalid, expired or revoked.
403	`api_not_included`	The organisation’s plan does not include API access.
403	`insufficient_scope`	The key does not have the required scope.
429	`rate_limited`	The organisation’s rate budget is exhausted.

POST `/v1/payment-plans`

Propose a payment plan

paymentplans:write

Creates a PROPOSAL (proposed) covering the customer’s whole open balance. You send only instalments; amounts are computed from the balance and your terms and recomputed by the database. At most one live plan per customer (409 payment_plan_conflict). The plan becomes active only when the customer signs the debt acknowledgement (MitID) — never through the API. Sending the agreement for signature is done from the portal for now.

Request body fields 5

Field	Type	Required	Description
`customerId`	`string`	Yes	The customer this resource belongs to.
`instalments`	`integer`	Yes	Field in the request payload.
`note`	`string`	No	Field in the request payload.
`replyBy`	`string`	No	Field in the request payload.
`offerAutopay`	`boolean`	No	Field in the request payload.

Request exampleapplication/json

curl -X POST https://api.rieckflow.com/v1/payment-plans \
  -H "Authorization: Bearer $RIECK_API_KEY" \
  -H "Idempotency-Key: order-2041" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "9b2f1c1e-…",
    "instalments": 1,
    "offerAutopay": true
  }'

const svar = await rieck.request("POST", "/v1/payment-plans", {
  body: {
    "customerId": "9b2f1c1e-…",
    "instalments": 1,
    "offerAutopay": true
  },
});

{
  "data": {}
}

201 The plan; customerUrl is the customer’s own page — treat it as a secret.application/json

Possible errors 9

HTTP	Code	Meaning
400	`invalid_idempotency_key`	Idempotency-Key is missing or malformed.
400	`invalid_request`	The request body or parameter failed validation.
401	`invalid_api_key`	The API key is missing, invalid, expired or revoked.
403	`api_not_included`	The organisation’s plan does not include API access.
403	`insufficient_scope`	The key does not have the required scope.
409	`idempotency_conflict`	The same key was used with a different request.
409	`idempotency_in_progress`	The same operation is currently being processed. Retry later.
413	`payload_too_large`	The JSON or uploaded file exceeds this endpoint’s size limit.
429	`rate_limited`	The organisation’s rate budget is exhausted.

Request body — fuldt JSON Schema

{
  "type": "object",
  "properties": {
    "customerId": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "instalments": {
      "type": "integer",
      "minimum": 2,
      "maximum": 120
    },
    "note": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 2000
        },
        {
          "type": "null"
        }
      ]
    },
    "replyBy": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
        },
        {
          "type": "null"
        }
      ]
    },
    "offerAutopay": {
      "default": false,
      "type": "boolean"
    }
  },
  "required": [
    "customerId",
    "instalments"
  ],
  "additionalProperties": false
}

GET `/v1/payment-plans/{planId}`

Get payment plan

paymentplans:read

Parameter	In	Type	Required	Description
`planId`	path	`string`	Yes

Request exampleNo request body

curl https://api.rieckflow.com/v1/payment-plans/9b2f1c1e-… \
  -H "Authorization: Bearer $RIECK_API_KEY"

const svar = await rieck.request("GET", "/v1/payment-plans/9b2f1c1e-…");

{
  "data": {}
}

200 Covered invoices, the schedule, cumulative progress while active, and remindersPaused — the reminder chain on the covered invoices sleeps while the plan is active. No card fields, ever.application/json

Possible errors 4

HTTP	Code	Meaning
401	`invalid_api_key`	The API key is missing, invalid, expired or revoked.
403	`api_not_included`	The organisation’s plan does not include API access.
403	`insufficient_scope`	The key does not have the required scope.
429	`rate_limited`	The organisation’s rate budget is exhausted.

POST `/v1/payment-plans/{planId}/close`

Close the plan

paymentplans:write

outcome: cancelled (you withdraw it), defaulted (the customer stopped paying) or fulfilled. This is where the reminder chain wakes up: the paused days are booked on the covered invoices and the clock continues where it stopped. 422 payment_plan_not_live for an already closed plan.

Parameter	In	Type	Required	Description
`planId`	path	`string`	Yes

Request body fields 2

Field	Type	Required	Description
`outcome`	`string`	Yes	Field in the request payload.
`note`	`string`	No	Field in the request payload.

Request exampleapplication/json

curl -X POST https://api.rieckflow.com/v1/payment-plans/9b2f1c1e-…/close \
  -H "Authorization: Bearer $RIECK_API_KEY" \
  -H "Idempotency-Key: order-2041" \
  -H "Content-Type: application/json" \
  -d '{
    "outcome": "cancelled"
  }'

const svar = await rieck.request("POST", "/v1/payment-plans/9b2f1c1e-…/close", {
  body: {
    "outcome": "cancelled"
  },
});

{
  "data": {}
}

200 The closed plan; meta.invoicesResumed.application/json

Possible errors 9

HTTP	Code	Meaning
400	`invalid_idempotency_key`	Idempotency-Key is missing or malformed.
400	`invalid_request`	The request body or parameter failed validation.
401	`invalid_api_key`	The API key is missing, invalid, expired or revoked.
403	`api_not_included`	The organisation’s plan does not include API access.
403	`insufficient_scope`	The key does not have the required scope.
409	`idempotency_conflict`	The same key was used with a different request.
409	`idempotency_in_progress`	The same operation is currently being processed. Retry later.
413	`payload_too_large`	The JSON or uploaded file exceeds this endpoint’s size limit.
429	`rate_limited`	The organisation’s rate budget is exhausted.

Request body — fuldt JSON Schema

{
  "type": "object",
  "properties": {
    "outcome": {
      "type": "string",
      "enum": [
        "cancelled",
        "defaulted",
        "fulfilled"
      ]
    },
    "note": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 500
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "outcome"
  ],
  "additionalProperties": false
}

GET `/v1/invoices/{invoiceId}/payment-plan`

The live plan covering this invoice

paymentplans:read

Parameter	In	Type	Required	Description
`invoiceId`	path	`string`	Yes

Request exampleNo request body

curl https://api.rieckflow.com/v1/invoices/9b2f1c1e-…/payment-plan \
  -H "Authorization: Bearer $RIECK_API_KEY"

const svar = await rieck.request("GET", "/v1/invoices/9b2f1c1e-…/payment-plan");

{
  "data": {}
}

200 The proposed or active plan that covers the invoice — the pause made readable per invoice. 404 payment_plan_not_found when the cadence is running normally.application/json

Possible errors 5

HTTP	Code	Meaning
401	`invalid_api_key`	The API key is missing, invalid, expired or revoked.
403	`api_not_included`	The organisation’s plan does not include API access.
403	`insufficient_scope`	The key does not have the required scope.
404	`invoice_not_found`	The invoice does not exist or belongs to another organisation.
429	`rate_limited`	The organisation’s rate budget is exhausted.

Payment plans

GET /v1/customers/{customerId}/payment-plan-terms

GET /v1/payment-plans

POST /v1/payment-plans

GET /v1/payment-plans/{planId}

POST /v1/payment-plans/{planId}/close

GET /v1/invoices/{invoiceId}/payment-plan

GET `/v1/customers/{customerId}/payment-plan-terms`

GET `/v1/payment-plans`

POST `/v1/payment-plans`

GET `/v1/payment-plans/{planId}`

POST `/v1/payment-plans/{planId}/close`

GET `/v1/invoices/{invoiceId}/payment-plan`