Commerce & Tracking Tags

Commerce

A self-hosted site running WooCommerce is also a Commerce store. The Commerce API at /v1/commerce manages its:

• products, variants, images and stock
• categories (as collections) and coupons (as discounts)
• product custom fields and pages

It can also sync the store into a Meta catalog for catalog ads.

Pass this account's id as accountId. Objects report platform: "woocommerce".

The connected user must be allowed to manage WooCommerce.

WordPress.com sites cannot serve WooCommerce through Zernio. Their pages remain available through the Commerce pages endpoints.

GET /v1/commerce/store returns the capabilities the site serves.

Sales channels, menus, redirects, metaobjects, markets and marketing activities are Shopify only; see WooCommerce differences.

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

Tracking tags

Install an ad platform's pixel or site tag on the site with POST /v1/accounts/{accountId}/tracking-tags/{tagId}/install:

• accountId is your connected ads account (Meta, TikTok, Google, LinkedIn, Pinterest, X or OpenAI).
• tagId is the tracking tag.
• The body names this site's storeAccountId.

Zernio adds a Custom HTML widget with the platform's base code to a widget area of the active theme. It picks a footer area when there is one, else the first active area; pass sidebarId to choose.

Zernio then reads the widget back to confirm WordPress kept the <script> tag.

const { data } = await zernio.trackingtags.installTrackingTagOnStore({
  path: { accountId: '66b2e19d8c3f5a7e9d0b1c2d', tagId: '18ce54d4x5t' },
  body: { storeAccountId: '66b2e19d8c3f5a7e9d0b1c4f', sidebarId: 'sidebar-1' }
});

Response (200), an X Pixel:

{
  "platform": "xads",
  "install": {
    "storeAccountId": "66b2e19d8c3f5a7e9d0b1c4f",
    "platform": "wordpress",
    "siteUrl": "https://example.com",
    "tagPlatform": "xads",
    "siteTagId": "o8z1q",
    "installed": true,
    "method": "wordpress_widget",
    "widgetId": "custom_html-3",
    "sidebarId": "sidebar-1",
    "sidebarName": "Footer",
    "created": true,
    "homepageCheck": "found"
  }
}

One widget per tag. Each widget carries a Zernio marker naming its platform and on-site id. The install is idempotent per tag: calling it again updates (or moves) the same widget and returns created: false.

Tags of several platforms, or several tags of one platform, run side by side. Tag code the site owner pasted by hand is never touched.

Homepage check. With verifyHomepage (default true) Zernio fetches the homepage afterwards. homepageCheck is found, not_found, unreachable or skipped.

not_found can be a page cache that has not refreshed. The widget read-back is the authoritative check.

Status. GET with ?storeAccountId= returns:

• whether this tag's widget is live (in an active widget area, script intact)
• a read-only preflight (ready, reason and the theme's widget areas in sidebars) to check a site before installing
• tags: every Zernio widget on the site with its platform, siteTagId, widgetId, sidebarId and whether it is active

The preflight reads capabilities only, so ready: true is not a guarantee. A stripped script is detected by the install itself.

Uninstall. DELETE with ?storeAccountId= removes every widget Zernio created for the tag. It reports the count in removed (0 when nothing was installed).

What the widget contains

A widget holds the platform's base code, so on WordPress each tag records page views.

Storefront events such as add to cart or purchase are a Shopify feature.

When WordPress cannot run the tag

WordPress keeps a <script> tag only for users with the unfiltered_html capability.

When the site cannot run the tag, Zernio removes anything it wrote and answers 422 tracking_tag_install_blocked with the cause in details.reason:

{
  "error": "The active theme has no widget areas (block themes use the Site Editor instead). Add the tag's code (the `code` field on GET .../tracking-tags/{tagId}) to the footer template part with a Custom HTML block, or paste the tag's code (the `code` field on GET .../tracking-tags/{tagId}) into the theme's header instead.",
  "type": "invalid_request_error",
  "code": "tracking_tag_install_blocked",
  "details": { "reason": "no_widget_areas" }
}

The message always names the manual alternative for the tag's platform:

• the official plugin in the table above, where one exists
• otherwise, pasting the tag's code (from GET /v1/accounts/{accountId}/tracking-tags/{tagId}) into the theme