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

# Preview and place - Sending an order

> What an Apexium order asks for: selection, stake, price floor, partial fills and expiry, how a preview differs from a placement, and what each returns.

`POST /v1/orders` both previews and places. `mode` is required and has no default, so a request can never place by accident.

| `mode` | What happens | Answer |
| - | - | - |
| `"preview"` | Every rule and limit is applied, and the order is tried as a test order with the bookmakers. Nothing is placed or stored. | `200` with `status: "PREVIEW"` |
| `"place"` | The order is placed. | `201` with the new order, or `200` with the existing one when you resend the same request (see [Idempotency](https://docs.apexiumbet.com/guides/idempotency.md)) |

## The request

```json theme={null}
{
  "mode": "place",
  "clientOrderId": "my-order-0002",
  "fixtureId": "id1000001761300868",
  "outcomeId": 101,
  "playerId": 0,
  "side": "back",
  "bookmakers": ["sharpbet", "betfair-ex"],
  "stake": { "amount": "200.00", "currency": "USD" },
  "minPrice": "1.90",
  "acceptBetterOdds": true,
  "acceptPartialStake": true,
  "expiresAt": "2026-10-05T15:00:00.000Z"
}
```

| Field | Meaning |
| - | - |
| `clientOrderId` | Your identifier for the order, unique on your account. It makes retries safe. |
| `fixtureId`, `outcomeId`, `playerId` | The selection, with the market data identifiers. `playerId` defaults to `0` (no player). |
| `side` | `"back"`. Laying is not available in v1. |
| `bookmakers` | Where the stake may go. Omitted, every bookmaker of your account is used. |
| `stake` | The total stake, in the account currency. See [Money](https://docs.apexiumbet.com/guides/money.md). |
| `minPrice` | The lowest price you accept, at least `1.001`. |
| `acceptBetterOdds` | `true` lets a bet fill at a better price than quoted. |
| `acceptPartialStake` | `true` accepts filling only part of the stake. `false` is fill or kill. |
| `expiresAt` | Optional. Keeps working the unfilled remainder until then, at most one hour ahead. |

### How the stake is split

The stake is split across the requested bookmakers that offer a price at or above `minPrice`, within each one's limits. Each part becomes a **bet**. An order can therefore have several bets, at different prices; `averageFilledPrice` is their stake-weighted average.

### Partial fills and expiry

| `acceptPartialStake` | `expiresAt` | Behaviour |
| - | - | - |
| `false` | — | Fill or kill: the whole stake or nothing. |
| `true` | absent | Immediate or cancel: what fills now is kept, the rest is dropped. |
| `true` | set | What fills now is kept, and the remainder keeps being worked until `expiresAt`. |

An order with `expiresAt` stays working until it fills or expires. Cancel it early with [`POST /v1/orders/{id}/cancel`](https://docs.apexiumbet.com/guides/cancellation). Some environments do not offer expiry yet: they answer `503 EXPIRY_NOT_AVAILABLE`, and the same order without `expiresAt` works.

### Bookmakers

* **Your bookmakers.** `GET /v1/me` lists the bookmakers of your account. Asking for another one answers `403 BOOKMAKER_NOT_AVAILABLE`.
* **Bookmakers closed to the API.** A bookmaker can be closed to the API even when it is enabled on your account, and `GET /v1/me` leaves it out. Asking for it answers `400 BOOKMAKER_NOT_AVAILABLE_VIA_API`, and it is never used when `bookmakers` is omitted.

## Preview first

A preview answers with what would be placed now: one entry per bookmaker in `bets`, with its status, stake and price.

```json theme={null}
{
  "clientOrderId": "my-order-0002",
  "status": "PREVIEW",
  "requestedStake": { "amount": "200.00", "amountCents": 20000, "currency": "USD" },
  "filledStake": { "amount": "200.00", "amountCents": 20000, "currency": "USD" },
  "averageFilledPrice": "1.93",
  "bets": [
    { "bookmaker": "sharpbet", "status": "PLACED", "requestedStake": { "amount": "120.00", "amountCents": 12000, "currency": "USD" }, "filledPrice": "1.95" },
    { "bookmaker": "betfair-ex", "status": "PLACED", "requestedStake": { "amount": "80.00", "amountCents": 8000, "currency": "USD" }, "filledPrice": "1.90" }
  ]
}
```

The example is shortened. Prices move: a preview is a good estimate, not a reservation. When nothing can be placed, the preview answers the same error a placement would. To read only the prices and limits, read the betslip with `GET /v1/betslip`: see [Feed odds and the betslip](https://docs.apexiumbet.com/guides/feed-odds-and-betslip.md).

## Rejections

Before anything is sent to a bookmaker, the order is checked: your balance, your limit per fixture, your account's rules, the prices and the liquidity. When a check fails, the request answers an error and nothing is recorded; see [Errors](https://docs.apexiumbet.com/api-reference/errors.md#order-rejections).

Once the order is recorded, a bookmaker can still decline its part. That is not an error: the order comes back, and the declined bet has `status: "REJECTED"` and a `declineReason`. See [Order and bet life cycle](https://docs.apexiumbet.com/guides/order-lifecycle.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.