---
title: "Create or simulate an order"
method: POST
path: "/orders"
tags: ["Commerce"]
---

# Create or simulate an order

`POST /orders`

## Request

- Base URL: `https://nautilinks.co/api/v1/agent`
- URL: `https://nautilinks.co/api/v1/agent/orders`
- Auth: HTTP bearer

Creates a 1-20 item backlink order. A live key may spend existing prepaid credit immediately; any card remainder is returned as a Stripe URL that a human must open. A sandbox key validates and prices the same payload without writes or charges. Reuse the same Idempotency-Key after timeouts.

## Headers

- `Idempotency-Key` string

## Request body

- CreateOrderRequest
  - `items` OrderItemInput[], required
    - `site_id` integer, required
    - `target_url` string, uri, required
    - `anchor_text` string, required
    - `anchor_type` 'exact' | 'partial' | 'branded' | 'generic' | 'naked'
    - `content_brief` string, nullable
    - `format` 'article_unitaire' | 'lien_insere'
    - `article_id` integer, nullable: Required when format is lien_insere.
    - `tier2_pack_size` 0 | 1 | 3 | 5
    - `project_id` integer, nullable
  - `promo_code` string
  - `sandbox_credit_cents` integer: Sandbox keys only: simulated prepaid balance used to test payment branches.

## Response `200`

Created, pending-payment, or sandbox order result. Inspect `payment_url`, `sandbox`, and `order_status` instead of assuming money moved.

- CreateOrderResponse
  - `ok` true, required
  - `sandbox` boolean
  - `quote_id` string, nullable
  - `order_id` string, nullable
  - `order_status` string, required
  - `payment_url` string, uri, nullable, required: A human must open this URL when non-null.
  - `items_count` integer, required
  - `would_require_human_payment` boolean
  - `applied_discount_code` string, nullable
  - `gross_total_eur` number
  - `total_eur` number
  - `discount_eur` number
  - `credit_applied_cents` integer
  - `card_amount_cents` integer
  - `amounts` Amounts, required
    - `gross_cents` integer, required
    - `discount_cents` integer, required
    - `net_cents` integer, required
    - `credit_cents` integer, required
    - `card_cents` integer, required

## Other responses

- `400`: The request is syntactically or semantically invalid.
- `401`: The API key is missing, invalid, or revoked.
- `403`: The key lacks the required scope or resource ownership.
- `404`: The resource does not exist or is not visible to this account.
- `409`: The request conflicts with current inventory, payment, or idempotency state.
- `429`: The request quota or rolling daily order cap was reached.
- `500`: Nautilinks encountered an unexpected internal error.
- `503`: A required payment or upstream service is temporarily unavailable.
- `default`: Any non-success status not listed explicitly uses the same typed error envelope.

---

[API](https://skmtc.dev/nautilinks/apis/nautilinks-agent-api.md) · [All operations](https://skmtc.dev/nautilinks/apis/nautilinks-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/nautilinks/apis/nautilinks-agent-api/revisions/7a2b1a00e40c?raw)