Dunning and tax

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.

MethodPathPurposePermission
GET/merchants/:merchantId/dunning-policyRead the policy, creating defaults if needed.subscriptions:read
PATCH/merchants/:merchantId/dunning-policyUpdate attempts, schedule, grace period and final action.subscriptions:write
FieldTypeRequiredNotes
enabledbooleanNo—
maxAttemptsintegerNo1 to 10.
retryScheduleHoursinteger[]No1 to 10 values, each between 1 and 720 hours. The last value repeats.
gracePeriodDaysintegerNo0 to 90 days.
finalActionmark_unpaid | cancel | restrictNo—

Tax rates

Rates are merchant-scoped and can be limited by country, region, priority and validity dates.

MethodPathPurposePermission
GET/merchants/:merchantId/tax-ratesList configured rates.tax:read
POST/merchants/:merchantId/tax-ratesCreate a rate with type and use-case gates.tax:write
PATCH/merchants/:merchantId/tax-rates/:taxRateIdUpdate a rate.tax:write
DELETE/merchants/:merchantId/tax-rates/:taxRateIdArchive a rate.tax:write
POST/merchants/:merchantId/tax-rates/import-defaultsSeed a country template such as NG or KE.tax:write
GET/platform/metadata/tax-jurisdictionsAvailable templates and their notes.—
FieldTypeRequiredNotes
namestringYes—
countryCodestringYesISO 3166-1 alpha-2.
regionCodestringNo—
ratestringNoDecimal string, for example "7.5".
taxTypevat | gst | sales_tax | consumption_tax | service_tax | withholding | noneNo—
compoundbooleanNoStacks on taxes applied before it.
appliesToSubscriptionsbooleanNo—
appliesToOneTimebooleanNo—
appliesToAddOnsbooleanNo—
appliesToUsagebooleanNo—

Importing defaults skips codes that already exist and returns created, skipped and any notes, so it is safe to run more than once.