Skip to navigation
API ReferencePurchaseOrders

Place an order

Check out a held cart. On success, tickets are issued and the cart is cleared.

Tickets are inside each items[] entry, not at the top level of the order. Fees are disclosed per item on priceOption.fees.

Authentication

X-TT-API-Keystring
API Key authentication via header

Headers

X-TT-Device-DatastringOptional

JSON describing the device the shopper is buying on — device_id, device_type (web or native), and device_os. Adds signal to card fraud checks, so fewer genuine customers are declined. Omit it when no end-user device is in the request path.

X-TT-PlatformenumRequired
Identifies the platform the request comes from.
Allowed values:
X-TT-RetailerstringRequired
Your retailer identifier, provided during onboarding. It must be a retailer your API key was issued for.
Idempotency-KeystringOptionalformat: "uuid"

Optional UUID v4 identifying an order placement attempt. An invalid key returns 400 INVALID_IDEMPOTENCY_KEY. Reusing a key with a different cart returns 409 IDEMPOTENCY_KEY_CART_MISMATCH.

Request

This endpoint expects an object.
cartIdstringRequiredformat: "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$">=1 character

ID of the cart to buy, from POST /carts.

expectedTotalobjectRequired

Total you expect to be charged — echo the total from a cart response read without a currency query parameter. The order settles in the currency the cart carries, so a total quoted with a currency parameter will not match. To pay in another currency, switch the cart with PATCH first.

contactobjectRequired
Who the order is for.
paymentobjectRequired
How the order is paid.
marketingConsentobjectOptional
Marketing messages the shopper agreed to at checkout. Leave it out when the shopper was not asked.
sendConfirmationEmailboolean or nullOptional
Whether to send the order confirmation email. True requests the email, false suppresses it, and omission uses the retailer default.

Response headers

X-RateLimit-Limitinteger
How many requests this API key may make for this retailer in the current window. Sent only when the request was counted against that limit. A response served from cache was not counted and repeats the value it was cached with.
X-RateLimit-Remaininginteger
How many requests this API key has left for this retailer in the current window. Sent only when the request was counted against that limit. A response served from cache was not counted and repeats the value it was cached with.

Response

The Idempotency-Key already completed an order for this cart. The existing order is returned and nothing is charged or issued again.

dataobject
An order, with its items and tickets.

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
410
Gone Error
429
Too Many Requests Error
500
Internal Server Error