Extensions

​

1. Upload a bundle

curl -X POST https://api.platformdtc.com/api/v1/appstore/partner/apps/$APP_ID/extension-bundles \
  -H "Authorization: Bearer $PARTNER_JWT" -H "X-CSRF-Token: $CSRF" \
  -F "file=@dist/reviews-block.js"

{ "bundle_sha256": "9f2c…", "bundle_url": "https://cdn.platformdtc.com/appstore/extensions/<app_id>/9f2c….js", "size_bytes": 8214 }

• JavaScript only (.js, UTF-8), 256 KiB maximum. Keep it small: it loads on the merchant’s storefront. Minify, and load heavy work lazily.
• The URL is content-hashed and immutable (cached for a year). Uploading the same file again returns the same URL. A new build gets a new hash, so it cannot break a store still on the old version.

​

2. Declare extensions on a version

POST /api/v1/appstore/partner/apps/{app_id}/versions
{
  "requested_scopes": ["read_products"],
  "scope_justifications": { "read_products": "Show reviews for the product being viewed" },
  "extensions": [
    {
      "type": "theme_app_block",
      "handle": "product-reviews",
      "name": "Product reviews",
      "target": "section",
      "bundle_sha256": "9f2c…",
      "settings_schema": [
        { "type": "text", "id": "heading", "label": "Heading", "default": "Customer reviews" },
        { "type": "range", "id": "limit", "label": "Reviews shown", "min": 1, "max": 20, "step": 1, "default": 5 }
      ]
    },
    { "type": "theme_app_embed", "handle": "chat-widget", "name": "Chat widget", "target": "body", "bundle_sha256": "41ab…" },
    {
      "type": "web_pixel", "handle": "analytics", "name": "Analytics", "bundle_sha256": "77d0…",
      "settings_schema": [{ "type": "text", "id": "account_id", "label": "Account ID" }]
    },
    { "type": "admin_link", "handle": "order-reviews", "name": "Request a review", "target": "order_details", "url": "/orders/review-request" }
  ],
  "app_proxy": { "prefix": "apps", "subpath": "reviews", "url": "https://reviews.example.com/proxy" }
}

• Up to 30 extensions per version. handle is ^[a-z0-9][a-z0-9-]{0,63}$ and unique within the version. name is 1–64 characters and is what the merchant sees.
• target:
  • section for blocks (the default), or product_media for a block drawn over the product gallery (see Product media blocks).
  • head or body for embeds (default body).
  • product_details, order_details or customer_details for admin links and actions (required).
• bundle_sha256 is required for blocks, embeds and pixels. It must be one of your own uploads. Admin links and actions take no bundle.
• settings_schema uses the same setting objects as theme sections: text, textarea, richtext, number, range, checkbox, select, radio, color, url, product, collection and the rest of the theme setting types, plus header and paragraph for sidebar text. It allows up to 25 settings.
  • Ids must be unique. select and radio need options. A range needs min < max and a sensible step. Defaults must match their type.
  • Web pixels accept text settings only.
• url (admin only, required) is a page path starting with / (not / itself), on your embedded_app_url’s origin, like every embedded-app path.

​

Theme app blocks

PlatformDTC.extensions.register(function render(root, ctx) {
  // root: an empty <div> owned by your block
  // ctx:  see "The render context" below
  const el = document.createElement('h2');
  el.textContent = ctx.settings.heading;
  root.appendChild(el);
  return () => root.replaceChildren(); // optional cleanup: called on unmount or when settings change
});

• The bundle is loaded once per page, however many times the block is placed. render runs once per placement, and again (after your cleanup) when the merchant changes its settings.
• Each block has its own error boundary. If your code throws, only your block disappears.
• If the app is uninstalled, or the block’s extension no longer exists in your approved version, the block renders nothing. No empty box is shown.

​

The render context

PlatformDTC.extensions.register(function render(root, ctx) {
  if (!ctx.productId) return; // not on a product section: render nothing
  let variantId = ctx.variantId;
  const unsubscribe = ctx.onVariantChange((next) => {
    variantId = next; // the block is NOT re-rendered for a variant change; keep your own state
  });
  // …build your UI in root
  return unsubscribe; // subscriptions also end when the block is removed
});

​

App blocks in the product section

​

Product media blocks

• It is offered in the theme editor only on product sections, and it renders on the product gallery of the default theme, Origin and Silent Scale. ctx.target is "product_media".
• root is full size over the active image: position: absolute; inset: 0. It moves with the gallery when the shopper switches images. Position your layer inside it with percentages so it follows the frame when the page is resized.
• root has pointer-events: none, so taps and swipes go through to the gallery (zoom, carousel). Set pointer-events: auto on each interactive element you add, and only on those. In the theme editor the whole root is clickable so the merchant can select the block.
• If the section draws no gallery (a product without media, or a section without one), the block renders nothing. It is never moved into the column instead.
• root follows whichever frame is active. To draw over one slide only (your preview belongs on the first photo, not on the lifestyle shots), read ctx.activeMedia and subscribe to ctx.onMediaChange, and hide your layer on every other frame:

PlatformDTC.extensions.register(function render(root, ctx) {
  if (!ctx.onMediaChange) return;                  // no gallery here
  const layer = root.appendChild(document.createElement('div'));
  const show = (m) => { layer.hidden = !m || m.index !== 0; };  // or match m.id to your photo's URL
  show(ctx.activeMedia);
  return ctx.onMediaChange(show);                  // unsubscribe on teardown
});

• To bring the shopper back to your slide when they change an option while looking at another photo, call ctx.setActiveMedia(index) from your option handler:

select.addEventListener('change', () => {
  if (ctx.activeMedia && ctx.activeMedia.index !== 0) ctx.setActiveMedia(0);
});

​

App blocks inside a group

​

Line item properties

​

Payload

{
  "customizer-studio": {
    "properties": [
      { "label": "Name", "value": "Alex" },
      { "label": "Font", "value": "Serif" }
    ],
    "previewImage": "https://cdn.example.com/previews/a3f9c1.png",
    "_selections": { "font": "serif", "colour": "#1a1a1a" },
    "_templateId": "8dba…"
  }
}

• Each top-level key must be the handle of an app installed and active on that store.
• The whole object, serialised as compact JSON with sorted keys, is at most 8 KB (8192 bytes) per line. Store large data on your own server and keep only an id here.
• No string anywhere may start with data:. Upload images and pass their URL.
• A line with no app data behaves exactly as before.

​

Set properties from the storefront

// Inside your block's render(root, ctx), on a product section.
function saveSelection(name) {
  window.PlatformDTC.cart.setLineProperties(ctx.productId, {
    'customizer-studio': {
      properties: [{ label: 'Name', value: name }],
      previewImage: 'https://cdn.example.com/previews/' + encodeURIComponent(name) + '.png',
      _selections: { name },
    },
  });
}

// When the shopper resets your form:
window.PlatformDTC.cart.setLineProperties(ctx.productId, null);

window.addEventListener('platformdtc:cart:change', (event) => {
  const mine = event.detail.lines.filter((l) => l.appProperties['customizer-studio']);
  // …update your own UI
});

• Namespace everything under your app handle. Writing under another app’s handle, or a handle that is not installed on the store, is rejected.
• Put only what the shopper and merchant should read in properties. Everything else goes under a _ key.
• Carts with line properties are sent to checkout through the cart API only. Cart permalinks cannot carry them. If the cart cannot be saved, the shopper sees an error rather than an order without their customisation.

​

Cart guards

const unsubscribe = window.PlatformDTC.cart.addGuard(productId, ({ productId, action }) => {
  if (!form.name.value.trim()) return { ok: false, message: 'Enter the name to engrave.' };
  return { ok: true };
});
// in a theme app block: ctx.addCartGuard(fn), removed with the block

• Every path runs it, first. Add to cart, Buy it now, the Apple Pay / Google Pay / PayPal / Link express buttons, quick add on a product card, bundles and Build-a-Box all run the product’s guards before anything else. They do not depend on button labels or markup. action is "add" for a cart add and "buy" for a direct hand-off to checkout.
• Guards run before line properties are read. A guard can finish its work and call setLineProperties for the same click.
• Answer with true, undefined or { ok: true } to allow, and false or { ok: false, message } to refuse. message is written for the shopper (at most 300 characters).
• Synchronous is best. When every guard answers synchronously the click proceeds in the same tick. A guard may return a Promise instead. It gets 1.5 seconds.
• It fails closed. A guard that throws, rejects, times out or returns anything else refuses the click, because an unchecked customisation is not a checked one.
• A refusal adds no cart line and opens no checkout. The platformdtc:cart:blocked event fires on window with detail: { productId, action, message }. Handle it yourself (scroll to the field, highlight it) and call event.preventDefault(). If no listener does, the storefront shows message in its own notice.
• Guards are per page. A guard registered on the product page does not follow the product to other pages, and lines already in the cart are never re-checked.

window.addEventListener('platformdtc:cart:blocked', (event) => {
  if (event.detail.productId !== ctx.productId) return;
  event.preventDefault();          // we show it inline instead of the storefront notice
  showInlineError(event.detail.message);
});

​

Read them on the order

• In the orders/create webhook: line_items[].app_properties.
• From the order API: GET /api/v1/agent/v1/orders/{order_id} returns items[].appProperties ({} when the line has none).

​

App embeds

const script = document.currentScript;               // read synchronously, at top level
const settings = JSON.parse(script.dataset.settings); // schema defaults merged with the merchant's values
const installId = script.dataset.dtcAppEmbed.split('/')[0];

​

Web pixels

register(({ analytics, browser, settings, init }) => {
  analytics.subscribe('all_events', (event) => {
    fetch('https://collect.example.com/e', {
      method: 'POST',
      keepalive: true,
      body: JSON.stringify({ account: settings.account_id, event }),
    });
  });
  analytics.subscribe('checkout_completed', async (event) => {
    await browser.localStorage.setItem('last_order', event.data.order_id ?? '');
  });
});

• browser.cookie.get(name) and browser.cookie.set(cookieString)
• browser.localStorage and browser.sessionStorage, each with getItem, setItem and removeItem

​

App proxy

"app_proxy": { "prefix": "apps", "subpath": "reviews", "url": "https://reviews.example.com/proxy" }

• prefix is one of apps, a, community or tools. These four path prefixes are reserved on every PlatformDTC storefront. subpath is ^[a-z0-9-]{1,30}$.
• Added query parameters:
  • shop: the store’s permanent platform host (<store>.myshopquantum.ai). It stays the same when the merchant changes their custom domain.
  • path_prefix: /{prefix}/{subpath}.
  • timestamp: Unix seconds.
  • logged_in_customer_id: currently always empty.
  • signature.
• Request Cookie and Authorization headers are removed. X-Forwarded-Host (the domain the shopper used) and X-Forwarded-For are added.
• Your response’s status, body and Content-Type are passed through. Set-Cookie is removed. Redirects are passed to the browser, not followed.
• Timeout is 10 seconds. After that the shopper gets a 504.
• Content-Type: application/liquid is not supported. PlatformDTC storefronts are not Liquid themes, and such a response returns 501. Return HTML (or JSON) instead.

​

Verify the signature

1. Remove signature from the query parameters.
2. For each remaining key, join its values with ,. Format each pair as key=value.
3. Sort the pairs, then concatenate them with no separator.
4. Compute a hex HMAC-SHA256 of that string, keyed with your app’s client_secret. Compare it to signature in constant time.
5. Reject requests whose timestamp is more than a few minutes old.

import crypto from 'node:crypto';

export function verifyProxy(query, clientSecret) {
  const { signature, ...rest } = query; // e.g. Object.fromEntries of URLSearchParams, arrays kept
  const message = Object.keys(rest)
    .map((k) => `${k}=${[].concat(rest[k]).join(',')}`)
    .sort()
    .join('');
  const digest = crypto.createHmac('sha256', clientSecret).update(message).digest('hex');
  const ok =
    typeof signature === 'string' &&
    signature.length === digest.length &&
    crypto.timingSafeEqual(Buffer.from(digest), Buffer.from(signature));
  return ok && Math.abs(Date.now() / 1000 - Number(rest.timestamp)) < 300;
}

​

Admin links and actions