> For the complete documentation index, see [llms.txt](https://docs.getpurpledot.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.getpurpledot.com/docs/purple-dot-apis/private-api/pre-orders.md).

# /pre-orders

## List pre-orders

> Lists pre-orders. With the platform integration and combined cart, in-stock purchases made through Purple Dot’s checkout are not included.

```json
{"openapi":"3.1.0","info":{"title":"Purple Dot Private API","version":"v1"},"tags":[{"name":"/pre-orders"}],"servers":[{"url":"https://www.purpledotprice.com/admin/api/v1","description":"Production"}],"security":[{"accessToken":[]}],"components":{"securitySchemes":{"accessToken":{"type":"apiKey","in":"header","name":"X-Purple-Dot-Access-Token","description":"Your store's private access token. It can also be sent as `Authorization: Bearer <token>`."}},"schemas":{"Pre-order":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Purple Dot ID of the pre-order."},"order_number":{"type":"string"},"reference":{"type":"string","description":"Order reference shared with shoppers."},"cancel_reason":{"type":["string","null"]},"cancelled_at":{"type":["string","null"],"description":"When the whole order was cancelled, or `null`."},"created_at":{"type":"string","format":"date-time","description":"When the pre-order was placed."},"placed_at":{"type":"string","format":"date-time","description":"When the pre-order was placed."},"updated_at":{"type":"string","format":"date-time","description":"When the pre-order was last updated."},"currency":{"type":"string","description":"Presentment currency."},"email":{"type":"string"},"customer":{"type":"object","properties":{"external_id":{"type":["string","null"],"description":"The platform customer ID, if known."},"email":{"type":"string"}},"required":["external_id","email"]},"line_items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"sku":{"type":["string","null"]},"product_id":{"type":"string"},"variant_id":{"type":"string"},"waitlist_id":{"type":["string","null"],"format":"uuid"},"quantity":{"type":"integer"},"price":{"type":"number","description":"Unit price."},"total":{"type":"number"},"total_discount":{"type":"number"},"discount_allocations":{"type":"array","items":{"type":"object","properties":{"amount":{"type":"number"},"discount_application_index":{"type":"integer"}},"required":["amount","discount_application_index"]}},"taxable":{"type":"boolean"},"tax_lines":{"type":"array","items":{"type":"object","properties":{"price":{"type":"number","description":"Total tax amount."},"rate":{"type":"number","description":"Tax rate as a decimal."},"title":{"type":"string","description":"Name of the tax."},"inclusive":{"type":"boolean","description":"Whether the tax is already in the price."}},"required":["price","rate","title","inclusive"]}}},"required":["id","name","sku","product_id","variant_id","waitlist_id","quantity","price","total","total_discount","discount_allocations","taxable","tax_lines"]}},"shipping_address":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":["string","null"]},"address1":{"type":"string"},"address2":{"type":["string","null"]},"city":{"type":"string"},"postal_code":{"type":"string"},"province_code":{"type":["string","null"]},"country":{"type":"string"},"country_code":{"type":"string"},"phone":{"type":["string","null"]}},"required":["first_name","last_name","address1","address2","city","postal_code","province_code","country","country_code","phone"]},"shipping_lines":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"title":{"type":"string"},"price":{"type":"number"},"total":{"type":"number"},"tax_lines":{"type":"array","items":{"type":"object","properties":{"price":{"type":"number","description":"Total tax amount."},"rate":{"type":"number","description":"Tax rate as a decimal."},"title":{"type":"string","description":"Name of the tax."},"inclusive":{"type":"boolean","description":"Whether the tax is already in the price."}},"required":["price","rate","title","inclusive"]}}},"required":["code","title","price","total","tax_lines"]}},"subtotal_price":{"type":"number","description":"Line item total before tax and shipping."},"tax_lines":{"type":"array","items":{"type":"object","properties":{"price":{"type":"number","description":"Total tax amount."},"rate":{"type":"number","description":"Tax rate as a decimal."},"title":{"type":"string","description":"Name of the tax."}},"required":["price","rate","title"]}},"tax_included":{"type":"boolean","description":"Whether listed prices already include tax."},"total_discounts":{"type":"number"},"total_price":{"type":"number"},"total_tax":{"type":"number"},"total_refunded":{"type":"number","description":"Sum of all refunds issued."},"discount_applications":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"allocation_method":{"type":"string"},"target_type":{"type":"string"},"type":{"type":"string"},"value":{"type":"number"},"value_type":{"type":"string"}},"required":["code","allocation_method","target_type","type","value","value_type"]}},"discount_codes":{"type":"array","items":{"type":"object","properties":{"amount":{"type":"number"},"code":{"type":"string"},"type":{"type":"string"}},"required":["amount","code","type"]}},"exported_orders":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["SHOPIFY_ORDER","SFCC_ORDER","PURPLE_DOT_FULFILLMENT_ORDER"]},"id":{"type":"string","description":"The ID of the order in your platform, or the Purple Dot fulfillment order ID."},"order_number":{"type":"string"},"created_at":{"type":"string"},"line_items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The platform line item ID."},"line_item_id":{"type":"string","description":"The Purple Dot line item ID."},"quantity":{"type":"number"}},"required":["id","line_item_id"]}}},"required":["type","id","order_number","created_at","line_items"]},"description":"Orders created in your platform from this pre-order."},"sales_channel":{"type":"string","enum":["online","pos"]},"pos_sale":{"type":["object","null"],"properties":{"cashier_staff_name":{"type":"string"},"staff_name":{"type":"string"},"location_name":{"type":"string"}},"required":["cashier_staff_name","staff_name","location_name"],"description":"Set if placed through Purple Dot POS."}},"required":["id","order_number","reference","cancel_reason","cancelled_at","created_at","placed_at","updated_at","currency","email","customer","line_items","shipping_address","shipping_lines","subtotal_price","tax_lines","tax_included","total_discounts","total_price","total_tax","total_refunded","discount_applications","discount_codes","exported_orders","sales_channel","pos_sale"]},"AuthErrorResponse":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"ErrorResponse":{"type":"object","properties":{"meta":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable message."},"errorData":{"type":"object","additionalProperties":{},"description":"Structured detail about the error."}},"required":["error","errorData"]},"data":{"type":"object","properties":{}}},"required":["meta","data"]}}},"paths":{"/pre-orders":{"get":{"tags":["/pre-orders"],"summary":"List pre-orders","description":"Lists pre-orders. With the platform integration and combined cart, in-stock purchases made through Purple Dot’s checkout are not included.","parameters":[{"schema":{"type":"integer","default":10,"description":"Number of pre-orders to return. Defaults to 10, maximum 200."},"required":false,"description":"Number of pre-orders to return. Defaults to 10, maximum 200.","name":"limit","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Returns pre-orders after the given pre-order ID."},"required":false,"description":"Returns pre-orders after the given pre-order ID.","name":"starting_after","in":"query"},{"schema":{"type":"string","description":"Comma-separated, URL-encoded Purple Dot order references."},"required":false,"description":"Comma-separated, URL-encoded Purple Dot order references.","name":"references","in":"query"},{"schema":{"type":"string","description":"Pre-orders created at or after this time."},"required":false,"description":"Pre-orders created at or after this time.","name":"created_at_min","in":"query"},{"schema":{"type":"string","description":"Pre-orders updated at or after this time."},"required":false,"description":"Pre-orders updated at or after this time.","name":"updated_at_min","in":"query"},{"schema":{"type":"string","description":"Pre-orders updated at or before this time."},"required":false,"description":"Pre-orders updated at or before this time.","name":"updated_at_max","in":"query"},{"schema":{"type":"string","description":"Matches pre-orders where every line item has one of the listed states (comma-separated). Supported: `cancelled`, `exported`."},"required":false,"description":"Matches pre-orders where every line item has one of the listed states (comma-separated). Supported: `cancelled`, `exported`.","name":"all_line_items","in":"query"},{"schema":{"type":"string","description":"Matches pre-orders where at least one line item has one of the listed states (comma-separated). Supported: `cancelled`, `exported`. Cannot be combined with `all_line_items`."},"required":false,"description":"Matches pre-orders where at least one line item has one of the listed states (comma-separated). Supported: `cancelled`, `exported`. Cannot be combined with `all_line_items`.","name":"some_line_item","in":"query"},{"schema":{"type":"string","description":"Comma-separated product variant SKUs."},"required":false,"description":"Comma-separated product variant SKUs.","name":"skus","in":"query"},{"schema":{"type":"string","description":"Pre-orders placed by this email address."},"required":false,"description":"Pre-orders placed by this email address.","name":"email","in":"query"}],"responses":{"200":{"description":"A page of pre-orders.","headers":{"Link":{"description":"Links to the previous and next pages of results. For compatibility, relations use the legacy `rel={next}` and `rel={previous}` syntax.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","properties":{"result":{"type":"string","enum":["success"]}},"required":["result"]},"data":{"type":"object","properties":{"orders":{"type":"array","items":{"$ref":"#/components/schemas/Pre-order"}},"has_more":{"type":"boolean","description":"Whether more results are available after this page."},"starting_after":{"type":["string","null"],"format":"uuid","description":"ID of the last item returned. Pass it as `starting_after`."},"previous_cursor":{"type":["string","null"],"format":"uuid"}},"required":["orders","has_more","starting_after","previous_cursor"]}},"required":["meta","data"]}}}},"400":{"description":"Missing access token. The limit is above 200, or both `all_line_items` and `some_line_item` were passed.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/AuthErrorResponse"},{"$ref":"#/components/schemas/ErrorResponse"}]}}}},"401":{"description":"Access token not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthErrorResponse"}}}}}}}}}
```
