Save payload

The browser SDK calls onVideoSave after it saves a video or audio recording. Despite the callback's historic name, the payload identifies both recording types through mode.

interface GiftieSavePayload {
  videoCode: string
  mode: 'video' | 'audio'
  timestamp: string
  occasion?: string
}

• videoCode is the Giftie recording reference. The name is retained for compatibility when mode is audio.
• mode identifies whether the saved recording is video or audio.
• timestamp is an ISO timestamp created in the shopper's browser when the widget reports the save.
• occasion is present only when the shopper selected one.

Fields shown in old comments, including videoId and userId, are not in the released save payload.

The callback confirms that Giftie saved the recording and emitted its host-page event. It does not mean that a Shopify cart was updated or that downstream media processing has finished.

Host responsibility

The SDK returns the payload but does not decide what your application does with it. A direct integration must:

1. Validate that videoCode exists.
2. Persist the reference or associate it with the intended order/cart item.
3. Catch failures from its own asynchronous work.
4. Update visible application or cart state only after that work succeeds.

For a custom Shopify integration, Giftie must supply the correct recording add-on variant. The released theme integration uses _gt_videoCode as the private line-item property that identifies the recording. Do not copy a variant ID or additional private properties from another store.

Detailed Shopify cart behavior is outside the browser SDK. Most merchants use Giftie's standard theme integration. Developers adapting a custom cart can review Cart refresh.

Callback timing

The loader invokes save callbacks synchronously but does not await returned promises. Asynchronous host work may continue after the modal begins closing and must catch its own rejection.

A synchronous throw interrupts the remaining save handling. Catch synchronous errors inside the callback as well as promise rejections from any work it starts.