Static HTML/JS checkout for product pages

Add the public script once, authorize the storefront domain in WireGum Storefront, then place data attributes wherever the CMS renders a product page.

1. Authorize the domain

Add the live website, local, or staging origin in Storefront. Browser requests from other origins cannot fetch products or create Checkout Sessions for the workspace.

2. Install the script

<script
  async
  src="https://app.example.com/api/storefront/widget"
  data-wiregum-organization="workspace-slug"
></script>

3. Add a buy box

<div data-wiregum-product="wg_product_ref" lang="it"></div>

Custom markup

<div data-wiregum-product="wg_product_ref" lang="it">
  <div data-wiregum-price></div>
  <div data-wiregum-variant-selector></div>
  <input data-wiregum-quantity type="number" min="1" value="1">
  <button data-wiregum-add-to-cart type="button">Add to cart</button>
</div>

<div data-wiregum-cart-count></div>
<div data-wiregum-country-selector></div>
<div data-wiregum-cart></div>

Generated cart controls use data attributes only, so the CMS theme can style them with vanilla CSS, Tailwind classes on the parent, or framework-specific wrappers.

<div data-wiregum-cart>
  <!-- WireGum renders data attributes only:
  data-wiregum-cart-item
  data-wiregum-cart-item-name
  data-wiregum-cart-item-price
  data-wiregum-cart-decrement
  data-wiregum-cart-item-quantity
  data-wiregum-cart-increment
  data-wiregum-cart-remove
  data-wiregum-cart-total
  data-wiregum-checkout
  -->
</div>

Product grid add-to-cart buttons

A grid can render one button per product before the site has internal product pages. Putdata-wiregum-product on the card or directly on the button. WireGum fetches every product reference, binds each button, and adds the default or selected variant to the shared cart. Use the WireGum public ID, for example wg_..., when the integration should survive slug changes. Product slugs are still supported.

<section class="product-grid" lang="it">
  <article data-wiregum-product="wg_12ab34cd56">
    <h2>Linen tote</h2>
    <div data-wiregum-price></div>
    <button data-wiregum-add-to-cart type="button">Add to cart</button>
  </article>

  <article data-wiregum-product="wg_78ef90ab12">
    <h2>Cotton cap</h2>
    <div data-wiregum-price></div>
    <button data-wiregum-add-to-cart type="button">Add to cart</button>
  </article>

  <button
    data-wiregum-product="wg_34cd56ef78"
    data-wiregum-add-to-cart
    type="button"
  >
    Add scarf
  </button>
</section>

<div data-wiregum-cart-count></div>
<div data-wiregum-country-selector></div>
<div data-wiregum-cart></div>

For products with variants, keep a variant selector in the card or pass a fixeddata-wiregum-variant public variant ID on the button. The shipping country selector should remain visible when shipping rates depend on country.

API contract

Use the same public endpoints if a site wants to build its own UI. The request origin must still match an authorized live, local, or staging domain.

GET https://app.example.com/api/storefront/products?organization=workspace-slug&products=wg_product_ref
POST https://app.example.com/api/storefront/checkout
Content-Type: application/json

{
  "organizationSlug": "workspace-slug",
  "locale": "it",
  "shippingCountry": "IT",
  "items": [
    { "variantId": "wg_variant_ref", "quantity": 1 }
  ]
}

Stability and versioning

The current storefront contract is v0.1. The public widget exposes window.WireGum.version as 0.1.0.

Stable surface: data attributes, window.WireGum methods, product payload fields used by the widget, and checkout request fields.Additive changes can ship on the same contract. Breaking changes should use a new major contract and keep the previous one available during a migration window.Use WireGum public product and variant IDs, not editable slugs or internal database IDs, when CMS integrations must remain stable over time.