> ## Documentation Index
> Fetch the complete documentation index at: https://docs.droplinked.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Stream 7 — Settlement

> Order payment + financial-detail projection — provider, status, amount — projected from OrderV2.

<Note>**BETA — Critical stream for lenders.** Settlement is the canonical revenue signal for lending underwriting. In v1 the stream exposes the `OrderV2` payment + financial-detail shape directly; a normalized cross-PSP `UnifiedTransaction` projection is planned and will swap in without changing this partner-facing shape.</Note>

The **settlement stream** projects per-order payment and financial detail from `OrderV2`: the
order, its status, the payment provider and payment status, the USD amount, the currency, and the
capture timestamp. The lending underwriter consumes a trailing window of these as the revenue
signal. Rows are scoped to the shops owned by the API key's merchant.

## Endpoint

```
GET /v1/api/inventory-os/streams/settlement
```

**Query parameters:**

| Param    | Type     | Notes                                               |
| -------- | -------- | --------------------------------------------------- |
| `limit`  | int      | 1–200, default 50                                   |
| `cursor` | string   | Opaque pagination token                             |
| `since`  | ISO-8601 | Optional; orders updated on or after this timestamp |

## Row shape

```json theme={null}
{
  "orderId": "665ford123…",
  "orderNumber": "DRP-100245",
  "status": "COMPLETED",
  "paymentProvider": "stripe",
  "paymentStatus": "CAPTURED",
  "amountUsd": 124.96,
  "currency": "USD",
  "capturedAt": "2026-06-01T12:01:33.000Z",
  "updatedAt": "2026-06-01T12:01:33.000Z"
}
```

| Field             | Meaning                                                               |
| ----------------- | --------------------------------------------------------------------- |
| `orderId`         | `OrderV2` id; pagination cursor advances on this field                |
| `orderNumber`     | Human-readable order number                                           |
| `status`          | Order status                                                          |
| `paymentProvider` | PSP that processed the payment (`payment.provider`); `null` if unset  |
| `paymentStatus`   | PSP-side payment status (`payment.status`); `null` if unset           |
| `amountUsd`       | Order total in USD (`financialDetails.totalUsd`); `null` if unset     |
| `currency`        | Settlement currency (`financialDetails.currency`); `null` if unset    |
| `capturedAt`      | When the payment was captured (`payment.capturedAt`); `null` if unset |

<Note>The v1 shape exposes the `OrderPayment` fields verbatim so partners can build against the
surface today. The forthcoming `UnifiedTransaction` projection will normalize per-PSP shapes
(Stripe / PayPal / Bonum / Telr / Paymob) and add cohort + MoR-entity context — without changing
the field names a partner already reads.</Note>

## Response envelope

```json theme={null}
{
  "streamType": "settlement",
  "merchantId": "65df8abc123…",
  "data": [ /* rows */ ],
  "count": 50,
  "nextCursor": "NjY1Zm9yZDEyMw..."
}
```

## curl

```bash theme={null}
curl "https://apiv3.droplinked.com/v1/api/inventory-os/streams/settlement?since=2026-05-01T00:00:00.000Z&limit=200" \
  -H "x-droplinked-api-key: REPLACE_ME"
```

## Lender-facing usage

This is **the** revenue signal for lending decisions. Aggregate `amountUsd` over 30/60/90-day
windows client-side; combined with provenance (Stream 8) and inventory level (Stream 2), the
underwriter prices a working-capital line against confirmed, captured revenue. Use `since` for
incremental pulls and **subscribe to `settlement.changed`** for near-real-time integration.

## Rate limits

Low-budget class — **250 reads/min/key**, up to **3 subscriptions/key**. Settlement reads are
usually batch (nightly reconciliation); subscribe for real-time.

## Related

* [Sell-through stream](/developers/inventory-os-api/streams/sell-through) — commission events cross-check
* [Return-rate stream](/developers/inventory-os-api/streams/return-rate) — refunded + cancelled orders
* [KYB cohorts](/developers/kyb-cohorts) — cohort + MoR routing context (planned for the UnifiedTransaction projection)
* [Webhook subscriptions](/developers/inventory-os-api/subscriptions) — `settlement.changed` events