Commerce

The Commerce API is one platform-neutral API at /v1/commerce over every connected store. Write an integration once and it works on Shopify and on WooCommerce (self-hosted WordPress). Pick the store with accountId: a query parameter on reads and a body field on writes. It is the _id of the connected shopify or wordpress account.

All data lives on the store. Zernio proxies each call and stores nothing, except the catalog syncs you create.

Conventions

Connect a store

A Commerce store is an account you already connect for blogs:

• Shopify: the OAuth flow with the store's myshopify.com domain, an install from the Shopify App Store, or a custom-app Admin token. See Shopify.
• WooCommerce: connect the self-hosted WordPress site with a username and an Application Password. See WordPress. The user must be allowed to manage WooCommerce. WordPress.com sites cannot serve WooCommerce through Zernio: the WordPress.com token reaches no WooCommerce API.

Capabilities and extra permissions

Call Get a store before anything else. It returns the store's currency and country, the capabilities it can serve now, the missingCapabilities the platform supports but this store has not granted, and grantPermissionsUrl.

curl "https://zernio.com/api/v1/commerce/store?accountId=66b2e19d8c3f5a7e9d0b1c2d" \
  -H "Authorization: Bearer $ZERNIO_API_KEY"

{
  "store": {
    "accountId": "66b2e19d8c3f5a7e9d0b1c2d",
    "platform": "shopify",
    "name": "Acme",
    "domain": "acme.myshopify.com",
    "url": "https://acme.com",
    "currency": "USD",
    "country": "US",
    "capabilities": ["products.read", "products.create", "products.update", "products.status", "products.price", "products.variants", "products.images", "collections.read", "collections.write", "collections.metafields", "metafields.read", "metafields.write", "pages.read", "pages.write"],
    "missingCapabilities": ["products.images_remove", "inventory.read", "inventory.write", "channels.read", "channels.write", "discounts.read", "discounts.write", "discounts.codes", "navigation.read", "navigation.write", "metaobjects.read", "metaobjects.write", "markets.read", "markets.write", "marketing.write"],
    "grantPermissionsUrl": "https://admin.shopify.com/store/acme/oauth/install?client_id=...&optional_scopes=write_files%2Cwrite_inventory%2Cread_locations%2C..."
  }
}

Shopify

Every install grants the products, collections, metafields and pages capabilities. The rest need optional scopes that the store owner approves separately, so a store that only uses blogs is never asked for them. Send the owner to grantPermissionsUrl: it opens the Shopify admin and approves the missing scopes on the existing install, with no reinstall, and the owner can revoke them later. Call Get a store again afterwards to read the new capabilities.

grantPermissionsUrl is null when nothing is missing, and on a store connected with a custom-app token: that token carries the custom app's scopes, not Zernio's, so the merchant adds the scopes to their custom app instead. A store connected before product access existed lacks the required product scopes, which the link does not cover: reconnect it.

Calling an operation whose scope is missing answers 403 insufficient_permissions, and the message points to grantPermissionsUrl.

WooCommerce

WooCommerce has no optional permissions, so grantPermissionsUrl is always null. The store capabilities appear when the site runs WooCommerce and the connected user can manage it; pages.read and pages.write appear when the user can edit pages, even on a site without WooCommerce. See WooCommerce differences for what the platform does not serve.

Endpoint map

Every operation also lists its platforms on its reference page.

Products

Variants, options and images

Inventory and locations

Collections

On WooCommerce, collections are product categories.

Discounts

On WooCommerce, discounts are coupons.

Sales channels

Markets and price lists

Metafields and metaobjects

Pages, menus and redirects

On WooCommerce, pages are the WordPress site's pages.

Marketing activities

Record a post, ad or message you ran for the merchant in the store's Marketing section, with its link and UTM parameters for attribution. Use your own id (for example the Zernio post id) as remoteId.

Examples

List and create products

curl "https://zernio.com/api/v1/commerce/products?accountId=66b2e19d8c3f5a7e9d0b1c2d&status=active&limit=50" \
  -H "Authorization: Bearer $ZERNIO_API_KEY"

query is passed to the platform's product search as is, and collectionId narrows the list to one collection. A status the platform has no equivalent of returns an empty page.

A new product starts as draft unless you send status: "active". It takes up to 3 options, 100 variants and 20 images:

curl -X POST "https://zernio.com/api/v1/commerce/products" \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "66b2e19d8c3f5a7e9d0b1c2d",
    "title": "Linen Shirt",
    "descriptionHtml": "<p>Breathable linen, cut for summer.</p>",
    "status": "active",
    "images": [{ "url": "https://cdn.example.com/linen-shirt.jpg", "altText": "Linen shirt" }],
    "options": [{ "name": "Size", "values": ["M", "L"] }],
    "variants": [
      { "sku": "LS-M", "price": "49.00", "options": [{ "name": "Size", "value": "M" }] },
      { "sku": "LS-L", "price": "49.00", "options": [{ "name": "Size", "value": "L" }] }
    ]
  }'

Activate, deactivate, archive or delete products takes up to 50 product ids and reports each product's outcome, so one failure does not abort the rest. A delete is permanent on both platforms.

Set stock

Read the location ids with List locations, then set or adjust per variant. mode: "set" makes quantity the new available count; mode: "adjust" adds it (negative to subtract). The response is the product's stock after the change.

curl -X POST "https://zernio.com/api/v1/commerce/products/8214569812345/inventory" \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "66b2e19d8c3f5a7e9d0b1c2d",
    "mode": "adjust",
    "changes": [{ "variantId": "44021234567890", "locationId": "71234567890", "quantity": -2 }]
  }'

Sync a store to a Meta catalog

A catalog sync keeps a Meta product catalog in step with a store, for catalog ads (goal: catalog_sales) and Shops. It works on both platforms.

You need:

• accountId: the store.
• catalogAccountId: a connected facebook, instagram or metaads account whose Meta login can manage the catalog (the catalog_management permission). A WhatsApp account cannot hold a sync, because background runs refresh the catalog token through a Meta login.
• catalogId: the numeric Meta catalog id. Find it with List catalogs.

curl -X POST "https://zernio.com/api/v1/commerce/catalog-syncs" \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "66b2e19d8c3f5a7e9d0b1c2d",
    "catalogAccountId": "66c3f2a0b1d4e5f6a7b8c9d0",
    "catalogId": "1234567890123456"
  }'

The call answers 202 with the sync in runStatus: "pending", and the first full run starts in the background. One store syncs to a given catalog once: a second create for the same pair is 409 catalog_sync_conflict. A catalog can take several stores.

Once the run has finished, Get a catalog sync reads:

{
  "catalogSync": {
    "id": "66d4a1b2c3d4e5f6a7b8c9d0",
    "accountId": "66b2e19d8c3f5a7e9d0b1c2d",
    "catalogPlatform": "meta",
    "catalogAccountId": "66c3f2a0b1d4e5f6a7b8c9d0",
    "catalogId": "1234567890123456",
    "runStatus": "succeeded",
    "lastRunStartedAt": "2026-09-29T05:20:04.000Z",
    "lastRunFinishedAt": "2026-09-29T05:21:37.000Z",
    "lastError": null,
    "itemsSent": 412,
    "itemsSkipped": 9,
    "itemsDeleted": 3,
    "createdAt": "2026-09-20T10:02:11.000Z"
  }
}

What a run does

Each product variant becomes one catalog item, grouped by product (item_group_id). A product is listed only when it is active, published to the online store (it has a storefront url) and has at least one image. Item ids are namespaced to the store (<platform>:<store>:<variantId>), so a run only ever touches items this store put in the catalog.

A full run pushes every listable variant, then deletes this store's items that are no longer listable or no longer exist. The counters describe the last run:

runStatus is pending until the first run starts, running during a run and succeeded or failed after it. A run in which Meta rejected every item is failed. A run that has not finished after 30 minutes reads as failed and is retried on the next daily pass.

Keeping it current

• Product changes: a product created, updated or deleted on the store refreshes its items within minutes. Shopify notifies Zernio through its product webhooks; WooCommerce through webhooks Zernio registers on the site when a self-hosted site is connected and again when a sync is created. A deleted product queues a full run of the sync, since its variant ids are gone with it.
• Daily pass: every sync that has not run in the last 20 hours runs once a day, which catches missed deliveries and deleted variants. Syncs of a disconnected store are skipped until it is reconnected.
• On demand: Run a catalog sync now (POST /v1/commerce/catalog-syncs/{syncId}/run) queues a full run and answers 202. It is 409 catalog_sync_conflict while a run is in progress.

The same product changes also reach your own webhooks as commerce.product.created, commerce.product.updated and commerce.product.deleted, with the store and product id only; read the product with Get a product.

Stop a sync

Stop a catalog sync (DELETE /v1/commerce/catalog-syncs/{syncId}) stops syncing. Items already in the catalog stay there. List catalog syncs and Get a catalog sync read the state; reading and stopping keep working after the store is disconnected.

WooCommerce differences

WooCommerce is reached through the self-hosted site's REST API with the connected user's Application Password. What differs from Shopify:

Common errors

Related

• Commerce API reference: every endpoint with its fields.
• Shopify: connecting a store, blogs and tracking pixels.
• WordPress: connecting a site, blogs and tracking tags.
• Product catalogs: the Meta catalogs a sync writes to.
• Pixels and tracking tags: installing ad pixels on a store.