Server sessions

Use server-minted embed sessions when your backend should control customer, cart, order, metadata, or TTL values.

Create a session

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", "name": "Jordan Tate" },
    "metadata": { "channel": "storefront" }
  }'

The response includes an embed_session, a short-lived client_secret, and an iframe_url.

Save behavior

The iframe save endpoint currently saves a fill and marks the embed session as saved. Your cart or order should store the returned fill.id.

Track generated output

Use the render ledger when your production system needs to reconcile generated PDFs, preflight results, and storefront order metadata.

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

Use GET /v1/renders/{id} to refresh a single row and retrieve a short-lived signed_url when the PDF is available.

Common errors

missing_template means the request did not include a template, product mapping, or resolvable product ID.

template_not_found means the target template is missing or not available to the team.

See Create server embed session, List renders, and Get render.