List Agreements

GET 
/v1/agreements

List stored agreements visible to the authenticated principal. Returns the brief view (no attached orders).

Required permission: agreements_read.

Request

Query Parameters

items integer

Possible values: >= 1 and <= 100

id uuid

Filter by internal UUID.

agreement_id string

Filter by the merchant-assigned agreement identifier.

type string

Possible values: [unscheduled, recurring, registered, installment]

variability string

Possible values: [fixed, variable]

active boolean

Filter to active (true) or disabled (false) agreements.

created_at[gte] date-time
created_at[lte] date-time

Responses

200

Paginated list of agreements (brief view).

application/json

Schema

Schema

agreements

object[]

required

Array [

id stringrequired

Merchant-chosen agreement identifier (the id supplied in new_agreement.id at creation). Use this value as agreement_id on follow-up transactions.

type stringrequired

Possible values: [unscheduled, recurring, registered, installment]

first_order_id uuid

A 36-character UUIDv7 identifier. When used as an idempotency key on write endpoints, the client is responsible for generating a fresh UUID for each logical operation and retaining it across retries.

max_use integernullable

variability stringrequired

Possible values: [fixed, variable]

expiry datenullable

active booleanrequired

false once the agreement has been disabled via PUT /v1/agreements/:id/disable. Disabled agreements reject new transactions.

created_at date-timerequired

ISO 8601 UTC timestamp with time zone designator.

updated_at date-timerequired

ISO 8601 UTC timestamp with time zone designator.

]

meta

object

required

Cursor-style pagination metadata. next_page and prev_page are null at the boundaries. Total counts are intentionally omitted for performance on large result sets (countless pagination).

current_page integerrequired

Possible values: >= 1

next_page integernullablerequired

prev_page integernullablerequired

Example (from schema)

{
  "agreements": [
    {
      "id": "SUB-USER-42",
      "type": "unscheduled",
      "first_order_id": "0191f5a7-3d99-7f81-b7ec-962a5f5fdd7c",
      "max_use": 0,
      "variability": "fixed",
      "expiry": "2024-07-29",
      "active": true,
      "created_at": "2025-01-15T14:30:00Z",
      "updated_at": "2025-01-15T14:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": 2,
    "prev_page": null
  }
}

401

Authentication failed.

application/json

Schema

Schema

message stringrequired

Example (from schema)

{
  "message": "Missing authentication information"
}

403

The authenticated principal lacks the required permission.

application/json

Schema

Schema

message stringrequired

Example (from schema)

{
  "message": "Unauthorized"
}

Loading...