Getting started

Use this guide when you are connecting a storefront, product page, or internal print workflow to StackFill for the first time.

Choose a path

Use the no-backend embed when the storefront can safely identify products in the browser and you only need the shopper to save personalization to cart.

Use a server-minted session when your backend controls customer, cart, order, pricing, or metadata values.

No-backend embed

1. Create an embed application in the Integrations dashboard.
2. Add your allowed storefront origin.
3. Create a product mapping from your product ID to a live template.
4. Paste the widget script and button on the product page.
5. Listen for stackfill:saved and attach fill.id to the cart line item.

<script src="https://cdn.stackfill.com/widget/v1.js" async></script>
<button
  data-stackfill-open
  data-stackfill-key="stackfill_live_pk_REPLACE_ME"
  data-stackfill-product="business-card"
  data-stackfill-variant="standard">
  Personalize
</button>

window.addEventListener("stackfill:saved", (event) => {
  const fillId = event.detail.fill.id;
  cart.addMetadata({ stackfill_fill_id: fillId });
});

After checkout, your backend can reconcile generated output with the render ledger:

curl https://api.stackfill.com/v1/renders \
  -H "Authorization: Bearer stackfill_live_sk_REPLACE_ME"

Server-minted session

Create the session from your backend with a secret key, then open the returned iframe_url or pass the session to your storefront widget integration.

curl https://api.stackfill.com/v1/embed/sessions \
  -H "Authorization: Bearer stackfill_live_sk_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -d '{
    "external_product_id": "business-card",
    "external_variant_id": "standard",
    "external_cart_id": "cart_123",
    "customer": { "email": "customer@example.com" }
  }'

Common errors

product_mapping_not_found means the product ID, variant, allowed origin, or template live status does not match.

origin_not_allowed means the browser origin is not listed on the publishable key or embed application.

See Create guest embed session, Create server embed session, Resolve product mapping, and List renders.