Get account obligation

One obligation with its status, deadline, origin and the movements matched to it. Required API-key scope: settlements_read; an OAuth client needs the same scope. The key’s owner must also be allowed to view the workspace’s settlements.

GET /api/v1/workspaces/{workspaceId}/venue-accounts/{venueAccountId}/settlement/obligations/{obligationId}

Read a settlement obligation

cURL

curl --request GET \
  --url https://api.tetrafi.io/api/v1/workspaces/{workspaceId}/venue-accounts/{venueAccountId}/settlement/obligations/{obligationId} \
  --header 'Authorization: Bearer <token>'

200

{
  "amount": "<string>",
  "asset": "<string>",
  "consequence": "overdue",
  "dueAt": "2023-11-07T05:31:56Z",
  "metAmount": "<string>",
  "obligationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "origin": {
    "kind": "windowSnapshot",
    "originId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "version": 123
  },
  "payee": "workspace",
  "payer": "workspace",
  "policyVersion": 123,
  "readAt": "2023-11-07T05:31:56Z",
  "remainingAmount": "<string>",
  "revision": 123,
  "state": "open",
  "venueAccountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "workspaceId": "<string>",
  "events": [
    {
      "eventId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "kind": "<string>",
      "obligationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "occurredAt": "2023-11-07T05:31:56Z",
      "payload": "<unknown>",
      "revision": 123
    }
  ],
  "matches": [
    {
      "allocationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "amount": "<string>",
      "asset": "<string>",
      "matchedAt": "2023-11-07T05:31:56Z",
      "movementId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "movementRevision": 123,
      "obligationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "reversedAt": "2023-11-07T05:31:56Z"
    }
  ],
  "matching": {
    "discrepancy": "<string>",
    "eligibleDeliveryUsdValue": "<string>",
    "observedDeliveryUsdValue": "<string>",
    "paidUsdValue": "<string>",
    "priceVersion": "<string>",
    "reasonCode": "<string>",
    "remainingDeliveryUsdValue": "<string>",
    "rule": "<string>",
    "statementVersion": 123
  },
  "unappliedMovements": [
    {
      "amount": "<string>",
      "asset": "<string>",
      "movementId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "reasonCode": "<string>"
    }
  ],
  "arrivalAt": "2023-11-07T05:31:56Z",
  "consequencePolicy": {
    "grace": "disabled",
    "lateFee": "disabled",
    "rollover": "disabled",
    "source": "<string>",
    "tradingBlock": "disabled",
    "version": 123
  },
  "dueRefusal": "<string>",
  "dueState": "notDue",
  "lateFundsAmount": "<string>",
  "latePayment": true,
  "lpDelivery": {
    "sends": [
      {
        "amount": "<string>",
        "asset": "<string>",
        "movementId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "occurredAt": "2023-11-07T05:31:56Z",
        "network": "<string>",
        "txHash": "<string>"
      }
    ],
    "state": "awaitingWorkspacePayment",
    "agreementAt": "2023-11-07T05:31:56Z",
    "dueAt": "2023-11-07T05:31:56Z",
    "refusal": "<string>",
    "sla": {
      "seconds": 123,
      "source": "<string>"
    },
    "workspaceFinalAt": "2023-11-07T05:31:56Z"
  },
  "needsReview": true,
  "observedAt": "2023-11-07T05:31:56Z",
  "originalWindowId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "overdueSince": "2023-11-07T05:31:56Z",
  "payInDifference": {
    "amount": "<string>",
    "direction": "over"
  },
  "remindersPaused": true,
  "closure": {
    "reason": "keptAtVenue",
    "recordedAt": "2023-11-07T05:31:56Z",
    "fromWindowId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "intoWindowId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "keepRequestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "nettedAmount": "<string>"
  },
  "dispute": {
    "note": "<string>",
    "openedAt": "2023-11-07T05:31:56Z",
    "openedBy": "<string>",
    "priorState": "open",
    "openedByName": "<string>"
  },
  "dueBasis": "clock",
  "metAt": "2023-11-07T05:31:56Z",
  "tradeId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "windowId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

Authorizations

bearer_authapi_key

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Scopes

settlements_read · bearer_auth

settlements_read · api_key

Headers

X-Workspace-Id · string<uuid>

The workspace the request acts in. An API key bound to a workspace implies it: omit the header, or send that same id (another id answers 403 WORKSPACE_SCOPE_MISMATCH). A member session must send it (400 MISSING_WORKSPACE without it).

Path Parameters

workspaceId · string · required

Workspace id

venueAccountId · string<uuid> · required

The venue account's id

obligationId · string<uuid> · required

The obligation's id

Response

200

application/json

Deadline facts projected at read time with the stored row's deadline.

amount · string · required

Exact decimal asset units, never a floating-point number.

asset · string · required

consequence · enum<string> · required

New values may be added; treat unknown values as other.

Available options: overdue, lapse

dueAt · string<date-time> · required

metAmount · string · required

obligationId · string<uuid> · required

origin · object · required

Show child attributes

payee · enum<string> · required

New values may be added; treat unknown values as other.

Available options: workspace, lp

payer · enum<string> · required

New values may be added; treat unknown values as other.

Available options: workspace, lp

policyVersion · integer<int64> · required

readAt · string<date-time> · required

remainingAmount · string · required

revision · integer<int64> · required

state · enum<string> · required

New values may be added; treat unknown values as other.

Available options: open, partlyMet, met, lapsed, overdue, disputed

venueAccountId · string<uuid> · required

workspaceId · string · required

events · object[] · required

Show child attributes

matches · object[] · required

Show child attributes

matching · object · required

Show child attributes

unappliedMovements · object[] · required

Show child attributes

arrivalAt · string<date-time> | null

Authoritative arrival of the latest final allocated movement.

consequencePolicy · null | object

The LP's explicit, versioned consequence terms. Every setting is stated; an absent policy is unavailable, never read as all disabled.

Show child attributes

dueRefusal · string | null

A named cause when the policy or deadline facts could not be read.

dueState · enum<string>

New values may be added; treat unknown values as other.

Available options: notDue, dueSoon, overdue, lpDeliveryOverdue, disputed, met, lapsed, nothingOwed, deadlineUnconfirmed, unavailable, updating, dueNow

lateFundsAmount · string | null

Money credited to a lapsed pay-in after its deadline, exact, as the fiat arrival owner recorded it (credit time in arrival_at). Never revives the price.

latePayment · boolean | null

True when a final allocated movement arrived after the deadline.

lpDelivery · null | object

An LP-paid residual against the schedule's delivery promise; absent when the schedule makes none.

Show child attributes

needsReview · boolean

The obligation's deadline task kept refusing and stopped for review; its named cause is in due_refusal and due_state is unavailable.

observedAt · string<date-time> | null

When TetraFi observed that movement, which may be after the deadline.

originalWindowId · string<uuid> | null

The window whose statement created this obligation; late payments meet it.

overdueSince · string<date-time> | null

The confirmed deadline itself once the residual is past it.

payInDifference · null | object

With dueRefusal PAY_IN_AMOUNT_MISMATCH: whether the on-time payment exceeds or falls short of the agreed amount, and by how much. Absent when the recorded arrival no longer shows an on-time amount that differs.

Show child attributes

remindersPaused · boolean

Reminders and overdue escalation are paused for this obligation only.

closure · null | object

Set only when the delivery closed at zero because the LP confirmed a keep.

Show child attributes

dispute · null | object

Show child attributes

dueBasis · enum<string>

onAgreement: dueAt is when the LP's statement was agreed, not a deadline.

Available options: clock, onAgreement

metAt · string<date-time> | null

tradeId · string<uuid> | null

windowId · string<uuid> | null