Queek docs
Storefront endpoint reference

Orders

GET
/store/orders

Lists the signed-in customer’s orders at this store, newest first, one page at a time: walk with starting_after = the previous next_cursor while has_more is true, or read page=N. No totals or page counts are sent. Filter with status (all|ongoing|pending|delivered|completed, default all) and service (the store’s service slug, e.g. fashion).

Authorization

clientKey customerToken
X-Client-Key<token>

The connection's key (Dashboard → Channels → Headless API; keys are also listed in Settings → Connections). pk_… public keys are for browser code and only work from a website listed on the connection (a website connection never accepts *; a development connection on a dev store also allows localhost); sk_… private keys are for servers and native apps and need no Origin.

In: header

AuthorizationBearer <token>

The customer access credential from any sign-in session answer (access_token). Account operations only — send as Authorization: Bearer <access_token> ALONGSIDE X-Client-Key. It is bound to one store: a credential issued for another vendor answers 403 here.

In: header

Query Parameters

per_page?integer

Orders per page (default 10, max 50; alias of limit).

Range1 <= value <= 50
Default10
service?string

Only orders placed under this service of the store (its service slug, e.g. fashion).

starting_after?string

Keyset cursor: pass the previous page next_cursor. Walk while has_more is true; a stale, tampered, cross-list or filter-changed cursor answers 422 validation_failed with the failure on starting_after. Never combine with page.

limit?integer

Items per read (alias of per_page, max 50). page mode caps at page 50 (a deeper page answers 422 validation_failed on page); walk the cursor past that.

Header Parameters

X-Client-Key*string

Your connection's key (Dashboard → Channels → Headless API; keys are also listed in Settings → Connections). pk_… public keys are for browser code and only work from a website listed on the connection (a website connection never accepts *; a development connection on a dev store also allows localhost); sk_… private keys are for servers and native apps and need no Origin.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/store/orders?per_page=10&limit=10" \  -H "X-Client-Key: {{clientKey}}"
{  "status": "success",  "message": "Orders retrieved",  "data": [    {      "id": "019b0c4d-5e6f-7a8b-9c0d-1e2f3a4b5c91",      "p_id": 74101,      "title": "Northwind Goods",      "currency": "USD",      "total_price": "60.00",      "delivery_fee": "0.00",      "grand_total": "51.00",      "payment_status": "paid",      "is_paid": true,      "is_payable": false,      "amount_paid": "51.00",      "refunded_total": "0.00",      "balance_due": "0.00",      "is_verified": true,      "order_no": "26-0925-74101",      "status": "processing",      "order_type": "instant",      "scheduled_date": null,      "scheduled_time": null,      "is_backorder_held": false,      "backorder_ready_date": null,      "delivery_method": "pickup",      "payment_method": "online",      "delivery_address": null,      "pickup_address": null,      "stage": 0,      "earliest_delivery_time": null,      "latest_delivery_time": null,      "ready_window": null,      "vendor": {        "id": "019b0c4d-5e6f-7a8b-9c0d-1e2f3a4b5c01",        "name": "Northwind Goods",        "slug": "northwind-goods",        "logo": "https://media.usequeek.com/uploads/stores/2207/logo.png",        "address": "14 Mercer Street, New York, NY 10013",        "phone": "+1 202 555 0147",        "email": "[email protected]",        "map_lat": "40.7243000",        "map_lng": "-73.9997000"      },      "created_by_id": null,      "timeline": [        {          "title": "Order Received",          "description": "Waiting for Northwind Goods to accept your order.",          "time": null        },        {          "title": "Preparing Your Order",          "description": "Your order is being prepared and will be ready for pickup soon.",          "time": null        },        {          "title": "Ready for Pickup",          "description": "Your order is ready! Head over to Northwind Goods to pick it up.",          "time": null        },        {          "title": "Picked Up",          "description": "Your order has been picked up. Enjoy!",          "time": null        }      ],      "vendor_timeline": [        {          "title": "Order Received",          "description": "New order received for pickup.",          "time": null        },        {          "title": "Preparing Your Order",          "description": "You accepted the order and started preparation.",          "time": null        },        {          "title": "Ready for Pickup",          "description": "Order is ready — awaiting customer pickup.",          "time": null        },        {          "title": "Picked Up",          "description": "Order has been picked up by the customer.",          "time": null        }      ],      "vendor_note": null,      "rider_note": null,      "shopforme_fee": "0.00",      "service_fee": "0.00",      "is_confirmed": false,      "rejected": false,      "is_completed": false,      "cancelled": false,      "items_count": null,      "started_at": null,      "completed_at": null,      "created_at": "10:58am, 25/9/2026",      "placed_at": null,      "awaiting_payment": true,      "updated_at": "11:20am, 25/9/2026",      "metafields": {}    },    {      "id": "019b0c4d-5e6f-7a8b-9c0d-1e2f3a4b5c94",      "p_id": 74102,      "title": "Northwind Goods",      "currency": "USD",      "total_price": "60.00",      "delivery_fee": "0.00",      "grand_total": "51.00",      "payment_status": "pending",      "is_paid": false,      "is_payable": true,      "amount_paid": "0.00",      "refunded_total": "0.00",      "balance_due": "51.00",      "is_verified": false,      "order_no": "26-0926-74102",      "status": "pending_payment",      "order_type": "instant",      "scheduled_date": null,      "scheduled_time": null,      "is_backorder_held": false,      "backorder_ready_date": null,      "delivery_method": "pickup",      "payment_method": "online",      "delivery_address": null,      "pickup_address": null,      "stage": 0,      "vendor": {        "id": "019b0c4d-5e6f-7a8b-9c0d-1e2f3a4b5c01",        "name": "Northwind Goods",        "slug": "northwind-goods",        "logo": "https://media.usequeek.com/uploads/stores/2207/logo.png",        "address": "14 Mercer Street, New York, NY 10013",        "phone": "+1 202 555 0147",        "email": "[email protected]",        "map_lat": "40.7243000",        "map_lng": "-73.9997000"      },      "created_by_id": null,      "timeline": [        {          "title": "Order Received",          "description": "Waiting for Northwind Goods to accept your order.",          "time": null        },        {          "title": "Preparing Your Order",          "description": "Your order is being prepared and will be ready for pickup soon.",          "time": null        },        {          "title": "Ready for Pickup",          "description": "Your order is ready! Head over to Northwind Goods to pick it up.",          "time": null        },        {          "title": "Picked Up",          "description": "Your order has been picked up. Enjoy!",          "time": null        }      ],      "vendor_timeline": [        {          "title": "Order Received",          "description": "New order received for pickup.",          "time": null        },        {          "title": "Preparing Your Order",          "description": "You accepted the order and started preparation.",          "time": null        },        {          "title": "Ready for Pickup",          "description": "Order is ready — awaiting customer pickup.",          "time": null        },        {          "title": "Picked Up",          "description": "Order has been picked up by the customer.",          "time": null        }      ],      "vendor_note": null,      "rider_note": null,      "shopforme_fee": "0.00",      "service_fee": "0.00",      "is_confirmed": false,      "rejected": false,      "is_completed": false,      "cancelled": false,      "items_count": null,      "started_at": null,      "completed_at": null,      "created_at": "10:58am, 25/9/2026",      "placed_at": null,      "awaiting_payment": true,      "updated_at": "11:20am, 25/9/2026",      "metafields": {}    }  ],  "has_more": false,  "next_cursor": null}
GET
/store/orders/{id}

Retrieves one of the signed-in customer’s orders with its items and amounts. {id} accepts the UUID id or the human order_no (e.g. 26-0925-74101) — the example calls the latter.

Authorization

clientKey customerToken
X-Client-Key<token>

The connection's key (Dashboard → Channels → Headless API; keys are also listed in Settings → Connections). pk_… public keys are for browser code and only work from a website listed on the connection (a website connection never accepts *; a development connection on a dev store also allows localhost); sk_… private keys are for servers and native apps and need no Origin.

In: header

AuthorizationBearer <token>

The customer access credential from any sign-in session answer (access_token). Account operations only — send as Authorization: Bearer <access_token> ALONGSIDE X-Client-Key. It is bound to one store: a credential issued for another vendor answers 403 here.

In: header

Path Parameters

id*string

The order id (UUID) or its order number. Only the caller's own orders resolve.

Header Parameters

X-Client-Key*string

Your connection's key (Dashboard → Channels → Headless API; keys are also listed in Settings → Connections). pk_… public keys are for browser code and only work from a website listed on the connection (a website connection never accepts *; a development connection on a dev store also allows localhost); sk_… private keys are for servers and native apps and need no Origin.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/store/orders/26-0925-74101" \  -H "X-Client-Key: {{clientKey}}"
{  "data": {    "id": "019b0c4d-5e6f-7a8b-9c0d-1e2f3a4b5c91",    "p_id": 74101,    "title": "Northwind Goods",    "currency": "USD",    "total_price": "60.00",    "delivery_fee": "0.00",    "grand_total": "51.00",    "payment_status": "paid",    "is_paid": true,    "is_payable": false,    "amount_paid": "51.00",    "refunded_total": "0.00",    "balance_due": "0.00",    "is_verified": true,    "order_no": "26-0925-74101",    "status": "processing",    "order_type": "instant",    "scheduled_date": null,    "scheduled_time": null,    "is_backorder_held": false,    "backorder_ready_date": null,    "delivery_method": "pickup",    "payment_method": "online",    "delivery_address": null,    "pickup_address": null,    "table": null,    "stage": 0,    "earliest_delivery_time": null,    "latest_delivery_time": null,    "ready_window": null,    "vendor": {      "id": "019b0c4d-5e6f-7a8b-9c0d-1e2f3a4b5c01",      "name": "Northwind Goods",      "slug": "northwind-goods",      "logo": "https://media.usequeek.com/uploads/stores/2207/logo.png",      "address": "14 Mercer Street, New York, NY 10013",      "phone": "+1 202 555 0147",      "email": "[email protected]",      "map_lat": "40.7243000",      "map_lng": "-73.9997000"    },    "created_by_id": null,    "timeline": [      {        "title": "Order Received",        "description": "Waiting for Northwind Goods to accept your order.",        "time": null      },      {        "title": "Preparing Your Order",        "description": "Your order is being prepared and will be ready for pickup soon.",        "time": null      },      {        "title": "Ready for Pickup",        "description": "Your order is ready! Head over to Northwind Goods to pick it up.",        "time": null      },      {        "title": "Picked Up",        "description": "Your order has been picked up. Enjoy!",        "time": null      }    ],    "vendor_timeline": [      {        "title": "Order Received",        "description": "New order received for pickup.",        "time": null      },      {        "title": "Preparing Your Order",        "description": "You accepted the order and started preparation.",        "time": null      },      {        "title": "Ready for Pickup",        "description": "Order is ready — awaiting customer pickup.",        "time": null      },      {        "title": "Picked Up",        "description": "Order has been picked up by the customer.",        "time": null      }    ],    "vendor_note": null,    "rider_note": null,    "shopforme_fee": "0.00",    "service_fee": "0.00",    "is_confirmed": false,    "rejected": false,    "is_completed": false,    "cancelled": false,    "items_count": null,    "started_at": null,    "completed_at": null,    "created_at": "10:58am, 25/9/2026",    "placed_at": null,    "awaiting_payment": true,    "updated_at": "11:20am, 25/9/2026",    "metafields": {},    "status_label": "Processing",    "status_img": "https://api.usequeek.com/images/icon/box.png",    "user_id": "019b0c4d-5e6f-7a8b-9c0d-1e2f3a4b5c51",    "pickup_map_lat": null,    "pickup_map_lng": null,    "items": [      {        "id": "019b0c4d-5e6f-7a8b-9c0d-1e2f3a4b5c92",        "quantity": 1,        "title": "Cotton Midi Dress",        "variant_id": "019b0c4d-5f10-7a02-8c61-0b2d4e6f8a02",        "product_p_id": 31501,        "variant_p_id": 44102,        "variant_title": "M",        "variant_option_values": {          "Size": "M"        },        "variant_media": {          "image": "https://media.usequeek.com/uploads/stores/2207/cotton-midi-dress.jpg",          "video_url": null,          "source": "product"        },        "currency": "USD",        "total_price": "51.00",        "sale_price": "60.00",        "unit_price": "51.00",        "base_unit_price": "60.00",        "is_backorder": false,        "backorder_ready_date": null,        "discounted_amount": "9.00",        "created_at": "2026-09-25T14:58:00.000000Z",        "addons": [],        "properties": []      }    ],    "created_by": null,    "rider": null,    "rider_rating": 0,    "rider_review_status": null,    "vendor_review_status": null,    "vendor_rating": 0,    "virtual_account_id": null,    "payment_link": null,    "pay_link": "https://usequeek.com/store/pay/019b0c4d-5e6f-7a8b-9c0d-1e2f3a4b5c91",    "viewer_type": "customer",    "amount_summary": {      "title": "Order Summary",      "view": "customer",      "items": [        {          "key": "sub_total",          "label": "Sub Total",          "type": "price",          "amount": "60.00"        },        {          "key": "discount",          "label": "Discount",          "type": "discount",          "amount": "18.00"        },        {          "key": "grand_total",          "label": "Grand Total",          "type": "total",          "amount": "51.00"        }      ]    }  }}
GET
/store/orders/{id}/pay

Returns the payment link and data for an unpaid order of the signed-in customer. {id} accepts the UUID id or the human order_no. Only online orders answer a link: anything else 422s.

Authorization

clientKey customerToken
X-Client-Key<token>

The connection's key (Dashboard → Channels → Headless API; keys are also listed in Settings → Connections). pk_… public keys are for browser code and only work from a website listed on the connection (a website connection never accepts *; a development connection on a dev store also allows localhost); sk_… private keys are for servers and native apps and need no Origin.

In: header

AuthorizationBearer <token>

The customer access credential from any sign-in session answer (access_token). Account operations only — send as Authorization: Bearer <access_token> ALONGSIDE X-Client-Key. It is bound to one store: a credential issued for another vendor answers 403 here.

In: header

Path Parameters

id*string

The order id (UUID) or its order number. Only the caller's own orders resolve.

Header Parameters

X-Client-Key*string

Your connection's key (Dashboard → Channels → Headless API; keys are also listed in Settings → Connections). pk_… public keys are for browser code and only work from a website listed on the connection (a website connection never accepts *; a development connection on a dev store also allows localhost); sk_… private keys are for servers and native apps and need no Origin.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/store/orders/26-0926-74102/pay" \  -H "X-Client-Key: {{clientKey}}"
{  "status": "success",  "message": "Order payment details fetched successfully",  "data": {    "order": {      "id": "019b0c4d-5e6f-7a8b-9c0d-1e2f3a4b5c94",      "order_no": "26-0926-74102",      "status": "pending_payment",      "payment_status": "pending",      "payment_method": "online",      "currency": "USD",      "is_payable": true,      "is_paid": false,      "grand_total": "51.00",      "payment_link": "https://pay.usequeek.com/p/northwind-74102",      "pay_link": "https://usequeek.com/store/pay/019b0c4d-5e6f-7a8b-9c0d-1e2f3a4b5c94",      "items": [        {          "id": "019b0c4d-5e6f-7a8b-9c0d-1e2f3a4b5c92",          "quantity": 1,          "title": "Cotton Midi Dress",          "variant_id": "019b0c4d-5f10-7a02-8c61-0b2d4e6f8a02",          "variant_title": "M",          "variant_option_values": {            "Size": "M"          },          "variant_media": null,          "currency": "USD",          "total_price": "51.00",          "sale_price": "60.00",          "unit_price": "51.00",          "base_unit_price": "60.00",          "is_backorder": false,          "backorder_ready_date": null,          "created_at": "2026-09-25T14:58:00.000000Z",          "addons": [],          "properties": {}        }      ]    }  }}
GET
/store/orders/{order}/returns

What the signed-in customer may ask the store to take back from one of their own orders at this store, and the returns already asked for. line_items[] carries each line’s verdict under the store’s current return rules: returnable_quantity, window_ends_at, requestable and, when not, the refusal; self_serve is false when the store takes no requests online. returns[] is newest first and carries the store’s customer_message on an approved or declined one. {order} accepts the UUID id or the human order_no. Another customer’s order, another store’s order and an order that was not placed through this store answer 404.

Authorization

clientKey customerToken
X-Client-Key<token>

The connection's key (Dashboard → Channels → Headless API; keys are also listed in Settings → Connections). pk_… public keys are for browser code and only work from a website listed on the connection (a website connection never accepts *; a development connection on a dev store also allows localhost); sk_… private keys are for servers and native apps and need no Origin.

In: header

AuthorizationBearer <token>

The customer access credential from any sign-in session answer (access_token). Account operations only — send as Authorization: Bearer <access_token> ALONGSIDE X-Client-Key. It is bound to one store: a credential issued for another vendor answers 403 here.

In: header

Path Parameters

order*string

The order id (UUID) or its order number.

Header Parameters

X-Client-Key*string

Your connection's key (Dashboard → Channels → Headless API; keys are also listed in Settings → Connections). pk_… public keys are for browser code and only work from a website listed on the connection (a website connection never accepts *; a development connection on a dev store also allows localhost); sk_… private keys are for servers and native apps and need no Origin.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/store/orders/26-0925-74101/returns" \  -H "X-Client-Key: {{clientKey}}"
{  "status": "success",  "message": "Returns retrieved",  "data": {    "self_serve": true,    "request_pending": false,    "returnable": true,    "reason_code": null,    "notifies_by_email": true,    "reasons": [      "unwanted",      "not_as_described",      "wrong_item",      "defective",      "size_too_small"    ],    "window_days": 14,    "line_items": [      {        "order_item": "019b0c4d-5e6f-7a8b-9c0d-1e2f3a4b5c92",        "title": "Cotton Midi Dress",        "variant_title": "M",        "quantity": 1,        "returnable_quantity": 0,        "final_sale": false,        "window_ends_at": "2026-10-09T23:59:59+00:00",        "requestable": false,        "statutory_reasons_only": false,        "refusal": "none_left"      }    ],    "returns": [      {        "id": 1041,        "status": "open",        "line_items": [          {            "order_item": "019b0c4d-5e6f-7a8b-9c0d-1e2f3a4b5c92",            "title": "Cotton Midi Dress",            "variant_title": "M",            "quantity": 1,            "received_quantity": 0,            "reason": "defective"          }        ],        "source": "storefront",        "customer_note": "The zip broke on first use.",        "customer_message": "Thank you. Bring it to our New York shop and we will refund you when it arrives.",        "refunded_amount": "0.00",        "currency": "USD",        "requested_at": "2026-09-28T10:20:00+01:00",        "opened_at": "2026-09-28T11:05:00+01:00",        "declined_at": null,        "closed_at": null      }    ]  }}
POST
/store/orders/{order}/returns

Asks the store to take lines of the signed-in customer’s own order back; the store reviews it and approves or declines, and nothing is refunded or restocked by asking. Send line_items[] (order_item, quantity, reason, one of the reasons the read answers) and an optional customer_note. Answers 201 with the return (status requested). A line the rules do not allow, a store that takes no requests online, an order not yet delivered and a second request while one waits answer 422 (return_line_invalid, order_not_returnable) with errors naming each failing line (line_items.N) or the order (errors.order[0]: order_cancelled, order_not_delivered, self_serve_off). Send an Idempotency-Key to make a retry safe. {order} accepts the UUID id or the human order_no.

Authorization

clientKey customerToken
X-Client-Key<token>

The connection's key (Dashboard → Channels → Headless API; keys are also listed in Settings → Connections). pk_… public keys are for browser code and only work from a website listed on the connection (a website connection never accepts *; a development connection on a dev store also allows localhost); sk_… private keys are for servers and native apps and need no Origin.

In: header

AuthorizationBearer <token>

The customer access credential from any sign-in session answer (access_token). Account operations only — send as Authorization: Bearer <access_token> ALONGSIDE X-Client-Key. It is bound to one store: a credential issued for another vendor answers 403 here.

In: header

Path Parameters

order*string

The order id (UUID) or its order number.

Header Parameters

X-Client-Key*string

Your connection's key (Dashboard → Channels → Headless API; keys are also listed in Settings → Connections). pk_… public keys are for browser code and only work from a website listed on the connection (a website connection never accepts *; a development connection on a dev store also allows localhost); sk_… private keys are for servers and native apps and need no Origin.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Idempotency-Key?string

Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Ask the store to take lines of this order back. Which lines may be asked for, and why not, is the store's rules for this order (GET orders/{order}/returns shows them) and is refused with 422 return_line_invalid naming each failing line in errors (final_sale, window_ended, none_left, digital; errors.order = request_pending while an earlier request waits), or order_not_returnable when the order was not delivered or the store takes no requests online.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/store/orders/26-0925-74101/returns" \  -H "X-Client-Key: {{clientKey}}" \  -H "Content-Type: application/json" \  -d '{    "line_items": [      {        "order_item": "019b0c4d-5e6f-7a8b-9c0d-1e2f3a4b5c92",        "quantity": 1,        "reason": "defective"      }    ],    "customer_note": "The zip broke on first use."  }'
{  "status": "success",  "message": "Return requested",  "data": {    "id": 1041,    "status": "requested",    "line_items": [      {        "order_item": "019b0c4d-5e6f-7a8b-9c0d-1e2f3a4b5c92",        "title": "Cotton Midi Dress",        "variant_title": "M",        "quantity": 1,        "received_quantity": 0,        "reason": "defective"      }    ],    "source": "storefront",    "customer_note": "The zip broke on first use.",    "customer_message": null,    "refunded_amount": "0.00",    "currency": "USD",    "requested_at": "2026-09-28T10:20:00+01:00",    "opened_at": null,    "declined_at": null,    "closed_at": null  }}