---
title: "Book a flight against a quote_id"
method: POST
path: "/api/v1/orders"
tags: ["Buying"]
---

# Book a flight against a quote_id

`POST /api/v1/orders`

## Request

- Base URL: `https://neuronsystems.org`
- URL: `https://neuronsystems.org/api/v1/orders`
- Auth: none declared

Books the flight and returns an order_id plus a Stripe Checkout URL for exactly the quoted amount. Price and impressions come from the stored quote. Send an Idempotency-Key header so a retry does not double-book.

## Headers

- `Idempotency-Key` string

## Request body

- CreateOrderRequest
  - `quote_id` string, required: From POST /api/v1/quote.
  - `ad_category` 'general' | 'alcohol' | 'betting', required: What the sponsor sells. alcohol and betting ads are shown only to signed in fans who have told us they are 21 or over; general ads are shown to everyone.
  - `brand_name` string, required
  - `headline` string
  - `click_url` string, uri, required: HTTPS only.
  - `image_url` string, uri: Required for display formats.
  - `voice_script` string: Required for voice_sponsor_read. Maximum 35 words (~15 seconds).
  - `selected_persona` 'The Architect' | 'Marcus' | 'Leo' | 'Sam' | 'Zareena' | 'Big Mike'
  - `track_title` string: Required for music slots.
  - `artist_name` string: Required for music slots.
  - `audio_stream_url` string, uri: Required for music slots.
  - `cover_art_url` string, uri
  - `streaming_platform_url` string, uri
  - `rights_confirmed` boolean: Must be true for music slots: you confirm licensing or ownership.
  - `advertiser_email` string, email
  - `idempotency_key` string

## Response `201`

Order booked; pay at checkout.url.

- OrderResponse
  - `status` string
  - `order` object
    - `order_id` string
    - `quote_id` string
    - `status` 'pending_payment' | 'active' | 'completed' | 'amount_mismatch' | 'expired_unpaid'
    - `impressions_ordered` integer
    - `impressions_delivered` integer
    - `pacing_pct` number
    - `clicks` integer
    - `ctr_pct` number
    - `audio_completes` integer
    - `audio_completion_rate_pct` number, nullable
    - `total_cost_usd` number
    - `paid_at` string, date-time, nullable
  - `checkout` object
    - `url` string, uri: Send the buyer here to pay.
    - `session_id` string
    - `amount_usd` number

## Other responses

- `400`: Request rejected. `code` is machine-readable; `message` says how to correct it.
- `404`: Request rejected. `code` is machine-readable; `message` says how to correct it.
- `409`: Quote expired, already used, or the slot lacks capacity.
- `422`: Creative failed validation for the quoted format.

---

[API](https://skmtc.dev/neuronsystems/apis/neuron-sports-ad-exchange-api.md) · [All operations](https://skmtc.dev/neuronsystems/apis/neuron-sports-ad-exchange-api/llms.txt) · [OpenAPI document](https://skmtc.dev/neuronsystems/apis/neuron-sports-ad-exchange-api/revisions/980421bb95a0?raw)