> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anyway.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Orders API

> Query orders, confirm payment status, and build safe fulfillment with the Merchant API.

Use the generated endpoint pages for the complete query parameters and response schemas.

<CardGroup cols={2}>
  <Card title="List orders" icon="list" href="/api-reference/endpoint/orders">
    Filter and paginate organization-scoped orders.
  </Card>

  <Card title="Get an order" icon="file-magnifying-glass" href="/api-reference/endpoint/get-order">
    Inspect one order and its available payment-channel identifiers.
  </Card>
</CardGroup>

## List and detail behavior

The list operation supports payment-status checks and operational views. Its `status`
filter matches the human-facing `displayStatus`, while the response also preserves the
canonical status. You can also narrow orders by `customer_id` or Anyway
`subscription_id`. Merchant API order detail does not expose payment-provider or provider
account identifiers.

`orderId` is the canonical order identifier. The legacy `id` response field contains the
same value but is deprecated. `amount` is the display-unit amount, while `amountCents` is
the stored minor-unit amount.

Card orders can also include `fundsSettled` and `settledAvailableOn`. Use
`fundsSettled` as the payout-eligibility state; `settledAvailableOn` is only the provider's
estimated availability time. Both fields are omitted for payment methods without this
settlement lifecycle.

## Subscription relationships

An order created for a recurring payment includes `subscriptionId`. The initial payment
has no `originalOrderId`; each renewal points `originalOrderId` to that initial order.
Use `GET /v1/orders?subscription_id=SUB_EXAMPLE` to retrieve the order history for one
subscription.

## Payment-link correlation

Append URL-encoded query parameters when sending a payment link to a buyer:

```text theme={null}
https://pay.anyway.sh/pay/PL_EXAMPLE?merchant_reference=PUR_456&user_id=USR_123&source=web
```

When checkout opens, Anyway stores the query parameters on the checkout-attempt record as
`merchantMetadata`. If a key matches `merchant_reference` or `merchantReference`, Anyway
also promotes its value to the attempt's separate `merchantReference` field while keeping
the original key-value pair in `merchantMetadata`.

When payment is confirmed, both values are copied from the checkout attempt to the order
record. Subscription renewal orders inherit them from the initial order. This persistence
path makes the same correlation data available through order responses and Webhooks after
checkout has finished.

Payment-link query parameters are exposed through two complementary fields:

* `merchantReference` is the promoted value of the `merchant_reference` query parameter.
  It is stored separately as a first-class correlation field, and the orders list can
  filter it with `merchant_reference`.
* `merchantMetadata` contains every custom payment-link query parameter as string
  key-value pairs. Merchant API responses return the map, but arbitrary metadata keys
  cannot be used as list filters.

After receiving an order ID from a webhook or success redirect, retrieve the order and
read both fields:

```bash theme={null}
curl "https://merchant-api-prod.anyway.sh/v1/orders/ORD_EXAMPLE" \
  -H "X-API-Key: ak_YOUR_MERCHANT_API_KEY"
```

```json theme={null}
{
  "success": true,
  "message": "Order retrieved",
  "data": {
    "orderId": "ORD_EXAMPLE",
    "status": "PAID",
    "merchantReference": "PUR_456",
    "merchantMetadata": {
      "merchant_reference": "PUR_456",
      "user_id": "USR_123",
      "source": "web"
    }
  }
}
```

Treat `merchantMetadata`, buyer-supplied notes, and URL query parameters as untrusted
input; never use them alone to authorize access or set a price.

## Fulfillment

Fulfill from a verified paid state or a verified `order.paid` webhook. Make delivery idempotent by the Anyway order ID. Anyway protects paid orders from duplicate payment events and status regression, but your fulfillment handler must also tolerate retries.

<Warning>
  A successful API response does not make buyer-controlled metadata trustworthy. Authorization and pricing decisions must come from server-controlled records.
</Warning>