Creates a Settlement resource.

This endpoint creates a settlement (payment arrangement) on a collection order. A settlement defines a schedule of one or more terms that the debtor will pay over time. Once started, the collection order transitions to status settlement and the regular flow is replaced by the settlement schedule. ### 1. Settlement profile A SettlementProfile defines the policy rules a settlement must respect (term count, minimum amount, failure-handling strategies, etc.). Profiles are configured in the Collect Portal. | Field | Description | Usage | |-------|-------------|-------| | settlement_profile_id | Identifier of the profile to use. Discoverable via GET /v3/settlement_profiles. | optional | If omitted, the client's default profile (the one marked is_default = true) is used. If neither is provided nor exists, the request is rejected with 400. ### 2. Terms The terms array describes the payment schedule. At least one term is required. | Field | Description | |-------|-------------| | term_number | Position of the term in the schedule. Must be dense and sequential starting from 1 (1, 2, 3, ...). | | amount | Amount due for the term, in the currency's minor unit. Must be positive. | | send_at | ISO 8601 datetime (with timezone) at which the term's message is sent to the debtor. | | due_date | Date (YYYY-MM-DD) by which the term must be paid. | ### 3. Validation rules - term_number values are dense and sequential starting at 1. - amount is a positive integer. - send_at must not be in the past; due_date must not be in the past. - due_date must be on or after send_at for each term. - The next term's send_at must be strictly after the previous term's due_date (no overlap between terms). - The sum of all term amounts must equal the collection order's outstanding amount. - The term count and per-term amount must respect the profile's min_term_count, max_term_count, and min_term_amount (when configured). ### 4. Preconditions - The collection order must exist and belong to the authenticated client. - The collection order's status must be active. Orders in any other status (e.g. paid, pause, withdraw, cancel, settlement, merged, end) are rejected. - The collection order must not already have an active settlement. A prior lapsed, done, or cancelled settlement is replaced automatically; an active one returns 409 Conflict. ### 5. Errors | Code | When | |------|------| | 400 | Business rule failure (profile resolution, profile term rules, sum mismatch, status precondition). | | 404 | The collection order does not exist or does not belong to your account. | | 409 | The collection order already has an active settlement. | | 422 | Validation failure of the input shape (term sequence, amounts, dates). | ### 6. Response The response mirrors the GET /v3/collection_orders/{id}/settlement shape: it contains the created settlement's settlement_id, status, profile id, creation timestamp, and the full term schedule (with each term in status pending).