---
title: "Create the order from a quote and start payment (idempotent per quote_id)"
method: POST
path: "/v1/orders"
---

# Create the order from a quote and start payment (idempotent per quote_id)

`POST /v1/orders`

## Request

- Base URL: `https://pod.agentmade.dev`
- URL: `https://pod.agentmade.dev/v1/orders`
- Auth: none declared

## Request body

- PurchaseRequest
  - `quote_id` string: quote_id returned by quote, for one parcel. Set quote_id or orders, not both.
  - `recipient` object: Shipping address. Country, state and postal code must match the quote destination. Send the full address when you have it. If you cannot collect the street address, send only country_code, postal_code (and state_code for US, CA and AU): the person then enters the address on the order page before paying. Required with quote_id.
    - `name` string: Full name of the recipient.
    - `company` string
    - `address1` string: Street and house number.
    - `address2` string: Apartment, floor, etc.
    - `city` string
    - `state_code` string: State or province code. Required for US, CA and AU.
    - `postal_code` string, required
    - `country_code` string, required: ISO 3166-1 alpha-2 country code, e.g. CZ, DE, US.
    - `email` string, email: Recipient email, for carrier delivery notices only. Never used for receipts. For a gift, leave it empty unless the recipient agrees.
    - `phone` string
  - `orders` object[]: Many parcels with one payment: one quote_id and one recipient per parcel. Not live yet: call purchase once per quote_id for now.
    - `quote_id` string, required: quote_id returned by quote.
    - `recipient` object, required: Shipping address. Country, state and postal code must match the quote destination. Send the full address when you have it. If you cannot collect the street address, send only country_code, postal_code (and state_code for US, CA and AU): the person then enters the address on the order page before paying.
      - `name` string, required: Full name of the recipient.
      - `company` string
      - `address1` string, required: Street and house number.
      - `address2` string: Apartment, floor, etc.
      - `city` string, required
      - `state_code` string: State or province code. Required for US, CA and AU.
      - `postal_code` string, required
      - `country_code` string, required: ISO 3166-1 alpha-2 country code, e.g. CZ, DE, US.
      - `email` string, email: Recipient email, for carrier delivery notices only. Never used for receipts. For a gift, leave it empty unless the recipient agrees.
      - `phone` string
  - `contact_email` string, email: Email of the payer, for the order confirmation and the payment receipt. Not the recipient's email: for a gift, the recipient must not see the price. Optional.
  - `payment_capabilities` string[]: Payment methods the calling agent can use. "hosted_checkout" = a link that the person opens to pay by card, Apple Pay or Google Pay. Always supported.
  - `gift_message` string: Short message for the packing slip of a gift. Not printed yet: the answer says so.
  - `rights_attestation` true, required: Must be true: confirms the customer owns or is licensed to print all submitted artwork, and that it is not prohibited content.

## Response `201`

Order with payment URL

- PurchaseResult
  - `order_id` string, required: A bearer key: whoever has it can read and cancel the order. Do not share it publicly.
  - `status` 'AWAITING_PAYMENT' | 'PAID' | 'VALIDATING' | 'SUBMITTING' | 'SUBMITTED' | 'IN_PRODUCTION' | 'SHIPPED' | 'DELIVERED' | 'QUOTE_EXPIRED' | 'PAYMENT_FAILED' | 'REJECTED' | 'SUBMISSION_FAILED' | 'CANCELLED' | 'REFUND_PENDING' | 'REFUNDED' | 'DISPUTED', required
  - `next_step` string, required: What the agent should do next, in plain language.
  - `address_needed` boolean, required: True when purchase had no street address: the person enters it on the order page before paying.
  - `destination` object, nullable, required: While address_needed: the quoted destination.
    - `country_code` string, required
  - `status_reason` string, nullable, required
  - `quote_id` string, required
  - `total` object, required
    - `amount_minor` integer, required: Integer minor units (cents) of `currency`.
    - `currency` string, required
    - `formatted` string, required
  - `order_url` string, required: The order page. The person sees the status there.
  - `payment` object, required
    - `method` string, required
    - `paid` boolean, required: True only after a verified payment.
    - `url` string, nullable, required: While unpaid: the link to give the person who pays.
    - `expires_at` string, nullable, required
    - `instructions` string, nullable, required
    - `note` string, nullable, required
  - `items` object[], required
    - `product_id` string, required
    - `title` string, required
    - `color` string, required
    - `size` string, required
    - `quantity` integer, required
    - `image_url` string, nullable, required
    - `mockups` object[], required: One preview per print side of the ordered design on the product. Show them to the person as the exact print.
      - `placement` string, required
      - `url` string, required
  - `shipments` object[], required
    - `carrier` string, nullable, required
    - `tracking_number` string, nullable, required
    - `tracking_url` string, nullable, required
  - `delivery_estimate_business_days` object, nullable, required: Null when the order ended (cancelled, refunded, rejected, expired or delivered).
    - `min` number, nullable, required
    - `max` number, nullable, required
  - `timeline` object[], required
    - `at` string, required
    - `status` string, nullable, required
    - `note` string, nullable, required
  - `notes` string[], required

## Other responses

- `4XX`: Error with a machine-readable code and a hint for the next step
- `5XX`: Error with a machine-readable code and a hint for the next step

---

[API](https://skmtc.dev/agentmade/apis/agentmade-print-on-demand-api.md) · [All operations](https://skmtc.dev/agentmade/apis/agentmade-print-on-demand-api/llms.txt) · [OpenAPI document](https://skmtc.dev/agentmade/apis/agentmade-print-on-demand-api/revisions/542fad1de43b?raw)