API reference
Merchant API
Every Merchant API operation, with its scopes, parameters, responses and request samples.
Act on a store as a person: the merchant app and connected AI apps.
- Base URL
https://api.shopeazy.co- Version
0.9.0-draftBeta- Authentication
- stationToken: It may call only the operations whose x-stations lists its kind, on its own store, and acts through the access of the owner or admin who paired it.
- OAuth access token: OAuth 2.1 (authorization code + PKCE S256, public clients, dynamic registration) for connected AI apps.
- Operations
- 250
The Merchant API lets a person act on the stores they belong to. The merchant app and AI apps a merchant connects both use it.
Every path names the store, as in /v1/merchant/stores/{storeId}/orders. A store the person cannot reach answers 404 store_not_found, never 403.
A connected AI app signs in with OAuth and gets scopes. What it can do is the scopes it was granted, and the person's role today, and the plan, checked on every call. Each operation page lists the scopes it needs. Operations that only the first-party app may call are not in this reference.
Every write takes an Idempotency-Key. Use the typed client, @shopeazy/merchant-client, which has one method per operation, or call the API over plain HTTPS. Every operation shows a cURL sample and a client sample.
Read next
All operations
Session
Reference
Dashboard
Insights
Marketing
Products
- getThe store's kits, in display order
/v1/merchant/stores/{storeId}/kits - getList or search the catalogue
/v1/merchant/stores/{storeId}/products - postCreate an item in a kit
/v1/merchant/stores/{storeId}/products - getLook an item up by barcode
/v1/merchant/stores/{storeId}/products/by-barcode - postSet the shipping weight and box on several products
/v1/merchant/stores/{storeId}/products/shipping - getOne item, as the editor needs it
/v1/merchant/stores/{storeId}/products/{productId} - patchEdit an item (allow-listed fields only)
/v1/merchant/stores/{storeId}/products/{productId} - deleteDelete an item
/v1/merchant/stores/{storeId}/products/{productId} - postMove stock by a delta or set a counted total
/v1/merchant/stores/{storeId}/products/{productId}/stock - patchReorder settings and where a product sits
/v1/merchant/stores/{storeId}/products/{productId}/stock-settings - postPut a Library photo on a product
/v1/merchant/stores/{storeId}/products/{productId}/library-assets - getCustomisation groups (option groups offered with a product)
/v1/merchant/stores/{storeId}/customisation-groups - postCreate a customisation group
/v1/merchant/stores/{storeId}/customisation-groups - putPut the customisation groups in order
/v1/merchant/stores/{storeId}/customisation-groups/order - getOne customisation group and the listings that offer it
/v1/merchant/stores/{storeId}/customisation-groups/{groupId} - patchChange a customisation group
/v1/merchant/stores/{storeId}/customisation-groups/{groupId} - deleteArchive a customisation group
/v1/merchant/stores/{storeId}/customisation-groups/{groupId} - putOffer a group on exactly these listings
/v1/merchant/stores/{storeId}/customisation-groups/{groupId}/listings - putSet the customisation groups on one listing
/v1/merchant/stores/{storeId}/products/{productId}/customisations - getPast product imports, newest first
/v1/merchant/stores/{storeId}/product-imports - postStart a bulk product import from an uploaded CSV
/v1/merchant/stores/{storeId}/product-imports - postA signed link to upload the CSV straight to storage
/v1/merchant/stores/{storeId}/product-imports/upload-link - getOne import, with its status, progress and the rows it refused
/v1/merchant/stores/{storeId}/product-imports/{runId} - getSaved import column mappings
/v1/merchant/stores/{storeId}/product-import-profiles - postSave an import column mapping
/v1/merchant/stores/{storeId}/product-import-profiles - getThe listing categories shoppers browse by
/v1/merchant/stores/{storeId}/categories - postAdd categories by name (find-or-create)
/v1/merchant/stores/{storeId}/categories - putPut the categories in order
/v1/merchant/stores/{storeId}/categories/order - patchRename a category
/v1/merchant/stores/{storeId}/categories/{categoryId} - deleteRemove a category
/v1/merchant/stores/{storeId}/categories/{categoryId}
Settings
Orders
- getList or search orders
/v1/merchant/stores/{storeId}/orders - postRing up a manual (counter) order
/v1/merchant/stores/{storeId}/orders - postDo one thing to several orders at once
/v1/merchant/stores/{storeId}/orders/bulk - getOne order
/v1/merchant/stores/{storeId}/orders/{orderId} - putCorrect the delivery address
/v1/merchant/stores/{storeId}/orders/{orderId}/address - putCorrect the customer's phone on an order
/v1/merchant/stores/{storeId}/orders/{orderId}/phone - postCancel an order
/v1/merchant/stores/{storeId}/orders/{orderId}/cancel - postFulfil (or unfulfil) several lines at once
/v1/merchant/stores/{storeId}/orders/{orderId}/fulfil - postFulfil (or unfulfil) one line
/v1/merchant/stores/{storeId}/orders/{orderId}/lines/{lineId}/fulfil - postSend the tickets for a line again
/v1/merchant/stores/{storeId}/orders/{orderId}/tickets/resend - postRecord a payment taken outside the checkout
/v1/merchant/stores/{storeId}/orders/{orderId}/mark-paid - postAdd a merchant note
/v1/merchant/stores/{storeId}/orders/{orderId}/notes - postMark ready to collect and email the customer
/v1/merchant/stores/{storeId}/orders/{orderId}/ready-to-collect - getWhether the order can be refunded through its payment provider
/v1/merchant/stores/{storeId}/orders/{orderId}/refund - postRefund an order
/v1/merchant/stores/{storeId}/orders/{orderId}/refund - postEmail the customer a reminder to pay
/v1/merchant/stores/{storeId}/orders/{orderId}/remind - getThe link a customer pays an order at
/v1/merchant/stores/{storeId}/orders/{orderId}/payment-link - getWho is on a tour departure
/v1/merchant/stores/{storeId}/tours/{itemId}/manifest
Delivery
- postLive courier prices for this order
/v1/merchant/stores/{storeId}/orders/{orderId}/delivery/quote - postBook a courier collection
/v1/merchant/stores/{storeId}/orders/{orderId}/delivery/book - deleteCall off a booked collection
/v1/merchant/stores/{storeId}/orders/{orderId}/delivery/book - postRefresh tracking from the courier
/v1/merchant/stores/{storeId}/orders/{orderId}/delivery/tracking - postEmail the waybill to the merchant
/v1/merchant/stores/{storeId}/orders/{orderId}/delivery/waybill - getWhat is going in the box, and what it will be billed at
/v1/merchant/stores/{storeId}/orders/{orderId}/delivery/parcel-preview - getFind courier lockers and counters
/v1/merchant/stores/{storeId}/delivery/lockers - getDelivery settings and couriers
/v1/merchant/stores/{storeId}/delivery - putSave delivery settings
/v1/merchant/stores/{storeId}/delivery - put"Collect from you": on or off, and what to tell shoppers
/v1/merchant/stores/{storeId}/delivery/collection - getOne courier's own settings
/v1/merchant/stores/{storeId}/delivery/couriers/{providerId} - patchSave one courier's own settings
/v1/merchant/stores/{storeId}/delivery/couriers/{providerId} - getRoughly what dropping off saves against a driver collecting
/v1/merchant/stores/{storeId}/delivery/couriers/{providerId}/drop-off-saving - putSave "You deliver": the shop's own delivery zones
/v1/merchant/stores/{storeId}/delivery/self-delivery - postMove an order the shop delivers itself
/v1/merchant/stores/{storeId}/orders/{orderId}/delivery/own - getThe shipping queue
/v1/merchant/stores/{storeId}/shipping - getWhat to pull off the shelves for these orders
/v1/merchant/stores/{storeId}/shipping/pick-list
Stock
- getWhat a product is made from
/v1/merchant/stores/{storeId}/products/{productId}/recipe - putSet what a product is made from
/v1/merchant/stores/{storeId}/products/{productId}/recipe - getRaw materials, A to Z
/v1/merchant/stores/{storeId}/materials - postAdd a raw material
/v1/merchant/stores/{storeId}/materials - patchEdit a material
/v1/merchant/stores/{storeId}/materials/{materialId} - postSet or change a material's stock
/v1/merchant/stores/{storeId}/materials/{materialId}/stock - postRecord a stock count
/v1/merchant/stores/{storeId}/stock-counts - postRecord a batch made
/v1/merchant/stores/{storeId}/production-runs - getWhat sells, what sits, what runs out
/v1/merchant/stores/{storeId}/stock/insights
AI
- getCredits and which AI tools can run
/v1/merchant/stores/{storeId}/ai - postDraft a whole listing from a photo, barcode or prompt
/v1/merchant/stores/{storeId}/ai/product-draft - postWrite a name and description
/v1/merchant/stores/{storeId}/ai/product-copy - postImprove a photo or draw a new image
/v1/merchant/stores/{storeId}/ai/image
Customers
- getList or search customers
/v1/merchant/stores/{storeId}/customers - postAdd a customer
/v1/merchant/stores/{storeId}/customers - getOne customer
/v1/merchant/stores/{storeId}/customers/{customerId} - patchEdit a customer
/v1/merchant/stores/{storeId}/customers/{customerId} - deleteArchive a customer (soft delete)
/v1/merchant/stores/{storeId}/customers/{customerId} - postRestore an archived customer
/v1/merchant/stores/{storeId}/customers/{customerId}/restore - postArchive or restore several customers at once
/v1/merchant/stores/{storeId}/customers/bulk-status - getEvery tag in use on listings and customers, A to Z
/v1/merchant/stores/{storeId}/tags
Discounts
- getList discount codes
/v1/merchant/stores/{storeId}/discounts - postCreate a discount code
/v1/merchant/stores/{storeId}/discounts - getOne discount code
/v1/merchant/stores/{storeId}/discounts/{code} - patchEdit a discount code (including renaming it)
/v1/merchant/stores/{storeId}/discounts/{code} - deleteArchive a discount code
/v1/merchant/stores/{storeId}/discounts/{code}
Notifications
Events
- getTicketed events with at least one ticket issued
/v1/merchant/stores/{storeId}/events - getTickets issued and admitted for an event
/v1/merchant/stores/{storeId}/events/{itemId}/door-count - postAdmit a ticket at the door
/v1/merchant/stores/{storeId}/tickets/scan - getThe QR code for one ticket
/v1/merchant/stores/{storeId}/tickets/{code}/qr - getOne ticket as a printable PDF
/v1/merchant/stores/{storeId}/tickets/{code}/pdf
Uploads
- postUpload an image to the workspace's storage
/v1/merchant/stores/{storeId}/uploads - postUpload a file that is not an image
/v1/merchant/stores/{storeId}/uploads/files - postStore photos for listings, from links or bytes
/v1/merchant/stores/{storeId}/photos - postSigned links to upload photos straight to storage
/v1/merchant/stores/{storeId}/photos/upload-links
- getChannel health and how many chats are waiting
/v1/merchant/stores/{storeId}/whatsapp - postLook again for a catalogue on the WhatsApp account
/v1/merchant/stores/{storeId}/whatsapp/catalogue/refresh - putSwitch the WhatsApp AI auto-reply on or off
/v1/merchant/stores/{storeId}/whatsapp/ai - getRecent conversations
/v1/merchant/stores/{storeId}/whatsapp/threads - getOne conversation and its messages
/v1/merchant/stores/{storeId}/whatsapp/threads/{threadId} - postReply in a conversation
/v1/merchant/stores/{storeId}/whatsapp/threads/{threadId} - postMark a conversation read
/v1/merchant/stores/{storeId}/whatsapp/threads/{threadId}/read
Billing
- getPlan, subscription, card on file, credits and usage
/v1/merchant/stores/{storeId}/billing - patchChange plan, cancel or resume
/v1/merchant/stores/{storeId}/billing - getWhat a plan, add-on, extra, credit pack or the Launch package costs today
/v1/merchant/stores/{storeId}/billing/quote - putSwitch an add-on on or off
/v1/merchant/stores/{storeId}/billing/addons/{addonId} - putHow many extra seats or stores the business pays for
/v1/merchant/stores/{storeId}/billing/extras/{kind} - getThe credit balance and the last 30 credits in or out
/v1/merchant/stores/{storeId}/billing/credits - postBuy a credit pack on the saved card
/v1/merchant/stores/{storeId}/billing/credits - postBook the Launch package on the saved card
/v1/merchant/stores/{storeId}/billing/launch-package - getWhat the business paid ShopEazy, fee invoices and recent sales and refunds
/v1/merchant/stores/{storeId}/billing/money - getThe business's referral link, credit banked and who signed up through it
/v1/merchant/stores/{storeId}/referral
Store
- getWhat a store can say it sells (the store category choices)
/v1/merchant/stores/{storeId}/profile/categories - getStore details, channels and go-live blockers
/v1/merchant/stores/{storeId}/profile - patchEdit store details and switch channels on
/v1/merchant/stores/{storeId}/profile - putSet or clear the announcement bar in the design draft
/v1/merchant/stores/{storeId}/design/announcement - patchArrange the home page sections in the design draft
/v1/merchant/stores/{storeId}/design/home-sections - putSet or clear the pop-up in the design draft
/v1/merchant/stores/{storeId}/design/popup - patchChange the brand: logo, colours, tagline and voice
/v1/merchant/stores/{storeId}/brand - getThe shop's top menu as it is
/v1/merchant/stores/{storeId}/menu - putChange the shop's top menu
/v1/merchant/stores/{storeId}/menu - putWrite or hide the shop's policies
/v1/merchant/stores/{storeId}/policies - getIs this shop web address free?
/v1/merchant/stores/{storeId}/web-address/check - postDesign the home page with AI, into the draft
/v1/merchant/stores/{storeId}/design/ai - getThe shop's web address and where a connected domain is at
/v1/merchant/stores/{storeId}/web-address - putChange the shop's web address and/or connect its own domain
/v1/merchant/stores/{storeId}/web-address - patchThe shop's ad and analytics tags
/v1/merchant/stores/{storeId}/tracking - getWhich sales channels are on, and why an off one cannot be switched on yet
/v1/merchant/stores/{storeId}/channels - putSwitch the storefront or WhatsApp channel on or off
/v1/merchant/stores/{storeId}/channels/{channel} - getWhether the shop is listed in the public ShopEazy store directory
/v1/merchant/stores/{storeId}/directory-listing - putList or unlist the shop in the store directory
/v1/merchant/stores/{storeId}/directory-listing
Pages
- postWrite a new page with AI, as a draft
/v1/merchant/stores/{storeId}/pages/ai - getThe shop's own pages and what new pages can start from
/v1/merchant/stores/{storeId}/pages - postMake a page, or save a new draft of one
/v1/merchant/stores/{storeId}/pages - postA landing page built around one listing
/v1/merchant/stores/{storeId}/pages/listing - postPublish, unpublish or delete several pages
/v1/merchant/stores/{storeId}/pages/bulk - getThe blocks of one ready-made section, built from this shop
/v1/merchant/stores/{storeId}/pages/sections/{sectionId} - putSwitch a catalogue page to a designed page, or back
/v1/merchant/stores/{storeId}/pages/catalog/{kind} - putThe order pages appear in the menu and footer
/v1/merchant/stores/{storeId}/pages/order - getOne page: its draft, what is live, its settings and a preview link
/v1/merchant/stores/{storeId}/pages/{pageId} - patchA page's title, address, menu and footer placement and menu label
/v1/merchant/stores/{storeId}/pages/{pageId} - deleteDelete a page
/v1/merchant/stores/{storeId}/pages/{pageId} - postPut a page's draft on the shop for shoppers
/v1/merchant/stores/{storeId}/pages/{pageId}/publish - postTake a page off the shop
/v1/merchant/stores/{storeId}/pages/{pageId}/unpublish - deleteThrow away a page's draft and go back to what is live
/v1/merchant/stores/{storeId}/pages/{pageId}/draft
Reviews
- getShopper reviews, newest first
/v1/merchant/stores/{storeId}/reviews - getOne review
/v1/merchant/stores/{storeId}/reviews/{reviewId} - putReply to a review in the shop's name
/v1/merchant/stores/{storeId}/reviews/{reviewId}/reply - putShow or hide a review
/v1/merchant/stores/{storeId}/reviews/{reviewId}/status
Setup
Alerts
Members
- putMembers-only selling
/v1/merchant/stores/{storeId}/membership - getMembership requests, or members by status
/v1/merchant/stores/{storeId}/members - getOne application or member
/v1/merchant/stores/{storeId}/members/{memberId} - postLet a pending applicant in
/v1/merchant/stores/{storeId}/members/{memberId}/approve - postTurn down a pending applicant
/v1/merchant/stores/{storeId}/members/{memberId}/reject - postTake away a member's access
/v1/merchant/stores/{storeId}/members/{memberId}/revoke
Team
Purchasing
- getSuppliers, A to Z
/v1/merchant/stores/{storeId}/suppliers - postAdd a supplier
/v1/merchant/stores/{storeId}/suppliers - patchEdit a supplier
/v1/merchant/stores/{storeId}/suppliers/{supplierId} - deleteRetire a supplier
/v1/merchant/stores/{storeId}/suppliers/{supplierId} - getSupplier orders, newest first
/v1/merchant/stores/{storeId}/purchase-orders - postDraft an order to a supplier
/v1/merchant/stores/{storeId}/purchase-orders - putMark a supplier order sent or cancelled
/v1/merchant/stores/{storeId}/purchase-orders/{purchaseOrderId}/status - postBook a delivery in
/v1/merchant/stores/{storeId}/purchase-orders/{purchaseOrderId}/receive
Reports
- getSales, orders, visitors and the average order
/v1/merchant/stores/{storeId}/reports/summary - getBest-selling listings by revenue
/v1/merchant/stores/{storeId}/reports/top-sellers - getVisitors to the shop and what they searched for
/v1/merchant/stores/{storeId}/reports/traffic - getSales by product, month, channel or seller
/v1/merchant/stores/{storeId}/reports/sales
Campaigns
Studio
- getCredits the business has and what each make costs
/v1/merchant/stores/{storeId}/studio/costs - getThe Library, newest first
/v1/merchant/stores/{storeId}/library - deleteDelete a Library file
/v1/merchant/stores/{storeId}/library/{assetId} - putStar or un-star a Library file
/v1/merchant/stores/{storeId}/library/{assetId}/favourite - postSay the finished version of an AI clip has been made
/v1/merchant/stores/{storeId}/library/{assetId}/composed - postNote that Library files are shown on a product
/v1/merchant/stores/{storeId}/library/used - getHow many files the Library holds, and what they cost to make
/v1/merchant/stores/{storeId}/library/stats - postA caption about this picture, in the shop's voice
/v1/merchant/stores/{storeId}/library/{assetId}/caption - postAn AI edit of one Library photo, as a new version
/v1/merchant/stores/{storeId}/library/{assetId}/edit - postChange one thing about a shot you already have
/v1/merchant/stores/{storeId}/library/{assetId}/refine - getHow a make is going
/v1/merchant/stores/{storeId}/studio/jobs/{jobId} - getWhat is making now
/v1/merchant/stores/{storeId}/studio/makes - postStart a Studio make in the background
/v1/merchant/stores/{storeId}/studio/makes - postShoot a product: N takes of one brief
/v1/merchant/stores/{storeId}/studio/shoots
Bookings
- getUpcoming appointments and tour departures, soonest first
/v1/merchant/stores/{storeId}/bookings - postBook a service time or tour seats for a customer
/v1/merchant/stores/{storeId}/bookings - postCheck a booking and price it, without making it
/v1/merchant/stores/{storeId}/bookings/quote - getBooking requests waiting for the merchant (or all)
/v1/merchant/stores/{storeId}/booking-requests - getOne booking request
/v1/merchant/stores/{storeId}/booking-requests/{requestId} - postConfirm or decline a booking request
/v1/merchant/stores/{storeId}/booking-requests/{requestId}/decision - getFree times for a service, or departures for a tour
/v1/merchant/stores/{storeId}/products/{productId}/availability - getThe bookings (lines with a time) on an order
/v1/merchant/stores/{storeId}/orders/{orderId}/bookings - postMove a booking to another open time
/v1/merchant/stores/{storeId}/orders/{orderId}/lines/{lineId}/reschedule - putTick a traveller on a tour as there (or not)
/v1/merchant/stores/{storeId}/orders/{orderId}/lines/{lineId}/travellers/{index}/attendance
Storefront
- getThe design as it stands in the draft
/v1/merchant/stores/{storeId}/storefront - getThe templates a design can start from
/v1/merchant/stores/{storeId}/storefront/templates - postStart the design from a template
/v1/merchant/stores/{storeId}/storefront/template - getA private link to the draft design
/v1/merchant/stores/{storeId}/storefront/preview - postMake the draft design live
/v1/merchant/stores/{storeId}/storefront/publish - deleteThrow away the design draft and go back to what is live
/v1/merchant/stores/{storeId}/storefront/draft - putChange the look and colours in the design draft
/v1/merchant/stores/{storeId}/storefront/look - putChange the home hero in the design draft
/v1/merchant/stores/{storeId}/storefront/hero
Stations
PointOfSale
- getThe till shift that is open now
/v1/merchant/stores/{storeId}/registers/current - postOpen the register with a cash float
/v1/merchant/stores/{storeId}/registers - postClose the register by counting the drawer
/v1/merchant/stores/{storeId}/registers/{registerId}/close - postVoid a sale rung up at the till by mistake
/v1/merchant/stores/{storeId}/orders/{orderId}/void - postStart a Scan to pay sale
/v1/merchant/stores/{storeId}/till/scan-to-pay - getHas the customer paid yet
/v1/merchant/stores/{storeId}/till/scan-to-pay/{orderId} - getThe data of a counter receipt, to print or show
/v1/merchant/stores/{storeId}/orders/{orderId}/counter-receipt - postEmail the customer a counter receipt
/v1/merchant/stores/{storeId}/orders/{orderId}/counter-receipt/email
Revoke an active member's access POST
`note` becomes the member's `decisionNote`, which the shopper sees. Old path, deprecated, sunset 1 Feb 2027: `POST /v1/members/{uid}/revoke`.
Who is signed in, and every store they can act on GET
A person with no ShopEazy profile yet gets `stores: []` and `defaultStoreId: null` (they go to onboarding). Access: OAuth scope `store:read`; not write-gated.
Social
/v1/merchant/stores/{storeId}/social/posts/v1/merchant/stores/{storeId}/social/posts/v1/merchant/stores/{storeId}/social/posts/{postId}/v1/merchant/stores/{storeId}/social/posts/{postId}/v1/merchant/stores/{storeId}/social/posts/{postId}/v1/merchant/stores/{storeId}/social/posts/{postId}/schedule/v1/merchant/stores/{storeId}/social/facebook/v1/merchant/stores/{storeId}/social/facebook/post/v1/merchant/stores/{storeId}/social/automation/v1/merchant/stores/{storeId}/social/automation/v1/merchant/stores/{storeId}/social/plan-week/v1/merchant/stores/{storeId}/library/{assetId}/promote/v1/merchant/stores/{storeId}/social/posts/{postId}/publish