# Merchant instance API

> The Merchant Instance API is the core of the Shuttle platform. It provides direct access to all payment resources within a single merchant instance.

The Merchant Instance API is the core of the Shuttle platform. It provides direct access to all payment resources within a single merchant instance.

**Payment Initiation**

- **[Payments](/platforms/reference/operations/tags/payments/)**: API-based payments (one-time, recurring, authorisations)
- **[Checkouts](/platforms/reference/operations/tags/checkouts/)**: embedded payment experience via shuttle.js
- **[Payment Links](/platforms/reference/operations/tags/payment-links/)**: hosted payment pages via shareable URLs
- **[Deep Links](/platforms/reference/operations/tags/deep-links/)**: secure, time-limited URLs for embedded Merchant Setup and merchant views

**Customer & Activity**

- **[Accounts](/platforms/reference/operations/tags/accounts/)**: your customers / payers, identified by your CRM key
- **[Payment Methods](/platforms/reference/operations/tags/payment-methods/)**: tokenised cards, bank accounts, and wallets
- **[Transactions](/platforms/reference/operations/tags/transactions/)**: the read-only ledger of all payment activity

**Payment Lifecycle**

- **[Captures](/platforms/reference/operations/tags/captures/)**: settle a previously authorised payment
- **[Voids](/platforms/reference/operations/tags/voids/)**: cancel an authorisation before capture
- **[Refunds](/platforms/reference/operations/tags/refunds/)**: return money to the customer

**Billing**

- **[Contracts](/platforms/reference/operations/tags/contracts/)**: the agreements behind every payment, with automatic retry logic for recurring billing
- **[Charges](/platforms/reference/operations/tags/charges/)**: invoices on recurring contracts

**Configuration**

- **[Gateways](/platforms/reference/operations/tags/gateways/)**: merchant connections to payment processors
- **[Processors](/platforms/reference/operations/tags/processors/)**: available payment processor integrations
- **[Instances](/platforms/reference/operations/tags/instances/)**: check the capabilities of the current merchant instance

**Enterprise**

- **[Legal Entities](/platforms/reference/operations/tags/legal-entities/)**: business entities that receive payments
- **[Legal Entity Routes](/platforms/reference/operations/tags/legal-entity-routes/)**: payment routing between entities and gateways
- **[Workflows](/platforms/reference/operations/tags/workflows/)**: automated actions on payment events

## List APIs

All list endpoints support `criteria`, `order`, and `expand` parameters. The available fields vary by endpoint; see individual endpoint documentation for the specific fields supported.

### Paging

List endpoints return a page at a time: `limit` records (20 if not set, at most 1,000), after skipping `offset` records. `offset` + `limit` can't exceed 5,000. To read more than 5,000 records, page by a field such as `created` instead: see [Paging through results](/platforms/reference/paging/).

### Criteria

The `criteria` parameter filters results. It supports these operators:

| Operator | Description | Example |
|---|---|---|
| `=` | Exact match. Separate multiple values with `;` for IN | `status=ACTIVE;FAILING` |
| `!=` | Not equal | `status!=ARCHIVE` |
| `~=` | Partial match (case insensitive) | `email~=example.com` |
| `>`, `>=`, `<`, `<=` | Comparison | `created>=2024-01-01` |
| `<>` | Between. Separate values with `;` | `created<>2024-01-01;2024-12-31` |
| `!` | Is null | `completed!` |
| `!!` | Is not null | `payment_method!!` |

Combine multiple criteria with commas (AND logic):

```
criteria=status=ACTIVE;FAILING,email=dave@gmail.com
```

Notes:
- Strings are case insensitive (some exceptions apply)
- Booleans are `Y`/`N` (tip: check for `=Y` or `!=Y` as some objects treat false as null)
- Remember to URL encode the criteria parameter, e.g., `criteria=status%3DACTIVE%3BFAILING` for `criteria=status=ACTIVE;FAILING`

### Order

The `order` parameter controls sorting. It supports any field that `criteria` supports.

- Defaults to `created:desc` if not specified
- Ascending by default, append `:desc` for descending
- Separate multiple fields with commas

```
order=updated
order=updated:desc
order=status,updated:desc
```

### Expand

The `expand` parameter includes related objects in the response instead of just their IDs.

- Separate multiple fields with commas
- Some objects support nested expansion with dot notation

```
expand=account,payment_method
expand=account,contract.last_transaction
```

Without expand, related objects are returned as IDs:

```json
{
  "transaction": {
    "id": "tr_1234_5678",
    "account": "acc_1234_9012",
    "payment_method": "pm_1234_3456"
  }
}
```

With `?expand=account,payment_method`, the full objects are included:

```json
{
  "transaction": {
    "id": "tr_1234_5678",
    "account": {
      "id": "acc_1234_9012",
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane@example.com"
    },
    "payment_method": {
      "id": "pm_1234_3456",
      "type": "VISA",
      "last4": "4242",
      "expiry": "12/2026"
    }
  }
}
```

### Pagination

All list endpoints support `limit` and `offset` for pagination. The response includes a `meta` object with `total`, `limit`, and `offset`.