List Agreements

GET 
/v1/agreements

List the stored agreements of every merchant under your acquirer. Returns the brief view (no attached orders).

Required permission: agreements_read.

Request

Query Parameters

items integer

Possible values: >= 1 and <= 100

Number of items per page.

agreement_id string

Filter by the merchant-assigned agreement identifier.

order_id uuid

Filter to the agreement attached to this order.

type string

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

variability string

Possible values: [fixed, variable]

created_at[gte] date-time
created_at[lte] date-time
sort[field] string

Possible values: [type, max_use, variability, expiry, created_at, updated_at]

Default value: created_at

sort[dir] string

Possible values: [asc, desc]

Default value: desc

Responses

200

Paginated list of agreements (brief view).

application/json

Schema

Schema

agreements

object[]

required

Array [

id stringrequired

Merchant-chosen agreement identifier supplied when the agreement was established.

type stringrequired

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

first_order_id uuid

A 36-character UUIDv7 identifier.

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 API key lacks the required permission.

application/json

Schema

Schema

message stringrequired

Example (from schema)

{
  "message": "Unauthorized"
}

Loading...