> ## Documentation Index > Fetch the complete documentation index at: https://docs.laces.run/llms.txt > Use this file to discover all available pages before exploring further. # Create an order > Create a cart and hold places. No money moves until you pay it. ## OpenAPI ````yaml api-reference/v1/openapi.json POST /orders openapi: 3.1.0 info: title: Laces Partner API version: 1.0.0 summary: Show your organization's races and sell entries from your own website. description: >- The Laces Partner API, served at `https://connect.laces.run/v1`. Every path is relative to that server URL, which already ends in `/v1`. Authenticate with a **bearer token** from `POST /oauth/token` (server side) or, on the routes that allow it, a **publishable key** in `X-Laces-Publishable-Key` (browser side, from an allowed domain). Keys are uppercase and case-sensitive: send them exactly as issued. There is one environment, production. Payments made through the API are real. Money is integer minor units. Every route except the token endpoint answers in the Laces envelope `{ code, message, data | error, error_code }`; branch on `error_code`, never on `message` or `error`. Every response carries an `X-Request-Id` header (`req_…`). Quote it to support@laces.run when something goes wrong. Browsers can read `X-Request-Id` and `Retry-After` (both are CORS-exposed). Rate-limited routes also send the standard `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` headers. Partner credentials are accepted on this host only. Sent to `api.laces.run` (the Laces app's own API), any partner credential is refused with `401 partner_credential_not_accepted`. contact: name: Laces support email: support@laces.run url: https://docs.laces.run license: name: Proprietary identifier: LicenseRef-Proprietary servers: - url: https://connect.laces.run/v1 description: Production security: - bearerAuth: [] tags: - name: Authentication description: OAuth 2.0 client credentials. - name: Events description: Your organization's races that are on sale. - name: Checkout sessions description: 'Laces-hosted checkout: redirect or embedded.' - name: Orders description: Create, pay and read orders from your own UI. - name: Webhook events description: Requests Laces sends to your webhook endpoint. - name: Health description: Liveness probe. paths: /orders: post: tags: - Orders summary: Create an order description: >- Creates a cart and **holds places** until `hold_expires_at`. No money moves until you [pay it](/api-reference/v1/orders/pay). `Idempotency-Key` is required. A retry with the same key and the same body returns the original response (`200`, "Cart already created (idempotent replay)"); the same key with a different body is `422 idempotency_key_reuse`. `payment_method` sets the price (`momo` = MTN Mobile Money, the default; `airtel` = Airtel Money). Card is coming soon: until it is available, `card` is refused with `409 payment_method_unavailable` (check the event's `payment_methods`). Pick it from the buyer's number: the pay call refuses a number on the other network with `409 reprice_required`. `order.total` in the response is the authoritative amount due. The response's `order` is the same partner order view as [GET /orders/{orderId}](/api-reference/v1/orders/get) (ISO 8601 timestamps, buyer phone in E.164), without `registrations` (those are listed beside it). Bearer token only, scope `orders:write`. The organization must be cleared to take payments (`403 payments_disabled`). operationId: createOrder parameters: - name: Idempotency-Key in: header required: true description: >- Any unique string you generate (a UUID is ideal), stored with your cart and **reused on every retry** of the same action. Scoped to your API client. schema: type: string maxLength: 255 example: 6f1c3c9e-2f4b-4c64-9a2f-0d1c5a8b7e11 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateOrderRequest' example: event_id: q3Zk9mVx lines: - ticket_type_id: tt_10k quantity: 1 participants: - distance_km: 10 buyer_name: Amina Nakato buyer_email: amina@example.com buyer_phone: '0763494235' payment_method: momo waiver_accepted: true waiver_version: '2026-09-01' custom_fields: kit_size: M partner_reference: cart-8841 responses: '200': description: Idempotent replay of an earlier request with the same key. content: application/json: schema: type: object required: - code - message - data properties: code: type: integer description: HTTP status, repeated in the body. examples: - 200 message: type: string examples: - Cart already created (idempotent replay) data: $ref: '#/components/schemas/CreateOrderData' example: code: 200 message: Cart already created (idempotent replay) data: order: id: Hk2mQ8vR order_code: LC-7K2M9X event_id: q3Zk9mVx status: cart currency: UGX subtotal: 50000 discount_total: 0 donation_total: 0 laces_fee: 2400 total: 52400 failure_kind: null ticket_count: 1 buyer: name: Amina Nakato email: amina@example.com phone: '+256763494235' attribution: channel: partner_api api_client_id: LCSCLI-EXAMPLECLNT2345EXAMP checkout_session_id: null partner_reference: cart-8841 hold_expires_at: '2026-10-09T08:29:03.000Z' created_at: '2026-10-09T08:14:03.000Z' checkout_lines: - label: Subtotal amount: 50000 - label: Laces Service Fee amount: 2400 - label: Total amount: 52400 is_free: false is_test_mode: false fee_rate: flat_fee: 0 percent_fee: 0 currency: UGX payment_method: momo registrations: - id: rg_5TfK2 ticket_type_id: tt_10k distance_km: 10 status: pending event_name: Kampala City 10K event_when_label: Sun 15 Nov 2026, 7:00 AM headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' '201': description: Cart created. content: application/json: schema: type: object required: - code - message - data properties: code: type: integer description: HTTP status, repeated in the body. examples: - 201 message: type: string examples: - Cart created successfully data: $ref: '#/components/schemas/CreateOrderData' example: code: 201 message: Cart created successfully data: order: id: Hk2mQ8vR order_code: LC-7K2M9X event_id: q3Zk9mVx status: cart currency: UGX subtotal: 50000 discount_total: 0 donation_total: 0 laces_fee: 2400 total: 52400 failure_kind: null ticket_count: 1 buyer: name: Amina Nakato email: amina@example.com phone: '+256763494235' attribution: channel: partner_api api_client_id: LCSCLI-EXAMPLECLNT2345EXAMP checkout_session_id: null partner_reference: cart-8841 hold_expires_at: '2026-10-09T08:29:03.000Z' created_at: '2026-10-09T08:14:03.000Z' checkout_lines: - label: Subtotal amount: 50000 - label: Laces Service Fee amount: 2400 - label: Total amount: 52400 is_free: false is_test_mode: false fee_rate: flat_fee: 0 percent_fee: 0 currency: UGX payment_method: momo registrations: - id: rg_5TfK2 ticket_type_id: tt_10k distance_km: 10 status: pending event_name: Kampala City 10K event_when_label: Sun 15 Nov 2026, 7:00 AM headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' examples: idempotency_key_required: summary: idempotency_key_required value: code: 400 message: idempotency_key_required error: Idempotency-Key header is required error_code: idempotency_key_required validation_failed: summary: validation_failed value: code: 400 message: Bad request error: 'Missing or invalid fields: buyer_email' error_code: validation_failed waiver_required: summary: waiver_required value: code: 400 message: waiver_required error: This event requires waiver acceptance error_code: waiver_required waiver_version_mismatch: summary: waiver_version_mismatch value: code: 400 message: waiver_version_mismatch error: The waiver has changed; re-read the event error_code: waiver_version_mismatch invalid_payment_method: summary: invalid_payment_method value: code: 400 message: Bad request error: payment_method must be momo, card or airtel error_code: invalid_payment_method distance_required: summary: distance_required value: code: 400 message: Checkout failed error: Choose a distance for each participant error_code: distance_required invalid_json: summary: invalid_json value: code: 400 message: Validation failed error: The request body is not valid JSON error_code: invalid_json invalid_email: summary: invalid_email value: code: 400 message: Validation failed error: buyer_email is not a valid email address error_code: invalid_email invalid_donation_amount: summary: invalid_donation_amount value: code: 400 message: Validation failed error: >- donation_amount must be a non-negative integer in minor units error_code: invalid_donation_amount invalid_partner_reference: summary: invalid_partner_reference value: code: 400 message: Validation failed error: >- partner_reference must be a string of at most 128 characters error_code: invalid_partner_reference ticket_type_not_in_event: summary: ticket_type_not_in_event value: code: 400 message: Checkout failed error: A selected ticket type does not belong to this event error_code: ticket_type_not_in_event invalid_distance: summary: invalid_distance value: code: 400 message: Checkout failed error: distance_km must be a number error_code: invalid_distance distance_not_offered: summary: distance_not_offered value: code: 400 message: Checkout failed error: That distance is not offered by this event error_code: distance_not_offered invalid_discount: summary: invalid_discount value: code: 400 message: Checkout failed error: That discount code is not valid error_code: invalid_discount headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' '401': $ref: '#/components/responses/Unauthorized' '403': description: >- The credential is not allowed here, or the organization cannot take payments yet. headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' content: application/json: schema: $ref: '#/components/schemas/Error' examples: insufficient_scope: summary: insufficient_scope value: code: 403 message: Forbidden error: 'Missing scope: orders:write' error_code: insufficient_scope credential_not_permitted: summary: credential_not_permitted value: code: 403 message: Forbidden error: This endpoint does not accept a publishable key error_code: credential_not_permitted payments_disabled: summary: payments_disabled value: code: 403 message: Checkout failed error: This organizer is not set up to accept payments yet error_code: payments_disabled '404': description: >- The event is not your organization's (or does not exist), or a ticket type does not exist. headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' content: application/json: schema: $ref: '#/components/schemas/Error' examples: not_found: summary: not_found value: code: 404 message: not_found error: Event not found error_code: not_found ticket_type_not_found: summary: ticket_type_not_found value: code: 404 message: Checkout failed error: 'Ticket type not found: tt_10k' error_code: ticket_type_not_found '409': description: The cart can't be created now. content: application/json: schema: $ref: '#/components/schemas/Error' examples: sale_closed: summary: sale_closed value: code: 409 message: Checkout failed error: Registration is closed error_code: sale_closed insufficient_inventory: summary: insufficient_inventory value: code: 409 message: Checkout failed error: Not enough places left error_code: insufficient_inventory ticket_not_on_sale: summary: ticket_not_on_sale value: code: 409 message: Checkout failed error: This ticket is not on sale error_code: ticket_not_on_sale idempotency_in_progress: summary: idempotency_in_progress value: code: 409 message: Conflict error: A request with this key is still being processed error_code: idempotency_in_progress payment_method_unavailable: summary: payment_method_unavailable value: code: 409 message: payment_method_unavailable error: payment_method card is not currently available error_code: payment_method_unavailable headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' '413': $ref: '#/components/responses/PayloadTooLarge' '422': description: The key was already used with different parameters. content: application/json: schema: $ref: '#/components/schemas/Error' examples: idempotency_key_reuse: summary: idempotency_key_reuse value: code: 422 message: Unprocessable error: Idempotency-Key reused with different parameters error_code: idempotency_key_reuse headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/ServerError' security: - bearerAuth: [] - oauth2: - orders:write components: schemas: CreateOrderRequest: type: object properties: event_id: type: string description: Must be your organization's event. examples: - q3Zk9mVx lines: type: array minItems: 1 items: $ref: '#/components/schemas/OrderLine' buyer_name: type: string examples: - Amina Nakato buyer_email: type: string description: Receipts and tickets go here. format: email examples: - amina@example.com buyer_phone: type: string examples: - '0763494235' description: >- The buyer's phone number. Returned in E.164 (`+2567…`) in every order read. payment_method: type: string description: >- **Sets the price.** `momo` (default) is MTN Mobile Money only; `airtel` is Airtel Money only. Choose from the buyer's number: the pay call answers `409 reprice_required` when the number's network does not match. Use only methods in the event's `payment_methods`: `card` is refused with `409 payment_method_unavailable` until card is available (coming soon). enum: - momo - card - airtel default: momo waiver_accepted: type: boolean description: Required (`true`) when the event's `waiver_required` is true. waiver_version: type: string description: >- Required when `waiver_required`; must equal the event's current `waiver_version`. custom_fields: type: object properties: {} description: Answers to `additional_questions`, keyed by `key`. additionalProperties: true discount_code: type: string donation_amount: type: integer description: Minor units. minimum: 0 partner_reference: type: string description: >- Your own reference. Echoed back as `attribution.partner_reference` in order reads and webhooks. maxLength: 128 referral_code: type: string description: Optional referral code. note: type: string description: Optional note on the order. guardian: type: object additionalProperties: true description: Parent or guardian details, when the event requires them for minors. buyer: type: object additionalProperties: true description: Optional extra buyer fields, stored with the order. required: - event_id - lines - buyer_name - buyer_email - buyer_phone CreateOrderData: type: object properties: order: $ref: '#/components/schemas/Order' description: >- The partner order view, as in GET /orders/{orderId} without `registrations`. checkout_lines: type: array description: >- Display lines: Subtotal, Discount, Donation, Laces Service Fee, Total. items: type: object properties: label: type: string amount: type: integer required: - label - amount is_free: type: boolean is_test_mode: type: boolean description: 'Always `false` for partner integrations: every order is real.' fee_rate: type: object properties: flat_fee: type: integer percent_fee: type: number currency: type: string payment_method: type: string enum: - momo - card - airtel required: - flat_fee - percent_fee - currency registrations: type: array items: type: object properties: id: type: string ticket_type_id: type: string distance_km: type: number status: type: string required: - id - ticket_type_id - status event_name: type: string event_when_label: type: string poster_theme: description: >- Display theme of the event's poster, for styling a confirmation. May be null. type: - object - 'null' additionalProperties: true payment_gateway: type: string description: Internal routing hint. Omitted when unknown; ignore it. required: - order - checkout_lines - is_free - is_test_mode - fee_rate - registrations - event_name additionalProperties: true Error: type: object properties: code: type: integer description: HTTP status, repeated in the body. message: type: string description: Short outcome. Do not branch on it; it may be reworded. error: type: string description: Human-readable detail. May be reworded; never parse it. error_code: type: string description: >- Stable machine-readable code. **Branch on this.** Present on every Partner API error, including `429 rate_limited`, `404 not_found` for unknown routes and `500 server_error`. See the [error reference](/concepts/errors). details: type: object properties: retry_after_seconds: type: integer description: Only on `409 prompt_in_progress`. required: - code - message - error - error_code description: The Laces error envelope. OrderLine: type: object properties: ticket_type_id: type: string examples: - tt_10k quantity: type: integer minimum: 1 maximum: 500 participants: type: array description: One object per ticket. items: $ref: '#/components/schemas/Participant' required: - ticket_type_id - quantity Order: type: object properties: id: type: string description: Order id. Pass it to pay and read. examples: - Hk2mQ8vR order_code: type: string description: Human-readable order code shown to the buyer. examples: - LC-7K2M9X event_id: type: string examples: - q3Zk9mVx status: type: string description: Order status. Fulfil only on `paid`. enum: - cart - payment_initiated - prompt_sent - paid - failed - expired - cancelled - refunded - partially_refunded - chargeback_flagged currency: type: string description: ISO 4217 currency code. examples: - UGX subtotal: type: integer description: Ticket prices, minor units. discount_total: type: integer description: Discounts, minor units. donation_total: type: integer description: Donation, minor units. laces_fee: type: integer description: The Laces fee for this cart and payment method, minor units. total: type: integer description: '**Authoritative** amount the buyer pays, minor units.' failure_kind: type: - string - 'null' enum: - provider_not_reached - timed_out - declined - other - null description: >- Why the latest payment attempt failed, as a sanitized bucket; `null` unless the order is `failed` or `expired`. Never the payment provider's own wording. - `provider_not_reached`: the charge never reached the payment provider. **Nothing was charged**; it is safe to retry at once. - `timed_out`: the payer didn't approve in time, or the prompt expired. - `declined`: the payer declined or cancelled, or can't pay (balance, PIN, limit). - `other`: anything else. Treat an unknown value as `other`. See [Why it failed](/guides/custom-ui#why-it-failed-failure-kind). examples: - null ticket_count: type: integer description: Number of tickets. May be absent on some older orders. attribution: type: object properties: channel: type: - string - 'null' description: >- `partner_api` (custom UI), `partner_hosted` (hosted or embedded checkout), or null for an order that did not come through the Partner API. enum: - partner_api - partner_hosted - null api_client_id: type: - string - 'null' description: The API client that created the order. examples: - LCSCLI-EXAMPLECLNT2345EXAMP checkout_session_id: type: - string - 'null' description: The checkout session the order came from. examples: - null partner_reference: type: - string - 'null' description: Your `partner_reference` from order creation. examples: - cart-8841 required: - channel - api_client_id - checkout_session_id - partner_reference description: How the order came in. hold_expires_at: type: - string - 'null' description: When the inventory hold lapses if the order is not paid. format: date-time created_at: type: string format: date-time buyer: type: object properties: name: type: string email: type: string format: email phone: type: string description: E.164, for example `+256763494235`. examples: - '+256763494235' description: >- The buyer. Keys are omitted when empty; `phone` is E.164 (`+256763494235`). **Personal data.** required: - id - order_code - event_id - status - currency - subtotal - discount_total - donation_total - laces_fee - total - attribution - hold_expires_at - created_at description: >- An order as the Partner API shows it. Provider internals, processing fees and idempotency keys are never included. Participant: type: object properties: distance_km: type: number description: >- Required when the event offers distances. Inherited by the rest of the line when only the first participant sets it. description: >- Per-ticket participant details. Extra keys are passed through to the registration. additionalProperties: true headers: X-Request-Id: description: >- Unique id of this request (`req_…`). On every response, readable from browsers. Quote it to support. schema: type: string example: req_V1StGXR8Z5jdHi6BmyTq Retry-After: description: Whole seconds to wait before retrying. Readable from browsers. schema: type: integer RateLimit-Limit: description: Requests allowed in the current window. schema: type: integer RateLimit-Remaining: description: Requests left in the current window. schema: type: integer RateLimit-Reset: description: Seconds until the window resets. schema: type: integer responses: Unauthorized: description: >- No credential, an invalid or expired token, or an invalid publishable key. Comes with `WWW-Authenticate: Bearer realm="laces-partner"`. Revoking or regenerating keys can take up to a minute to reach every server. content: application/json: schema: $ref: '#/components/schemas/Error' examples: unauthorized: summary: unauthorized value: code: 401 message: Unauthorized error: Missing credentials error_code: unauthorized invalid_token: summary: invalid_token value: code: 401 message: Unauthorized error: Invalid or expired access token error_code: invalid_token invalid_key: summary: invalid_key value: code: 401 message: Unauthorized error: Invalid publishable key error_code: invalid_key headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' PayloadTooLarge: description: The body is over 1 MB. headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' content: application/json: schema: $ref: '#/components/schemas/Error' examples: payload_too_large: summary: payload_too_large value: code: 413 message: Validation failed error: The request body is too large error_code: payload_too_large RateLimited: description: >- Rate limited. Wait `Retry-After` seconds. Limits are per API client (reads about 300 a minute, writes about 60) and, for publishable keys, also per IP (about 120 a minute). headers: Retry-After: $ref: '#/components/headers/Retry-After' RateLimit-Limit: $ref: '#/components/headers/RateLimit-Limit' RateLimit-Remaining: $ref: '#/components/headers/RateLimit-Remaining' RateLimit-Reset: $ref: '#/components/headers/RateLimit-Reset' X-Request-Id: $ref: '#/components/headers/X-Request-Id' content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 429 message: Too many requests, please slow down error: rate_limited error_code: rate_limited ServerError: description: >- Unexpected failure. Retry with backoff, reusing the same `Idempotency-Key`. content: application/json: schema: $ref: '#/components/schemas/Error' examples: server_error: summary: server_error value: code: 500 message: An unexpected error occurred error: Something went wrong error_code: server_error headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: LCSTOK-…-X (opaque) description: >- A token from `POST /oauth/token`, valid 1 hour. Paste it as `LCSTOK-…-X` (without the word Bearer). oauth2: type: oauth2 description: >- OAuth 2.0 client credentials. The token it yields is the `bearerAuth` token. flows: clientCredentials: tokenUrl: https://connect.laces.run/v1/oauth/token scopes: events:read: List and read events orders:write: Create and pay orders orders:read: >- List and read orders, including buyer personal data (off by default) checkout_sessions:write: Create and read checkout sessions ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.