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

# GET /api/v1/settlements/:settlementId — Get Settlement

> GET /api/v1/settlements/:settlementId — fetches a settlement with invoice, payer, and merchant details. Auto-refreshes on-chain status when SUBMITTED.

Poll this endpoint to check the confirmation status of a settlement. The response includes the full settlement record along with nested details about the associated invoice, service, payer, and merchant. If the settlement is in `SUBMITTED` status and has a transaction hash, Retempo automatically re-checks the on-chain receipt on every request — no separate polling mechanism is needed.

```
GET https://api.retempo.xyz/api/v1/settlements/:settlementId
```

## Path Parameters

<ParamField path="settlementId" type="string" required>
  The unique identifier of the settlement to retrieve.
</ParamField>

## Response

A successful request returns HTTP `200 OK` with the full settlement object and all related records.

<ResponseField name="settlement" type="object">
  The requested settlement record with all related objects.

  <Expandable title="settlement fields">
    <ResponseField name="id" type="string">Unique identifier for the settlement.</ResponseField>
    <ResponseField name="invoiceId" type="string">ID of the associated invoice.</ResponseField>
    <ResponseField name="serviceId" type="string">ID of the associated service.</ResponseField>
    <ResponseField name="payerId" type="string">Retempo user ID of the payer.</ResponseField>
    <ResponseField name="merchantId" type="string">Retempo user ID of the merchant.</ResponseField>
    <ResponseField name="amount" type="string">Settled amount as a decimal string with six decimal places.</ResponseField>
    <ResponseField name="currency" type="string">Currency of the settlement.</ResponseField>
    <ResponseField name="referenceHash" type="string">The reference hash supplied at creation.</ResponseField>
    <ResponseField name="transactionHash" type="string">The on-chain transaction hash.</ResponseField>
    <ResponseField name="status" type="string">Current status — `PENDING` while being processed, `SUBMITTED` while awaiting on-chain confirmation, `CONFIRMED` once verified, or `FAILED` if the transaction did not succeed.</ResponseField>
    <ResponseField name="recordedAt" type="string">Datetime the settlement was recorded.</ResponseField>
    <ResponseField name="createdAt" type="string">ISO 8601 datetime the settlement was created.</ResponseField>
    <ResponseField name="invoice" type="object">Nested invoice object with status and amount details.</ResponseField>
    <ResponseField name="service" type="object">Nested service object with name and owner details.</ResponseField>
    <ResponseField name="payer" type="object">Nested payer user object.</ResponseField>
    <ResponseField name="merchant" type="object">Nested merchant user object.</ResponseField>
  </Expandable>
</ResponseField>

### 200 — Settlement retrieved

```json theme={null}
{
  "settlement": {
    "id": "clz1settle222",
    "invoiceId": "clz1invoice999",
    "serviceId": "clz1abc2def3ghi4",
    "payerId": "clz1user111",
    "merchantId": "clz1owner123",
    "amount": "49.000000",
    "currency": "USDC",
    "referenceHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
    "transactionHash": "0x9f8e7d6c5b4a392817263544536271819f0e1d2c3b4a5968...",
    "status": "CONFIRMED",
    "recordedAt": "2025-06-01T10:20:00.000Z",
    "createdAt": "2025-06-01T10:20:00.000Z",
    "invoice": {
      "id": "clz1invoice999",
      "status": "PAID",
      "amount": "49.000000",
      "currency": "USDC",
      "paidAt": "2025-06-01T10:20:00.000Z"
    },
    "service": {
      "id": "clz1abc2def3ghi4",
      "name": "DataStream Pro"
    },
    "payer": {
      "id": "clz1user111",
      "email": "subscriber@example.com"
    },
    "merchant": {
      "id": "clz1owner123",
      "email": "owner@datastreampro.com"
    }
  }
}
```

## Example Request

```bash theme={null}
curl https://api.retempo.xyz/api/v1/settlements/clz1settle222
```

## Error Codes

| Status          | Message                     | Condition                                 |
| --------------- | --------------------------- | ----------------------------------------- |
| `404 Not Found` | `Settlement was not found.` | No settlement exists for the provided ID. |

<Tip>
  If the settlement status is `SUBMITTED`, the API automatically re-checks the on-chain receipt on each `GET` request and updates the status. Poll this endpoint until `status` transitions to `CONFIRMED` or `FAILED`.
</Tip>