Online store API
The public REST API exposes the same online store operations as the store builder and the repzo store CLI. Use it to build stores from your own tools, sync content, or let an AI client edit a theme.
Authentication, API keys, rate limits, and error basics are the same as the rest of the API. See Developer API and CLI.
The interactive reference lives at /api/v1/docs on your Workstation, and the raw OpenAPI spec at /api/v1/openapi.json. The endpoints below appear there under the Online Stores, Store Themes, Store Builder, Store Theme Code, Store Publishing, Store Domains, Store Menus, Store Content, Store Discounts, Store Reviews, Store Payments, Store Shipping, Store Markets, Store Settings, Store Marketing, Store Doctor, Orders, and Order returns tags.
Access
Section titled “Access”All online store endpoints live under /api/v1/commerce.
| Scope | Allows | Delegated user also needs |
|---|---|---|
commerce:read |
Every GET, plus POST …/draft/validate |
commerce.view or commerce.manage |
commerce:write |
Every other change | commerce.manage |
In Settings → Integrations & Developers → Developer Apps, this scope is called Online Stores. The workspace also needs the Commerce module; without it, requests are refused.
Returns and order edits use the Orders scope (orders:read / orders:write) instead. See Returns and order edits.
Conventions
Section titled “Conventions”- Themes. A site has several themes, and each has its own draft. Without
themeId, an endpoint uses the site’s live theme. SendthemeIdin the query string on reads and deletes, and in the body on other writes. - Drafts. Every change edits a draft. Nothing reaches shoppers until you publish.
- Revisions. Each save raises the draft’s
revision. Single edits accept an optionalrevision; replacing the whole draft and publishing require it. A stale revision returns409 conflict: read the draft again and retry. - Text in two languages. Translatable settings take one value per site language:
{"en": "New arrivals", "ar": "وصل حديثاً"}. - Lists take
pageandlimit(default 20, max 200) and return{ data, meta }. - Errors use the standard shape:
{ "error": { "code", "message", "details" } }.
Sites and templates
Section titled “Sites and templates”| Method | Path | What it does |
|---|---|---|
GET |
/commerce/sites |
List sites, oldest first |
POST |
/commerce/sites |
Create a site, optionally from a starter template (409 if the address is taken) |
GET |
/commerce/sites/{siteId} |
Get a site |
PATCH |
/commerce/sites/{siteId} |
Change name, address, status (draft, live, password), languages, currency, browser title, store password, and “Sell stock from” locations |
GET |
/commerce/site-templates |
List the starter templates (not paged) |
A new site’s free address is <slug>.myrepzo.com; omit slug to derive one from the name. commerceEnabled: false makes a landing-page site with no product pages, cart, or checkout.
Themes
Section titled “Themes”| Method | Path | What it does |
|---|---|---|
GET |
/commerce/sites/{siteId}/themes |
List the theme library, live theme first, plus the site’s pending schedule |
POST |
/commerce/sites/{siteId}/themes |
Add a theme from a theme style or a starter template (never live until published; up to 20 per site) |
POST |
/commerce/sites/{siteId}/themes/import |
Import a theme file as a new, unpublished theme |
GET |
/commerce/sites/{siteId}/themes/{themeId}/export |
Export a theme file (settings, header, footer, pages) |
POST |
/commerce/sites/{siteId}/themes/{themeId}/duplicate |
Copy a theme |
PATCH |
/commerce/sites/{siteId}/themes/{themeId} |
Rename a theme |
DELETE |
/commerce/sites/{siteId}/themes/{themeId} |
Delete a theme that isn’t live |
POST |
/commerce/sites/{siteId}/themes/{themeId}/publish |
Publish this theme’s draft and make it live (needs revision) |
POST |
/commerce/sites/{siteId}/themes/{themeId}/schedule |
Publish at publishAt, 1 minute to 1 year ahead (one schedule per site) |
DELETE |
/commerce/sites/{siteId}/themes/schedule |
Cancel the site’s scheduled publish |
GET |
/commerce/sites/{siteId}/theme |
Read theme settings, color schemes, custom CSS, and the accepted settings per group |
PATCH |
/commerce/sites/{siteId}/theme |
Change the theme style, settings, color schemes, and custom CSS in one draft edit |
Draft and pages
Section titled “Draft and pages”| Method | Path | What it does |
|---|---|---|
GET |
/commerce/sites/{siteId}/draft |
Get the whole draft document and its revision |
PUT |
/commerce/sites/{siteId}/draft |
Replace the whole draft on top of revision. The response lists what the cleaner dropped or changed (changes) and code problems. |
POST |
/commerce/sites/{siteId}/draft/validate |
Check a draft without saving it (read scope) |
GET |
/commerce/sites/{siteId}/pages |
List pages |
GET |
/commerce/sites/{siteId}/pages/{pageId} |
Get a page with every section, setting, and block, plus an outline of the header and footer |
PATCH |
/commerce/sites/{siteId}/pages/{pageId} |
Change a page’s title, address (handle), or SEO |
Sections and blocks
Section titled “Sections and blocks”| Method | Path | What it does |
|---|---|---|
GET |
/commerce/sites/{siteId}/section-types |
List section types by category, or describe some in full with types=hero,faq (types=@theme lists universal blocks) |
POST |
/commerce/sites/{siteId}/sections |
Add a section to a page, or to the shared header or footer (group) |
GET |
/commerce/sites/{siteId}/sections/{nodeId} |
Get a section or block with the settings it and its child blocks accept |
PATCH |
/commerce/sites/{siteId}/sections/{nodeId} |
Change settings (merged), child blocks (kept by id), hidden, label, section CSS, or layout |
DELETE |
/commerce/sites/{siteId}/sections/{nodeId} |
Remove a section or block |
POST |
/commerce/sites/{siteId}/sections/{nodeId}/blocks |
Add a block inside a section or group |
POST |
/commerce/sites/{siteId}/sections/{nodeId}/move |
Move a section within its group, or a block within its parent or into another one with parentId |
section-types also filters by pageId, group (header, template, footer), and category.
Theme code
Section titled “Theme code”| Method | Path | What it does |
|---|---|---|
GET |
/commerce/sites/{siteId}/code/files |
List the draft’s code files with problem counts and the pages that use them |
GET |
/commerce/sites/{siteId}/code/files/{dir}/{name} |
Get one file’s source and problems |
PUT |
/commerce/sites/{siteId}/code/files/{dir}/{name} |
Create or replace a file ({ source, revision? }) |
DELETE |
/commerce/sites/{siteId}/code/files/{dir}/{name} |
Delete a file |
GET |
/commerce/sites/{siteId}/code/guide |
The theme code guide (AGENTS.md) as Markdown |
{dir}/{name} is a path such as sections/hero-banner.liquid. A file is saved even when it has Liquid or schema problems, because it is only a draft; the problems come back in problems. A bad path, a file over 48 KB, or a theme over 60 files or 512 KB is refused with 422. Deleting a file keeps the sections made from it on their pages; they draw nothing until the file comes back. See Theme code.
Publishing, previews, and versions
Section titled “Publishing, previews, and versions”| Method | Path | What it does |
|---|---|---|
POST |
/commerce/sites/{siteId}/publish |
Publish the draft at exactly revision as the next version (optional themeId, note) |
POST |
/commerce/sites/{siteId}/preview-link |
A 7-day share link to the draft that opens without signing in |
GET |
/commerce/sites/{siteId}/versions |
Published versions, newest first; isLive marks the live one |
POST |
/commerce/sites/{siteId}/versions/{versionId}/restore |
Copy a version into the draft (returns the new revision); publish to make it live |
Publishing is refused with 422 while the theme’s code files have errors. The error’s details.code is THEME_CODE_ERRORS and details.problems lists them.
Store from a link
Section titled “Store from a link”| Method | Path | What it does |
|---|---|---|
POST |
/commerce/sites/{siteId}/import |
Start building the store from a url (202). Adds up to 100 products as inactive drafts, their photos, and page copy. |
GET |
/commerce/sites/{siteId}/import |
The latest run in the last 7 days: status, steps, counts, and warnings (run is null when there’s none) |
The import uses AI credit. An empty AI balance returns 402 payment_required, and a run already going for the site returns 409. It isn’t available in sandboxes.
Domains and menus
Section titled “Domains and menus”| Method | Path | What it does |
|---|---|---|
GET |
/commerce/sites/{siteId}/domains |
List domains, the store domain, and the DNS target for custom domains |
POST |
/commerce/sites/{siteId}/domains |
Connect a custom domain (hostname); returns the DNS records to add. Not in sandboxes. |
DELETE |
/commerce/sites/{siteId}/domains/{domainId} |
Remove a domain (not the current free address) |
GET |
/commerce/sites/{siteId}/menus |
List menus |
POST |
/commerce/sites/{siteId}/menus |
Create a menu |
GET |
/commerce/sites/{siteId}/menus/{menuId} |
Get a menu with its item tree |
PATCH |
/commerce/sites/{siteId}/menus/{menuId} |
Rename a menu or replace its whole item tree (items) |
DELETE |
/commerce/sites/{siteId}/menus/{menuId} |
Delete a menu (not the main or footer menu) |
Menus aren’t part of a theme, so menu changes are live at once. Menu items nest up to 3 levels.
Collections, content, discounts, and reviews
Section titled “Collections, content, discounts, and reviews”These are shared by every site in the workspace.
| Method | Path | What it does |
|---|---|---|
GET, POST |
/commerce/collections |
List or create product collections (manual or smart) |
GET, PATCH, DELETE |
/commerce/collections/{id} |
Get, update, or delete a collection |
GET, POST |
/commerce/content-types |
List or create content types |
GET, PATCH, DELETE |
/commerce/content-types/{typeId} |
Get, update (the key never changes), or delete a content type |
GET, POST |
/commerce/content-types/{typeId}/entries |
List or create entries |
GET, PATCH, DELETE |
/commerce/content-types/{typeId}/entries/{entryId} |
Get, update, or delete an entry |
GET, POST |
/commerce/discounts |
List or create discounts (a code or automatic; 409 if the code is taken) |
GET, PATCH, DELETE |
/commerce/discounts/{id} |
Get, update, or delete a discount |
POST |
/commerce/discounts/{id}/deactivate |
End a discount now |
GET |
/commerce/reviews |
List product reviews (filter by status, rating) |
PATCH |
/commerce/reviews/{id} |
Set status (pending, published, rejected) or a public reply |
DELETE |
/commerce/reviews/{id} |
Delete a review |
See Products and collections, Navigation and content, and Discounts.
Store setup
Section titled “Store setup”These endpoints get a store ready to sell and keep it running. They use the same commerce:read / commerce:write scopes as the rest of this page. Two reads that look like writes only need commerce:read: POST /commerce/shipping/quote and POST /commerce/sites/{siteId}/doctor/run.
A few things stay in the app only: connecting Aramex, and a standalone Refund order.
Payments
Section titled “Payments”| Method | Path | What it does |
|---|---|---|
GET |
/commerce/payment-methods |
List the payment methods (cash_on_delivery, bank_transfer) and whether each is set up and on |
PATCH |
/commerce/payment-methods/{driver} |
Turn a method on or off, rename it for shoppers, or change its config |
For cash on delivery and bank transfer, config replaces the method’s whole settings and is checked like the settings screen. For example, a bank transfer needs an IBAN or account number, and cash on delivery takes maxOrderAmount and cities. See Checkout & Payments.
Shipping
Section titled “Shipping”| Method | Path | What it does |
|---|---|---|
GET |
/commerce/shipping |
Zones with their rates, pickup points, and the locations a pickup can use. Amounts are in the workspace’s base currency. |
POST |
/commerce/shipping/zones |
Create a zone: countries, optionally narrowed to cities when the zone has exactly one country |
PATCH, DELETE |
/commerce/shipping/zones/{id} |
Update or delete a zone |
POST |
/commerce/shipping/rates |
Create a shipping or local_delivery rate in a zone (zoneId), or a pickup rate at a location (locationId) |
PATCH, DELETE |
/commerce/shipping/rates/{id} |
Update a rate (fields left out keep their values; null clears a limit) or delete it |
GET |
/commerce/shipping/carriers |
Whether Aramex is connected, and which account it uses (never its password or PIN) |
POST |
/commerce/shipping/quote |
The options and prices a shopper would see for a country, city, subtotal, and weightGrams. Saves nothing. |
See Shipping & Delivery.
Markets
Section titled “Markets”| Method | Path | What it does |
|---|---|---|
GET |
/commerce/sites/{siteId}/markets |
Read a store’s markets. A store never set up gets a starting point (configured: false). |
PUT |
/commerce/sites/{siteId}/markets |
Save the whole set. Markets left out are removed. Live at once, no publish needed. |
A market’s currency needs an exchange rate in Settings → Currencies unless it’s the store’s own currency, and its languages must be the store’s. See Markets.
Store settings
Section titled “Store settings”| Method | Path | What it does |
|---|---|---|
GET, PATCH |
/commerce/settings/returns |
Return rules for every store: self-serve returns, window, auto-approve, exchanges, return shipping, final-sale items, instructions |
GET, PATCH |
/commerce/settings/customer-messages |
Which order emails shoppers get (customerMessages) |
GET, PATCH |
/commerce/settings/abandoned-checkouts |
The recovery email: email, abandonAfterMinutes, emailDelayMinutes, audience |
GET, PATCH |
/commerce/settings/back-in-stock |
Whether back-in-stock emails go out (email) |
GET, PATCH |
/commerce/settings/review-requests |
The review request email: enabled, delayDays, after (delivery or shipping), plus stats on read |
GET, PATCH |
/commerce/sites/{siteId}/sign-in |
How shoppers get sign-in codes: email always, whatsapp (a number and an approved template, checked with Meta), sms (only when smsAvailable) |
GET |
/commerce/sign-in-templates |
A WhatsApp number’s approved templates that can carry a sign-in code |
GET, PATCH |
/commerce/sites/{siteId}/tracking |
Pixels (Meta, GA4, Google Ads, TikTok, Snap) and the cookie banner. Only the pixels you send change. |
GET, PATCH |
/commerce/sites/{siteId}/ai-shopping |
agentReady (llms.txt and the store’s MCP endpoint) and the store assistant |
Every PATCH here changes only the keys you send. Turning the store assistant on deploys an inbox AI agent on a web chat channel. That needs permission to manage and deploy AI agents (403 otherwise). If the response has assistant.requiresPublish: true, publish the agent. See Returns & Order Edits, Shipping & Delivery, Abandoned Checkouts, Checkout & Payments, Analytics, and AI Shopping.
Product feeds and back in stock
Section titled “Product feeds and back in stock”| Method | Path | What it does |
|---|---|---|
GET, PATCH |
/commerce/sites/{siteId}/product-feed |
Google, Meta, and TikTok feeds: which are on, their signed URLs, the last fetch, and what the feeds hold |
POST |
/commerce/sites/{siteId}/product-feed/rotate-links |
Make new feed URLs. The old ones stop working at once (400 if no feed is on). |
GET |
/commerce/sites/{siteId}/product-feed/preview |
The first items and the products left out or warned about |
GET |
/commerce/back-in-stock/products |
Per product and variant: how many shoppers wait, how many were told, and whether the store can sell it now |
GET |
/commerce/back-in-stock/requests |
One row per shopper request |
GET |
/commerce/back-in-stock/summary |
Waiting shoppers, products, alerts sent, and orders that followed |
See Back in Stock, Feeds & Reviews.
Store doctor
Section titled “Store doctor”| Method | Path | What it does |
|---|---|---|
GET |
/commerce/sites/{siteId}/doctor |
The latest report: score and findings. A store never checked is checked now. |
POST |
/commerce/sites/{siteId}/doctor/run |
Check again now. It runs at most once every 30 seconds per site; sooner returns the last report. |
See Store doctor.
Orders: shipments and cancel
Section titled “Orders: shipments and cancel”These use the orders:read / orders:write scopes.
| Method | Path | What it does |
|---|---|---|
GET |
/orders/{id}/fulfillments |
The order’s shipments with items and tracking history, plus codRemaining (cash a new shipment could still collect) |
POST |
/orders/{id}/fulfillments |
Ship some or all items. idempotencyKey is required, so a retry never ships twice. shippingDriver is manual (default, you add tracking) or aramex (books a real waybill; Aramex must be connected). Also takes weightGrams, codAmount, carrierName, trackingNumber, trackingUrl, locationId, notes. |
PATCH |
/orders/{id}/fulfillments/{fulfillmentId} |
Move a shipment on: in_transit, out_for_delivery, delivered, failed_attempt, returned_to_sender, or canceled. delivered, returned_to_sender, and canceled are final. |
POST |
/orders/{id}/cancel |
Cancel an order: releases its stock and closes open card checkouts and pay links. With refund: credit_note, posted invoices are returned with credit notes; none leaves the money as it is. |
Cancel is refused while items have shipped: cancel those shipments first, or start a return. refund: credit_note also needs permission to update invoices. To send money back to the card, process a return (refundTo: "card") or refund from the app. Orders synced from another store are shipped there, not here (409). See Shipping & Delivery and Cancel an order.
Returns and order edits
Section titled “Returns and order edits”These endpoints use the orders:read / orders:write scopes.
| Method | Path | What it does |
|---|---|---|
GET |
/order-returns |
List returns, newest first (filter by status, search with q) |
POST |
/order-returns |
Start a return for shipped items |
GET |
/order-returns/{id} |
Get a return |
POST |
/order-returns/{id}/approve |
Approve a requested return, with how the items come back |
POST |
/order-returns/{id}/decline |
Decline a request; the reason is shown to the customer |
POST |
/order-returns/{id}/cancel |
Cancel a return before it’s processed |
POST |
/order-returns/{id}/receive |
Record how many items arrived and how many go back in stock |
POST |
/order-returns/{id}/process |
Refund or exchange the return (retry-safe) |
POST |
/order-edits |
Change an order’s quantities, items, line discounts, or shipping. dryRun previews. |
Processing a return and editing an order also need the invoices.update permission for delegated users. See Returns and order edits.
Example
Section titled “Example”Add an FAQ section to the home page of the live theme, then publish:
curl -X POST "https://your-workstation.example/api/v1/commerce/sites/$SITE_ID/sections" \ -H "Authorization: Bearer $REPZO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "faq", "settings": { "heading": { "en": "Questions", "ar": "أسئلة" } } }'
curl "https://your-workstation.example/api/v1/commerce/sites/$SITE_ID/draft" \ -H "Authorization: Bearer $REPZO_API_KEY" # read the current revision
curl -X POST "https://your-workstation.example/api/v1/commerce/sites/$SITE_ID/publish" \ -H "Authorization: Bearer $REPZO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "revision": 13, "note": "Added FAQ" }'Errors worth knowing
Section titled “Errors worth knowing”| Status | Code | When |
|---|---|---|
409 |
conflict |
Your revision is stale, an address, handle, or code is taken, or a one-per-page section is already there |
422 |
validation_error |
The body is invalid, or publishing found code errors (details.code = THEME_CODE_ERRORS, details.problems) |
402 |
payment_required |
Store from a link with an empty AI balance |
502 |
upstream_error |
The domain provider refused a custom domain |