# 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

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

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

**Response:**
```json
{
  "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

```http
POST /api/v1/settlements/schedule
```

```bash
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

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

```bash
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

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

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

---

## Settlement History

```http
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