# List contracts

`GET https://app.shuttleglobal.com/c/api/instances/{instance_key}/contracts`

Search and filter contract objects with pagination support.

Available fields for criteria and order:
`id`, `account`, `alt_key`, `channel`, `completed`, `created`, `designation`, `division`, `frequency`, `gateway`, `initiative`, `legal_entity`, `next_charge`, `next_payment`, `nonce`, `occurrences`, `outstanding_amount`, `payment_method`, `retry_complete`, `retry_count`, `scheduler`, `status`, `updated`

## Authentication

- basicAuth: Basic Authentication using secret key
- bearerAuth: OAuth 2.0 Bearer Token Authentication

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `criteria` | query | string | no | Search criteria for filtering contracts. Available fields: `id`, `account`, `alt_key`, `channel`, `completed`, `created`, `designation`, `division`, `frequency`, `gateway`, `initiative`, `legal_entity`, `next_charge`, `next_payment`, `nonce`, `occurrences`, `outstanding_amount`, `payment_method`, `payment_method_status`, `payment_method_expires`, `retry_complete` (Y/N) - retry_count - scheduler (Y/N) - status - updated Examples: - `status=ACTIVE;FAILING` - `account=acc_12345_67890` - `scheduler=Y` - `next_payment<>2024-01-01;2024-12-31` |
| `order` | query | string | no | Sort order for results. Supports any field that criteria supports. Defaults to `created:desc` if not specified. Append `:desc` for descending order. Separate multiple order fields with commas. Examples: - `order=next_payment` - `order=status,created:desc` |
| `expand` | query | string | no | Fields to expand into full objects. Separate multiple fields with commas. Available fields: - account (account object) - payment_method (payment method object) - gateway (gateway object) - legal_entity (legal entity object) - initiative (initiative object) - designation (designation object) - channel (channel object) - last_transaction (transaction object) - last_charge (charge object) - created_session (session object) - updated_session (session object) Example: `expand=account,payment_method,last_transaction` |
| `limit` | query | integer | no | Number of records to return: 20 if not set, at most 1000. |
| `offset` | query | integer | no | Number of records to skip before the first one returned. `offset` + `limit` can't exceed 5000; to read further, page by a field such as `created` instead. See [Paging through results](/platforms/reference/paging/). |

## Responses

### 200: List of contracts

```json
{
  "contracts": [
    {
      "account": "string",
      "alt_key": "string",
      "amount": "string",
      "channel": "string",
      "completed": "2026-01-01T12:00:00Z",
      "created": "2026-01-01T12:00:00Z",
      "currency": "string",
      "description": "string",
      "designation": "string",
      "frequency": "WEEKLY",
      "gateway": "string",
      "id": "string",
      "initiated": "2026-01-01T12:00:00Z",
      "initiative": "string",
      "keep_active_until": "2026-01-01T12:00:00Z",
      "last_charge": "string",
      "last_transaction": "string",
      "legal_entity": "string",
      "metadata": {
        "order_id": "12345",
        "customer_reference": "CUS-001"
      },
      "next_contract": "string",
      "next_payment": "2026-01-01T12:00:00Z",
      "nonce": "string",
      "account_alt_key": "string",
      "charge_count": 0,
      "event_date": "2026-01-01T12:00:00Z",
      "outstanding_amount": "string",
      "payment_method": "string",
      "recurring": true,
      "retry_complete": true,
      "retry_count": 0,
      "status": "SETUP",
      "updated": "2026-01-01T12:00:00Z"
    }
  ],
  "meta": {
    "limit": 0,
    "offset": 0,
    "total": 0
  }
}
```

### 400: Bad request

```json
{
  "code": "string",
  "message": "string"
}
```

### 401: Unauthorised: the API key is missing or not valid

```json
{
  "code": "UNAUTHORIZED",
  "message": "Unauthorised"
}
```

## Example request

```sh
curl --request GET \
  --url https://app.shuttleglobal.com/c/api/instances/YOUR_INSTANCE_KEY/contracts \
  --header 'Authorization: Basic <base64 of SECRET_KEY:>'
```

Reference page: https://docs.shuttleglobal.com/platforms/reference/operations/listcontracts/