# Online store API

> Public REST endpoints for online stores: sites, themes, the builder draft, theme code, publishing, domains, menus, collections, content, discounts, reviews, store setup (payments, shipping, markets, settings, feeds, store doctor), shipments, cancels, returns, and order edits.

The public REST API exposes the same online store operations as the [store builder](https://workstation.repzo.com/docs/online-store/store-builder) and the [`repzo store` CLI](https://workstation.repzo.com/docs/developers/online-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](https://workstation.repzo.com/docs/configuration/developer-api).

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

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](#returns-and-order-edits).

## Conventions

- **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" } }`.

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

| 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

| 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

| 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

| 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](https://workstation.repzo.com/docs/developers/online-store/theme-code).

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

| 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

| 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

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](https://workstation.repzo.com/docs/online-store/products-and-collections), [Navigation and content](https://workstation.repzo.com/docs/online-store/navigation-and-content), and [Discounts](https://workstation.repzo.com/docs/online-store/discounts).

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

| 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](https://workstation.repzo.com/docs/online-store/checkout-and-payments).

### 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](https://workstation.repzo.com/docs/online-store/shipping-and-delivery).

### 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](https://workstation.repzo.com/docs/online-store/markets).

### 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](https://workstation.repzo.com/docs/online-store/returns-and-order-edits), [Shipping & Delivery](https://workstation.repzo.com/docs/online-store/shipping-and-delivery#customer-emails), [Abandoned Checkouts](https://workstation.repzo.com/docs/online-store/abandoned-checkouts), [Checkout & Payments](https://workstation.repzo.com/docs/online-store/checkout-and-payments), [Analytics](https://workstation.repzo.com/docs/online-store/analytics), and [AI Shopping](https://workstation.repzo.com/docs/online-store/ai-shopping).

### 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](https://workstation.repzo.com/docs/online-store/marketing).

### 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](https://workstation.repzo.com/docs/online-store#store-doctor).

## 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](https://workstation.repzo.com/docs/online-store/shipping-and-delivery#ship-an-order) and [Cancel an order](https://workstation.repzo.com/docs/online-store/returns-and-order-edits#cancel-an-order).

## 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](https://workstation.repzo.com/docs/online-store/returns-and-order-edits).

## Example

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

```bash
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

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

## Related pages

- [Developer API and CLI](https://workstation.repzo.com/docs/configuration/developer-api)
- [Build a store from the CLI](https://workstation.repzo.com/docs/developers/online-store/cli)
- [Theme code (Liquid sections)](https://workstation.repzo.com/docs/developers/online-store/theme-code)
- [Sites](https://workstation.repzo.com/docs/online-store/sites)
- [Themes](https://workstation.repzo.com/docs/online-store/themes)
