---
search:
  tags:
    - Orders
    - POST
seo:
  description: >-
    Submits order placement. Reference for the POST /orders endpoint in the REST
    API.
sidebar:
  label: Place an Order
  badge: POST
title: Place an Order
type: openapi-operation
---
Submits order placement.

### Endpoint

- Method and path: `POST /orders`
- Operation ID: `createOrder`
- API reference: [POST /orders](/api-reference/rest/orders/create-order)
- Complete specification: [OpenAPI (YAML)](/openapi.yml)
- Spec location (JSON Pointer): `#/paths/~1orders/post`

#### Authorization

- Accepted credentials: `UDX-Access-Key` header and `UDX-Access-Timestamp` header and `UDX-Access-Signature` header; or Bearer token in `Authorization`
- Details: [Authentication](/reference/authentication)

#### Parameters

```yaml
- $ref: "#/components/parameters/VersionHeader"
- $ref: "#/components/parameters/IdempotencyKeyHeader"
```


#### Request body

Required: yes

Content type: `application/json`

Schema:

```yaml
$ref: "#/components/schemas/CreateOrderRequest"
```

Example: Example

```json
{
  "ticker": "UDX-EXAMPLE-MARKET",
  "client_order_id": "order-20260804-001",
  "side": "buy",
  "quantity": "100",
  "price": "0.55",
  "time_in_force": "gtc"
}
```


#### Responses

##### `202`

Order accepted for processing.

Headers:

```yaml
UDX-Version:
  $ref: "#/components/headers/VersionHeader"
UDX-Idempotent-Replayed:
  $ref: "#/components/headers/IdempotentReplayed"
```

Content type: `application/json`

Schema:

```yaml
$ref: "#/components/schemas/OrderSubmissionResponse"
```

Example: Example

```json
{
  "order": {
    "order_id": "BK9BZNTK8022",
    "client_order_id": "order-20260804-001"
  }
}
```

##### `400`

The request was malformed or the order was rejected at submission.

Headers:

```yaml
UDX-Version:
  $ref: "#/components/headers/VersionHeader"
```

Content type: `application/problem+json`

Schema:

```yaml
$ref: "#/components/schemas/ProblemDetails"
```

Example: Invalid request parameters

```json
{
  "type": "urn:udx:problem:invalid-request-parameters",
  "title": "Bad Request",
  "status": 400,
  "detail": "invalid request parameters",
  "instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef"
}
```

Example: The exchange rejected the order

```json
{
  "type": "urn:udx:problem:order-rejected",
  "title": "Bad Request",
  "status": 400,
  "detail": "Order rejected; it was not placed",
  "instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef"
}
```

##### `401`

No valid credential was provided.

Headers:

```yaml
UDX-Version:
  $ref: "#/components/headers/VersionHeader"
```

Content type: `application/problem+json`

Schema:

```yaml
$ref: "#/components/schemas/ProblemDetails"
```

Example: Authentication failed

```json
{
  "type": "urn:udx:problem:invalid-authentication-credentials",
  "title": "Unauthorized",
  "status": 401,
  "detail": "invalid authentication credentials",
  "instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef"
}
```

##### `403`

The credential lacks the trade scope.

Headers:

```yaml
UDX-Version:
  $ref: "#/components/headers/VersionHeader"
```

Content type: `application/problem+json`

Schema:

```yaml
$ref: "#/components/schemas/ProblemDetails"
```

Example: Insufficient permissions

```json
{
  "type": "urn:udx:problem:insufficient-permissions",
  "title": "Forbidden",
  "status": 403,
  "detail": "insufficient permissions",
  "instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef"
}
```

##### `409`

This idempotency key is still in use, or its request completed with a response too large to replay. The problem type tells the two apart.

Headers:

```yaml
UDX-Version:
  $ref: "#/components/headers/VersionHeader"
```

Content type: `application/problem+json`

Schema:

```yaml
$ref: "#/components/schemas/ProblemDetails"
```

Example: First request still running

```json
{
  "type": "urn:udx:problem:request-with-header-in-progress",
  "title": "Conflict",
  "status": 409,
  "detail": "a request with this UDX-Idempotency-Key is already in progress",
  "instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef"
}
```

Example: Completed without a replayable response

```json
{
  "type": "urn:udx:problem:response-too-large-to-replay",
  "title": "Conflict",
  "status": 409,
  "detail": "this request already executed, but its response was too large to replay; do not resend it with a fresh UDX-Idempotency-Key, read the affected resource to confirm the result",
  "instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef"
}
```

##### `422`

This idempotency key belongs to a different request.

Headers:

```yaml
UDX-Version:
  $ref: "#/components/headers/VersionHeader"
```

Content type: `application/problem+json`

Schema:

```yaml
$ref: "#/components/schemas/ProblemDetails"
```

Example: Example

```json
{
  "type": "urn:udx:problem:header-used-for-different-request",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "UDX-Idempotency-Key was already used for a different request",
  "instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef"
}
```

##### `429`

The member rate limit was exceeded.

Headers:

```yaml
UDX-Version:
  $ref: "#/components/headers/VersionHeader"
Retry-After:
  $ref: "#/components/headers/RetryAfter"
Cache-Control:
  $ref: "#/components/headers/NoStore"
```

Content type: `application/problem+json`

Schema:

```yaml
$ref: "#/components/schemas/ProblemDetails"
```

Example: Example

```json
{
  "type": "urn:udx:problem:member-rate-limit-exceeded",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "this member has temporarily exceeded its request rate",
  "instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef"
}
```

##### `500`

Something went wrong on UDX's side.

Headers:

```yaml
UDX-Version:
  $ref: "#/components/headers/VersionHeader"
```

Content type: `application/problem+json`

Schema:

```yaml
$ref: "#/components/schemas/ProblemDetails"
```

Example: Internal server error

```json
{
  "type": "urn:udx:problem:internal-error",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "internal error",
  "instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef"
}
```

##### `503`

Either request admission is temporarily unavailable, or the submission itself failed indeterminately: the exchange may or may not have received the order.

Headers:

```yaml
UDX-Version:
  $ref: "#/components/headers/VersionHeader"
Cache-Control:
  $ref: "#/components/headers/NoStore"
Retry-After:
  $ref: "#/components/headers/RetryAfter"
```

Content type: `application/problem+json`

Schema:

```yaml
$ref: "#/components/schemas/ProblemDetails"
```

Example: Order may or may not be placed

```json
{
  "type": "urn:udx:problem:order-outcome-unknown",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "the order may or may not have been placed; check your orders before retrying",
  "instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef"
}
```

Example: Admission temporarily unavailable

```json
{
  "type": "urn:udx:problem:request-admission-unavailable",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "request admission is temporarily unavailable",
  "instance": "urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef"
}
```


#### Referenced definitions

The references in the excerpts above resolve to these definitions in the complete specification.

##### `#/components/schemas/CreateOrderRequest`

```yaml
type: object
description: The fields needed to place an order.
required:
  - ticker
  - client_order_id
  - side
  - quantity
  - price
  - time_in_force
properties:
  ticker:
    $ref: "#/components/schemas/Ticker"
  client_order_id:
    $ref: "#/components/schemas/ClientId"
  side:
    $ref: "#/components/schemas/OrderSide"
  quantity:
    $ref: "#/components/schemas/FixedPointQuantity"
  price:
    type: string
    pattern: ^[0-9]+(\.[0-9]{1,6})?$
    maxLength: 24
    description: Limit price in YES price space, in dollars, regardless of side.
    example: "0.55"
  time_in_force:
    $ref: "#/components/schemas/TimeInForce"
  expires_at:
    type: string
    format: date-time
    maxLength: 40
    x-udx-timestamp-context: prospective
    description: The instant a good-till-time order expires. Required when time_in_force is gtt and not accepted with any other time in force.
    example: 2026-01-01T00:01:00.000000Z
  post_only:
    type: boolean
    default: false
    description: If true, the order only ever rests (adds liquidity); an order that would cross the book on placement is rejected. Incompatible with ioc/fok.
  account_id:
    type: string
    minLength: 1
    description: Account to place the order under. Required for an unrestricted API key; an account-restricted key uses its bound account.
    example: "6820943174116859281"
  self_trade_prevention_type:
    $ref: "#/components/schemas/SelfTradePreventionType"
allOf:
  - if:
      properties:
        time_in_force:
          const: gtt
    then:
      required:
        - expires_at
    else:
      not:
        required:
          - expires_at
```

##### `#/components/schemas/Ticker`

```yaml
type: string
minLength: 1
maxLength: 128
description: A human-meaningful natural key naming a single-leg or multi-leg market.
example: UDX-EXAMPLE-MARKET
```

##### `#/components/schemas/ClientId`

```yaml
type: string
description: A client-supplied correlation identifier.
example: client-20260804-001
```

##### `#/components/schemas/OrderSide`

```yaml
type: string
enum:
  - buy
  - sell
description: Order side.
```

##### `#/components/schemas/FixedPointQuantity`

```yaml
type: string
pattern: ^[0-9]+(\.[0-9]{1,2})?$
maxLength: 24
description: A quantity in contracts as a fixed-point decimal string.
example: "100"
```

##### `#/components/schemas/TimeInForce`

```yaml
type: string
enum:
  - gtc
  - ioc
  - fok
  - day
  - gtt
description: How long the order stays active.
```

##### `#/components/schemas/SelfTradePreventionType`

```yaml
type: string
enum:
  - placed
  - resting
description: Which order gives way when an incoming order would match one of the caller's own resting orders.
```

##### `#/components/headers/VersionHeader`

```yaml
description: API version used for this response.
schema:
  type: string
  maxLength: 10
  description: A dated API version (YYYY-MM-DD).
  example: 2026-07-15
```

##### `#/components/headers/IdempotentReplayed`

```yaml
description: true for a replayed response; omitted otherwise.
schema:
  type: string
  enum:
    - "true"
  description: Always the string true when present.
  example: "true"
```

##### `#/components/schemas/OrderSubmissionResponse`

```yaml
type: object
description: The exchange accepted the order submission for processing.
required:
  - order
properties:
  order:
    $ref: "#/components/schemas/OrderSubmission"
```

##### `#/components/schemas/OrderSubmission`

```yaml
type: object
description: An accepted order submission.
required:
  - order_id
  - client_order_id
properties:
  order_id:
    $ref: "#/components/schemas/EntityId"
  client_order_id:
    $ref: "#/components/schemas/ClientId"
```

##### `#/components/schemas/EntityId`

```yaml
type: string
minLength: 1
description: An exchange-assigned identifier. Treat it as an opaque, stable key with no internal structure.
example: "6820943174116859281"
```

##### `#/components/schemas/ProblemDetails`

```yaml
type: object
description: An RFC 9457 machine-readable error, returned on every non-2xx response. The response's Content-Language header identifies the language used by title and detail, and Vary includes Accept-Language.
required:
  - type
  - title
  - status
properties:
  type:
    type: string
    format: uri-reference
    maxLength: 2048
    description: A stable URN identifying the kind of problem, for example urn:udx:problem:insufficient-permissions. Branch on it rather than on the localized detail. It is an identifier, not a URL to dereference.
  title:
    type: string
    maxLength: 40
    example: Bad Request
    description: A localized, human-readable summary of the error category. Stable for a given status code and resolved language — clients must not use it as a machine-readable discriminator.
  status:
    type: integer
    example: 400
    description: The HTTP status code, repeated from the response itself.
  detail:
    type: string
    maxLength: 500
    example: malformed request body
    description: A localized, human-readable explanation specific to this occurrence. Clients must not parse it for machine-readable information.
  instance:
    type: string
    format: uri-reference
    maxLength: 100
    example: urn:request-id:8f14e45f-ceea-4abc-a743-e89a34d3f6ef
    description: An identifier for this specific occurrence, so it can be correlated with server-side logs if you need to report it.
```

##### `#/components/headers/RetryAfter`

```yaml
description: Whole seconds to wait before retrying.
schema:
  type: integer
  minimum: 1
  description: A positive delay in whole seconds.
  example: 2
```

##### `#/components/headers/NoStore`

```yaml
description: Prevents caching this response.
schema:
  type: string
  enum:
    - no-store
  description: Always the cache directive no-store.
  example: no-store
```

##### `#/components/parameters/VersionHeader`

```yaml
name: UDX-Version
in: header
required: false
description: Dated API version (YYYY-MM-DD).
schema:
  type: string
  minLength: 10
  maxLength: 10
  description: A dated API version (YYYY-MM-DD).
  example: 2026-07-15
```

##### `#/components/parameters/IdempotencyKeyHeader`

```yaml
name: UDX-Idempotency-Key
in: header
required: false
description: Optional client-generated key that makes a mutation safe to retry.
schema:
  type: string
  minLength: 1
  maxLength: 255
  description: A unique, client-generated key identifying this request.
  example: b6f1c2a4-2b7e-4c1a-9c2e-2d1f8a3e4b5c
```