Place the order and get the payment link
purchaseIdempotent
Turn a quote into an order. Needs quote_id, the full recipient address (it must match the quoted destination) and rights_attestation=true. contact_email is the payer's own email, never the gift recipient's. Returns order_id and payment.url: the order page where the person pays by card, Apple Pay or Google Pay. Nothing is printed until the payment is confirmed. Idempotent per quote_id.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| orders | No | 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 | No | quote_id returned by quote, for one parcel. Set quote_id or orders, not both. | |
| recipient | No | 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. | |
| gift_message | No | Short message for the packing slip of a gift. Not printed yet: the answer says so. | |
| contact_email | No | 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. | |
| rights_attestation | Yes | Must be true: confirms the customer owns or is licensed to print all submitted artwork, and that it is not prohibited content. | |
| payment_capabilities | No | 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. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | ||
| notes | Yes | ||
| total | Yes | ||
| status | Yes | ||
| payment | Yes | ||
| order_id | Yes | A bearer key: whoever has it can read and cancel the order. Do not share it publicly. | |
| quote_id | Yes | ||
| timeline | Yes | ||
| next_step | Yes | What the agent should do next, in plain language. | |
| order_url | Yes | The order page. The person sees the status there. | |
| shipments | Yes | ||
| destination | Yes | While address_needed: the quoted destination. | |
| status_reason | Yes | ||
| address_needed | Yes | True when purchase had no street address: the person enters it on the order page before paying. | |
| delivery_estimate_business_days | Yes | Null when the order ended (cancelled, refunded, rejected, expired or delivered). |