# List contract charges

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

List the charges attached to a contract. Ordered by due date ascending by default.

This endpoint is most useful for contracts created with explicit scheduled charges,
where all charges are created upfront at contract creation. For frequency-based
recurring contracts, charges are generated on schedule as each billing cycle comes
due — use [Get future charges](/merchants/reference/operations/getfuturecharges/) to see projected future
charges that have not yet been generated.

## Authentication

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

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `contract_id` | path | string | yes | The contract's ID (`co_...`). |
| `order` | query | string | no | Sort order for results. Defaults to `due` (due date ascending) if not specified. Append `:desc` for descending order. |
| `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](/merchants/reference/paging/). |
| `expand` | query | string | no | Fields to expand into full objects. Separate multiple fields with commas. Available fields: - contract (contract object) - created_session (session object) - updated_session (session object) |

## Responses

### 200: List of charges on the contract

```json
{
  "charges": [
    {
      "id": "string",
      "amount": "string",
      "alt_key": "string",
      "charge_number": 0,
      "extra_charge": true,
      "completed": "2026-01-01T12:00:00Z",
      "contract": "string",
      "created": "2026-01-01T12:00:00Z",
      "created_session": "string",
      "due": "2026-01-01T12:00:00Z",
      "initiated": "2026-01-01T12:00:00Z",
      "outstanding_amount": "string",
      "overdue_amount": "string",
      "recurring": true,
      "paid_amount": "string",
      "status": "ACTIVE",
      "updated": "2026-01-01T12:00:00Z",
      "updated_session": "string",
      "writtenoff_amount": "string",
      "v": 0
    }
  ]
}
```

### 400: Bad request

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

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

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

### 404: Resource not found

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

## Example request

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

Reference page: https://docs.shuttleglobal.com/merchants/reference/operations/listcontractcharges/