Orders and checkout

Create, inspect, or cancel orders and retrieve purchase history or checkout charges. Guest checkout supplies customer details in its request body.

Access labels such as Origin + Brand key + Customer are defined in Headers and access. Each endpoint ends in a Try it console; set the host and keys once in its Settings tab or on the overview.

Get Shopify orders by user ID

Fetch the authenticated customer’s Shopify orders, newest first, with cursor pagination.

Method	URL path	Required access
GET	/api/v1/user/shopify/orders	Origin + Brand key + Customer

Request fields:

Field	Type	Required	Rules / meaning
query.limit	number	optional	Integer; Minimum (1); Maximum (250); Default (10)
query.cursor	string	optional	Also accepts ("" , null); Default (null)

limit defaults to 10 and must be an integer from 1 through 250. cursor is an opaque string from the previous page; omit it for the first page. The result also includes limit.

Example:

curl -X GET "$BASE_URL/api/v1/user/shopify/orders?limit=10" \
  -H "Origin: $ORIGIN" \
  -H "api-key: $API_KEY" \
  -H "Authorization: Bearer $CUSTOMER_TOKEN"

Response: JSON with success: true and result containing the operation’s service data.

Source: app/v1/controller/customer_controller.js:1605 → getShopifyOrdersByUserID; routes: routes/v1/customer_route.js:145; service: _getShopifyOrdersByUserID (app/v1/service/customer_service.js:3991).

Cancel order

Method	URL path	Required access
PUT	/api/v1/user/order/cancel/:orderId	Origin + Brand key + Customer

Request fields:

Field	Type	Required	Rules / meaning
path.orderId	number	yes	—

Example:

curl -X PUT "$BASE_URL/api/v1/user/order/cancel/1" \
  -H "Origin: $ORIGIN" \
  -H "api-key: $API_KEY" \
  -H "Authorization: Bearer $CUSTOMER_TOKEN"

Response: JSON with success: true and result containing the operation’s service data.

Source: app/v1/controller/order_controller.js:408 → cancelOrder; routes: routes/v1/order_route.js:142; service: _cancelOrder (app/v1/service/order_service.js:1745).

Create new order

Method	URL path	Required access
POST	/api/v1/user/createOrder	Origin + Brand key + Hub selected + Customer

Request fields:

Field	Type	Required	Rules / meaning
body.payload	object	yes	—
body.payload.addressId	number	optional	—
body.payload.billingAddressId	number	optional	—
body.payload.governmentId	number	optional	—
body.payload.deliverySchedule	string	optional	Whitespace trimmed
body.payload.deliveryInstruction	string	optional	Whitespace trimmed
body.payload.posId	string	optional	Whitespace trimmed; Allowed values ("weedmaps", "phone", "email", "website", "kiosk")
body.payload.discounts	array of string	optional	—
body.payload.deliveryCharges	number	optional	—
body.payload.isPrepaidOrder	boolean	optional	—
body.payload.points	number	optional	Minimum (0)
body.payload.method	string	optional	Whitespace trimmed; Allowed values ("curbside", "doorstep", "pos", "instore", "shipment")

Example:

curl -X POST "$BASE_URL/api/v1/user/createOrder" \
  -H "Origin: $ORIGIN" \
  -H "api-key: $API_KEY" \
  -H "Authorization: Bearer $CUSTOMER_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-raw '{"payload":{}}'

Response: JSON with success: true and result containing the operation’s service data.

Source: app/v1/controller/order_controller.js:24 → createNewOrder; routes: routes/v1/order_route.js:112; service: _newCreateOrder (app/v1/service/order_service.js:49).

Create guest order

Method	URL path	Required access
POST	/api/v1/user/create-order	Origin + Brand key + Hub selected

Request fields:

Field	Type	Required	Rules / meaning
body.payload	object	yes	—
body.payload.customer	object	yes	At least one of ("email" , "phoneNumber" , "userId"); Exactly one of ("userId" , "name")
body.payload.customer.userId	number	optional	—
body.payload.customer.name	string	optional	Whitespace trimmed
body.payload.customer.password	string	optional	Whitespace trimmed; Minimum (8)
body.payload.customer.dateOfBirth	date	optional	ISO date
body.payload.customer.email	string	optional	Email address; Whitespace trimmed; Converted to lowercase
body.payload.customer.phoneNumber	string	optional	replace(/\D/g , ""); Whitespace trimmed; Minimum (8)
body.payload.customer.phone_prefix	string	conditional	Required when phoneNumber is supplied; otherwise optional
body.payload.customer.address	object	optional	At least one of ("addressId" , "address1")
body.payload.customer.address.addressId	number	optional	—
body.payload.customer.address.name	string	optional	Whitespace trimmed
body.payload.customer.address.type	string	optional	Whitespace trimmed; Allowed values ("shipping"); Default ("shipping")
body.payload.customer.address.address1	string	optional	Whitespace trimmed
body.payload.customer.address.county	string	optional	Whitespace trimmed
body.payload.customer.address.city	string	optional	Whitespace trimmed
body.payload.customer.address.state	string	optional	Whitespace trimmed
body.payload.customer.address.short_state	string	optional	Whitespace trimmed
body.payload.customer.address.zip	string	optional	Whitespace trimmed
body.payload.customer.address.country	string	optional	Whitespace trimmed; Country code from country_iso_codes, for example US or CA
body.payload.customer.address.latLng	object	optional	—
body.payload.customer.address.latLng.lat	number	yes	—
body.payload.customer.address.latLng.lng	number	yes	—
body.payload.customer.address.addressString	string	optional	Whitespace trimmed
body.payload.customer.billingAddress	object	optional	At least one of ("addressId" , "address1")
body.payload.customer.billingAddress.addressId	number	optional	—
body.payload.customer.billingAddress.name	string	optional	Whitespace trimmed
body.payload.customer.billingAddress.type	string	optional	Whitespace trimmed; Allowed values ("billing"); Default ("billing")
body.payload.customer.billingAddress.address1	string	optional	Whitespace trimmed
body.payload.customer.billingAddress.county	string	optional	Whitespace trimmed
body.payload.customer.billingAddress.city	string	optional	Whitespace trimmed
body.payload.customer.billingAddress.state	string	optional	Whitespace trimmed
body.payload.customer.billingAddress.short_state	string	optional	Whitespace trimmed
body.payload.customer.billingAddress.zip	string	optional	Whitespace trimmed
body.payload.customer.billingAddress.country	string	optional	Whitespace trimmed; Country code from country_iso_codes, for example US or CA
body.payload.customer.billingAddress.latLng	object	optional	—
body.payload.customer.billingAddress.latLng.lat	number	yes	—
body.payload.customer.billingAddress.latLng.lng	number	yes	—
body.payload.customer.billingAddress.addressString	string	optional	Whitespace trimmed
body.payload.customer.user_documents	array of object	optional	—
body.payload.customer.user_documents[].governmentId	string	yes	—
body.payload.customer.user_documents[].expiration	date	yes	—
body.payload.customer.user_documents[].fileName	string	yes	Whitespace trimmed
body.payload.customer.user_documents[].type	string	yes	Whitespace trimmed
body.payload.customer.user_documents[].isValid	boolean	yes	—
body.payload.bag	array of object	yes	—
body.payload.bag[].index	number	optional	—
body.payload.bag[].hubProductId	number	yes	Integer
body.payload.bag[].isPromotional	boolean	optional	—
body.payload.bag[].quantity	number	yes	—
body.payload.bag[].packageId	string	optional	Whitespace trimmed
body.payload.deliverySchedule	string	optional	Whitespace trimmed
body.payload.deliveryInstruction	string	optional	Whitespace trimmed
body.payload.posId	string	optional	Whitespace trimmed; Allowed values ("weedmaps", "phone", "email", "website", "kiosk")
body.payload.discounts	array of string	optional	—
body.payload.transporterId	string	optional	Whitespace trimmed
body.payload.method	string	optional	Whitespace trimmed; Allowed values ("curbside", "doorstep", "pos", "instore", "shipment")
query.source	string	optional	Whitespace trimmed; Allowed values ("organic", "scan", "referral", "promotion", "shopify_plugin", "other")
query.medium	string	optional	Whitespace trimmed; Allowed values ("ios", "android", "website", "plugin", "other")
query.device	string	optional	Whitespace trimmed; Allowed values ("mobile", "desktop", "ipad", "tablet", "other", "laptop")

Example:

curl -X POST "$BASE_URL/api/v1/user/create-order" \
  -H "Origin: $ORIGIN" \
  -H "api-key: $API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{"payload":{"customer":{"email":"alex@example.com","userId":1},"bag":[{"hubProductId":1,"quantity":1}]}}'

Response: JSON with success: true and result containing the operation’s service data.

Source: app/v1/controller/order_controller.js:100 → createGuestOrder; routes: routes/v1/order_route.js:102; service: _guestCreateOrder (app/v1/service/order_service.js:155).

Get order by order ID

Method	URL path	Required access
GET	/api/v1/user/order/:orderId	Origin + Customer

No brand key on this route

/api/v1/user/order/:orderId is listed although its route does not check api-key: the shop to order flow calls it. Sending the key anyway is harmless.

Request fields:

Field	Type	Required	Rules / meaning
path.orderId	number	yes	—

Example:

curl -X GET "$BASE_URL/api/v1/user/order/1" \
  -H "Origin: $ORIGIN" \
  -H "Authorization: Bearer $CUSTOMER_TOKEN"

Response: JSON with success: true and result containing the operation’s service data.

Source: app/v1/controller/order_controller.js:316 → getOrderByOrderId; routes: routes/v1/order_route.js:122; service: _getOrderByOrderId (app/v1/service/order_service.js:1175).

Get all orders for customer

Method	URL path	Required access
GET	/api/v1/user/orders	Origin + Customer

No brand key on this route

/api/v1/user/orders is listed although its route does not check api-key: the shop to order flow calls it. Sending the key anyway is harmless.

Request fields:

Field	Type	Required	Rules / meaning
query.withLineItems	boolean	optional	Default (false)

Example:

curl -X GET "$BASE_URL/api/v1/user/orders" \
  -H "Origin: $ORIGIN" \
  -H "Authorization: Bearer $CUSTOMER_TOKEN"

Response: JSON with success: true and result containing the operation’s service data. Result fields/details: Order history for the current customer; withLineItems requests line items.

Source: app/v1/controller/order_controller.js:345 → getAllOrdersForCustomer; routes: routes/v1/order_route.js:132; service: _getAllOrdersForUser (app/v1/service/order_service.js:1428).

Get user ordered products

List products previously ordered by the current customer, optionally filtered by date and tags.

Method	URL path	Required access
POST	/api/v1/user/ordered-products	Origin + Brand key + Customer

Request fields:

Field	Type	Required	Rules / meaning
body.payload	object	optional	—
body.payload.startDate	string	optional	isoDate()
body.payload.endDate	string	optional	isoDate()
body.payload.tags	array of string	optional	—
body.payload.limit	number	optional	Integer; Minimum (1); Maximum (100)
body.payload.offset	number	optional	Integer; Minimum (0)

Example:

curl -X POST "$BASE_URL/api/v1/user/ordered-products" \
  -H "Origin: $ORIGIN" \
  -H "api-key: $API_KEY" \
  -H "Authorization: Bearer $CUSTOMER_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-raw '{"payload":{"limit":10}}'

Response: JSON with success: true and result containing the operation’s service data. Result fields/details: count, limit, offset, products; each product includes lastOrderedAt, totalQuantity, orderCount.

Source: app/v1/controller/order_controller.js:368 → getUserOrderedProducts; routes: routes/v1/order_route.js:59; service: _getUserOrderedProducts (app/v1/service/order_service.js:1588).

Get taxes and other charges breakup

Method	URL path	Required access
POST	/api/v1/taxes-breakup	Origin + Brand key + Hub selected

Request fields:

Field	Type	Required	Rules / meaning
body.payload	object	yes	—
body.payload.priceBeforeTaxes	number	yes	—
body.payload.countryCode	string	yes	Whitespace trimmed

Example:

curl -X POST "$BASE_URL/api/v1/taxes-breakup" \
  -H "Origin: $ORIGIN" \
  -H "api-key: $API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{"payload":{"priceBeforeTaxes":1,"countryCode":"US"}}'

Response: JSON with success: true and result containing the operation’s service data.

Source: app/v1/controller/order_controller.js:434 → getTaxesAndOtherChargesBreakup; routes: routes/v1/order_route.js:81; service: _getTaxesAndOtherChargesBreakup (app/v1/service/order_service.js:1811).

Cancel order integration

Method	URL path	Required access
PUT	/api/v1/order/integrations/cancel	Origin + Brand key + Hub selected

Request fields:

Field	Type	Required	Rules / meaning
body.payload	object	yes	At least one of ("email" , "phoneNumber")
body.payload.email	string	optional	Email address; Whitespace trimmed; Converted to lowercase
body.payload.phoneNumber	string	optional	replace(/\D/g , ""); Whitespace trimmed
body.payload.phone_prefix	string	conditional	Required when phoneNumber is supplied; otherwise optional
body.payload.orderId	number	yes	—

Example:

curl -X PUT "$BASE_URL/api/v1/order/integrations/cancel" \
  -H "Origin: $ORIGIN" \
  -H "api-key: $API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{"payload":{"orderId":1,"email":"alex@example.com"}}'

Response: JSON with success: true and result containing the operation’s service data.

Source: app/v1/controller/order_controller.js:464 → cancelOrderIntegration; routes: routes/v1/order_route.js:91; service: _cancelOrderIntegration (app/v1/service/order_service.js:1900).

Lifecycle

An order's currentStep is one of PAYMENT_PENDING, PLACED, ACCEPTED, READY_FOR_DELIVERY, DISPATCHED, TRANSIT, DELIVERED, COMPLETED or CANCELLED. This API sets the first two and CANCELLED; the fulfilment steps are moved on the hub side.

• Prepaid means the request sent isPrepaidOrder, or the hub ships and has payment gateways configured. Both create-order paths share this rule.
• Payment succeeds is any gateway's pay call, or the provider's redirect back to the backend after a hosted payment — each sets PLACED. See Payments and gateways.
• Cancelling follows the order type. A pickup order can be cancelled from any step until it is COMPLETED or CANCELLED. Every other type can be cancelled only from PLACED, ACCEPTED or PAYMENT_PENDING, and is refused with already in progress or completed after that.
• The first fulfilment step the customer backend defines is ACCEPTED for delivery and shipment orders and DISPATCHED for pickup. Its cancellation handlers cover those three types only.
• Notifications follow the starting step: order placed or order payment pending, and the order is pushed to the hub's integration only when it starts at PLACED.

The checkout journey that creates and pays an order is the shop-to-order web flow.

Related pages

• Batch Commerce API overview
• Implementation notes