Settlement Schedule#

Configure when and how often a merchant's funds are settled.

All endpoints are admin API calls under /api/v1/settlements (plural): send Authorization: Bearer <JWT> (or an API key in x-api-key). The tenant comes from the token or key. There is one schedule per merchant.

Get Settlement Schedule#

GET/api/v1/settlements/schedule/:merchantId

Get Settlement Schedulebash

curl https://uat.auxcore.net/api/v1/settlements/schedule/3f9c2b7e-1a4d-4e8f-b6c5-2d1e0f9a8b7c \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

Get Settlement Schedulejson

{
  "success": true,
  "data": {
    "id": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e",
    "tenantId": "your-tenant-id",
    "merchantId": "3f9c2b7e-1a4d-4e8f-b6c5-2d1e0f9a8b7c",
    "interval": "daily",
    "autoSettle": true,
    "scheduledTime": "14:00",
    "timezone": "America/New_York",
    "enabled": true,
    "lastSettlementAt": "2026-01-14T19:00:00.000Z",
    "nextSettlementAt": "2026-01-15T19:00:00.000Z",
    "modifiedBy": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
    "notes": null,
    "createdAt": "2026-01-02T15:20:11.000Z",
    "updatedAt": "2026-01-10T09:02:45.000Z"
  }
}

Returns 404 with { "success": false, "error": "Settlement schedule not found" } when the merchant has no schedule.

Create Schedule#

POST/api/v1/settlements/schedule

Create Schedulebash

curl -X POST https://uat.auxcore.net/api/v1/settlements/schedule \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "3f9c2b7e-1a4d-4e8f-b6c5-2d1e0f9a8b7c",
    "interval": "daily",
    "scheduledTime": "14:00",
    "timezone": "America/New_York",
    "autoSettle": true
  }'

Field	Type	Required	Notes
`merchantId`	string (UUID)	yes
`interval`	string	yes	See Settlement Intervals.
`scheduledTime`	string	no	`HH:MM` (e.g. `"14:00"`) for `daily`, `weekly`, `biweekly`, `monthly`. Ignored for `15min`, `30min`, `hourly`.
`timezone`	string	no	IANA zone for `scheduledTime`. Default `UTC`.
`autoSettle`	boolean	no	Default `true`.
`notes`	string	no

Returns 201 with the schedule. Missing merchantId or interval → 400; a merchant that already has a schedule, or a malformed scheduledTime, → 500 with the error message (e.g. "Settlement schedule already exists for this merchant").

Update Schedule#

PUT/api/v1/settlements/schedule/:merchantId

Update Schedulebash

curl -X PUT https://uat.auxcore.net/api/v1/settlements/schedule/3f9c2b7e-1a4d-4e8f-b6c5-2d1e0f9a8b7c \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "interval": "daily",
    "scheduledTime": "09:00",
    "timezone": "America/New_York",
    "enabled": true
  }'

Accepts interval, autoSettle, scheduledTime, timezone, enabled and notes; omitted fields are left unchanged. If the merchant has no schedule yet, one is created from the body. Returns the schedule.

Delete Schedule#

DELETE/api/v1/settlements/schedule/:merchantId

Returns { "success": true, "message": "Settlement schedule deleted successfully" }.

Settlement History#

GET/api/v1/settlements/history/:merchantId

Returns all settlements for the merchant (data is an array of settlement records).

Settlement Intervals#

15min / 30min: settle every 15 or 30 minutes
hourly: every hour, on the hour
daily: once a day at scheduledTime (default interval)
weekly / biweekly: once every one or two weeks at scheduledTime
monthly: once per month at scheduledTime

Set enabled: false to pause a schedule without deleting it.

Need help? Contact support@auxcore.net