API REFERENCE
Dunning and tax
Two settings that decide what a failed payment costs and what an invoice must show: the retry policy, and the tax rates applied by country and use case.
Dunning policy
One policy per merchant. It is created with defaults the first time it is read.
| Method | Path | Purpose | Permission |
|---|---|---|---|
| GET | /merchants/:merchantId/dunning-policy | Read the policy, creating defaults if needed. | subscriptions:read |
| PATCH | /merchants/:merchantId/dunning-policy | Update attempts, schedule, grace period and final action. | subscriptions:write |
| Field | Type | Required | Notes |
|---|---|---|---|
| enabled | boolean | No | — |
| maxAttempts | integer | No | 1 to 10. |
| retryScheduleHours | integer[] | No | 1 to 10 values, each between 1 and 720 hours. The last value repeats. |
| gracePeriodDays | integer | No | 0 to 90 days. |
| finalAction | mark_unpaid | cancel | restrict | No | — |
Tax rates
Rates are merchant-scoped and can be limited by country, region, priority and validity dates.
| Method | Path | Purpose | Permission |
|---|---|---|---|
| GET | /merchants/:merchantId/tax-rates | List configured rates. | tax:read |
| POST | /merchants/:merchantId/tax-rates | Create a rate with type and use-case gates. | tax:write |
| PATCH | /merchants/:merchantId/tax-rates/:taxRateId | Update a rate. | tax:write |
| DELETE | /merchants/:merchantId/tax-rates/:taxRateId | Archive a rate. | tax:write |
| POST | /merchants/:merchantId/tax-rates/import-defaults | Seed a country template such as NG or KE. | tax:write |
| GET | /platform/metadata/tax-jurisdictions | Available templates and their notes. | — |
| Field | Type | Required | Notes |
|---|---|---|---|
| name | string | Yes | — |
| countryCode | string | Yes | ISO 3166-1 alpha-2. |
| regionCode | string | No | — |
| rate | string | No | Decimal string, for example "7.5". |
| taxType | vat | gst | sales_tax | consumption_tax | service_tax | withholding | none | No | — |
| compound | boolean | No | Stacks on taxes applied before it. |
| appliesToSubscriptions | boolean | No | — |
| appliesToOneTime | boolean | No | — |
| appliesToAddOns | boolean | No | — |
| appliesToUsage | boolean | No | — |
Importing defaults skips codes that already exist and returns created, skipped and any notes, so it is safe to run more than once.