StoreOS GraphQL mutations
The StoreOS GraphQL mutations that change checkout, coupons, and the customer account, and when to call each one.
Mutations change data on StoreOS — place orders, update profiles, log in. Most need x-tenant; some also need a customer JWT.
Checkout
createOrder
What it does: Places an order — converts cart line items into an invoice on StoreOS. This is the main checkout action.
Who can call: Guests (no JWT) or logged-in customers (with JWT).
What you send: Line items, shipping address, payment method (COD or ONLINE), delivery area, optional coupon.
What you get back: Order with invoiceUID, optional authToken for guest tracking.
mutation CreateOrder($input: CreateOrderInput!) {
createOrder(input: $input) {
order { invoiceUID invoiceStatus netTotalAmount }
authToken
customer { _id name email phoneNumber }
}
}REST equivalent: POST /api/v1/orders · SDK: createOrder()
verifyCoupon
What it does: Checks if a discount code is valid for the current cart and returns the discount amount.
Why line items are required: StoreOS validates the coupon against specific products and quantities.
mutation VerifyCoupon($input: VerifyCouponInput!) {
verifyCoupon(input: $input) {
valid discountAmount message
}
}Input needs code + lineItems[] with productId, variantId, quantity. Add deliveryArea so free-shipping codes are included in discountAmount.
REST equivalent: POST /api/v1/orders/coupons/verify · SDK: verifyCoupon()
previewDiscounts (query)
What it does: Returns the full discount breakdown for a cart: every automatic discount the merchant runs (amount off, buy X get Y, free shipping) plus an optional code. createOrder applies the same discounts, so totals match.
What you send: lineItems[], optional code, optional deliveryArea (needed for free shipping), optional deliverySubArea (an area within that region, from charges.deliveryRegions[].subAreas). A customer JWT is optional and enables customer-specific discounts.
query PreviewDiscounts($input: PreviewDiscountsInput!) {
previewDiscounts(input: $input) {
applications { discountId title type method code amount }
shippingDiscount discountTotal totalAfterDiscount
hints { kind message }
code codeError
}
}hints are nudges such as "Add 1 more item to get 1 free" or "Spend ৳500 more for free shipping". codeError explains why an entered code was not applied.
REST equivalent: POST /api/v1/orders/discounts/preview · SDK: previewDiscounts()
activeOffers (query)
What it does: Lists the store's active automatic offers (never codes) with a short badgeLabel like "Buy 1 Get 1" — for product badges and the free-shipping progress bar.
query ActiveOffers {
activeOffers {
id title type badgeLabel
appliesTo { scope productIds collectionIds }
minimumRequirement { type value }
freeShipping { deliveryRegions }
}
}REST equivalent: GET /api/v1/discounts/offers · SDK: activeOffers()
Account
updateProfile · changePassword
| Mutation | What it does | Auth |
|---|---|---|
updateProfile | Change name, phone, shipping address | Required |
changePassword | Change password (returns Boolean) | Required |
mutation UpdateProfile($input: UpdateProfileInput!) {
updateProfile(input: $input) { _id name email phoneNumber }
}REST equivalent: PATCH /api/v1/auth/profile, POST /api/v1/auth/change-password
cancelOrder
What it does: Cancels an order the logged-in customer placed.
Input: orderId (invoice UID) + optional reason.
mutation CancelOrder($input: CancelOrderInput!) {
cancelOrder(input: $input) {
invoiceUID invoiceStatus
}
}REST equivalent: POST /api/v1/orders/:orderId/cancel · SDK: cancelOrder()
Order lifecycle reference
Invoice status (invoiceStatus)
| Status | Meaning |
|---|---|
PENDING | Placed, awaiting processing |
PROCESSING | Being prepared |
SHIPMENT_IN_PROGRESS | Handed to courier |
SHIPMENT_IN_TRANSIT | In transit |
SHIPMENT_DELIVERED | Delivered |
REJECTED | Rejected / cancelled |
Payment status (paymentStatus)
UNATTEMPTED · PROCESSING · PAID · CANCELLED · FAILED · EXPIRED
Delivery areas
Bangladesh divisions: DHAKA, CHATTOGRAM, SYLHET, RAJSHAHI, KHULNA, BARISHAL, RANGPUR, MYMENSINGH, OUTSIDE_CAPITAL.
Fees come from storeFront.charges — fetch with storeFront query or getTenant().