Skip to content

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.

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.

  • Themes. A site has several themes, and each has its own draft. Without themeId, an endpoint uses the site’s live theme. Send themeId in 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 optional revision; replacing the whole draft and publishing require it. A stale revision returns 409 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 page and limit (default 20, max 200) and return { data, meta }.
  • Errors use the standard shape: { "error": { "code", "message", "details" } }.
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.

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
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
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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Add an FAQ section to the home page of the live theme, then publish:

Terminal window
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" }'
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