Data contract

The loader transports initialization and completion objects but does not own their Shopify catalogue or persistence rules. Obtain the correct design, template, version, and variant identities from Giftie for the target store.

Legacy initialization

The legacy runtime uses /boot. A new card normally supplies:

interface LegacyCardInit {
  shop: string
  design: GreetingCardDesign
  designId?: string
  shopifyVariantId: string | number
  variantIndex?: number
  preserveState?: boolean
  sessionId?: string
  draftPayload?: GreetingCardSessionPayload
  playbackBaseUrl?: string
}

• design is the approved Giftie greeting-card schema.
• shop and shopifyVariantId identify the Shopify store and matching variant.
• variantIndex defaults to 0.
• To edit a saved Shopify card, pass preserveState: true, sessionId, and shop. The builder loads the persisted editable payload and schema.
• A trusted host can provide draftPayload with preserveState: true when it already owns the editable state.

If design is omitted, designId can select a design already present in the builder catalogue. Do not assume a catalogue ID exists across environments.

Yuzu initialization

The Yuzu runtime uses /v2/boot. Select it with runtime: 'yuzu' or yuzuGcbEnabled: true.

interface YuzuCardInit {
  yuzuGcbEnabled: true
  shop: string
  shopifyVariantId: string | number
  templateId: string
  templateVersionId: string
  templateSchema?: YuzuTemplateSchema
  designSchema?: YuzuTemplateSchema
  baseTemplateSchema?: YuzuTemplateSchema | null
  sessionId?: string
  preserveState?: boolean
  cardFormat?: 'folded' | 'flat'
  safeAreaMm?: number
  playbackBaseUrl?: string
}

shop, shopifyVariantId, templateId, and templateVersionId are required. The builder can use an inline schema or load the approved template projection. When a design inherits from a base template, provide both schemas so the builder can compose them correctly.

For editing, preserveState: true and sessionId restore the saved Yuzu session only when its template, version, and Shopify variant identities match the requested card.

Completion payloads

For an embedded legacy Shopify card, completion contains the saved card payload plus its session ID:

type LegacyCardComplete = GreetingCardSessionPayload & {
  sessionId: string
}

For an embedded Yuzu card, completion is the saved session identity:

interface YuzuCardComplete {
  sessionId: string
  templateId: string
  templateVersionId: string
  shopifyVariantId: string
}

The session ID confirms that Giftie persisted the card. It does not add a cart line or update host application state. Associate it with the intended cart line through the approved Giftie/Shopify integration.

Outside Shopify embed mode, the legacy builder can return its card payload without a persisted sessionId. Treat payload shape outside the contracts above as integration-specific and agree it with Giftie.

Data safety

Initialization data is sent to the builder iframe with postMessage, targeted to the resolved builder origin. Do not include credentials, access tokens, or unrelated personal/order data. Treat shopper-authored card content as sensitive application data after receiving it.