Jump to section

API v3 — Integration Guide

{ E-commerce Gifting }
Integration Guide

Add video messages to your e-commerce gifts. Two integration scenarios, aligned with the interactive demo. Choose your delivery method and go live.

Try the interactive demo Choose your scenario

Key Concepts

Core terminology you need before integrating.

CRID

Client Reference ID — Your unique order identifier (e.g. order number). Used in every API call to associate a video message with a specific order.

Container

A container is a "slot" ready to receive a video message. Created via POST /v3/containers. Returns a urid and editKey for the widget.

Widget

A JavaScript module that embeds the Livstick recording interface directly in your checkout page. Initialized with urid and editKey.

Environments

Environment	Base URL	Usage
Production	`https://public.api.livstick.com/v3`	Live environment
Staging	`https://service.stage.livstick.com/v3`	Pre-production testing

Choose Your Scenario

Two integration paths, matching the delivery options in the interactive demo.

Step-by-Step Guides

Detailed implementation guides for each scenario. Toggle between Widget Capture (recommended, as shown in the demo) and Email Capture.

1Scenario 1

Email on Delivery

The video message is sent by email when the carrier confirms package delivery.

The customer records their video directly on your order confirmation page via the Livstick widget. The video is delivered by email when the carrier confirms delivery.

Create a container

When the customer confirms their order with the video message option, your back-end creates a Livstick container. This prepares the "slot" that will receive the video.

POST/v3/containers

Request Bodyjson

{
  "crid": "ORD-2026-1234",
  "email": "alice@example.com",
  "receiverEmail": "bob@example.com",
  "language": "en",
  "additionalData": {
    "senderFirstName": "Alice",
    "receiverFirstName": "Bob",
    "productName": "Gift Box"
  }
}

Responsejson

{
  "crid": "ORD-2026-1234",
  "urid": "abc123xyz9",
  "state": "recording_open",
  "editKey": "550e8400-e29b-41d4-a716-446655440000",
  "links": {
    "recordingUrl": "https://brand.example/abc123xyz9",
    "previewUrl": "https://brand.example/preview/abc123xyz9"
  }
}

Store the crid, urid and editKey. The urid and editKey are needed to initialize the recording widget.

Display the recording widget

On your order confirmation page, load the Livstick JavaScript widget. The customer records their video message without leaving your site.

Widget Embed Codehtml

<!-- Mount point -->
<div id="livstick-plugin"></div>

<!-- Widget script -->
<script
  type="module"
  src="https://app.livstick.com/widget/assets/widget.latest.js"
  data-uid="{urid}"
  data-editKey="{editKey}"
  data-lang="en"
></script>

The widget uses the urid and editKey from Step 1.

Full widget documentation →

Add shipment tracking

When the order ships, your back-end sends the carrier tracking information to Livstick. This enables automatic video delivery upon package arrival.

PATCH/v3/containers/{crid}

Request Bodyjson

{
  "shipmentCode": "1Z999AA10123456784",
  "shipmentCarrier": "ups"
}

Responsejson

{
  "result": "ok"
}

Supported carriers: chronopost, ups, dhl, coursier, other.

Automatic delivery on package arrival

Livstick monitors the carrier and automatically sends the video message by email to the recipient when the package is confirmed delivered.

No additional API call needed. Livstick handles carrier webhooks internally.

2Scenario 2

Physical Card in Package

A QR code card is printed and inserted in the package. The recipient scans to watch.

The customer records on your site via the widget. You retrieve a QR code to print on a card inserted in the package. The recipient scans to watch.

Create a container

When the order is confirmed with the video option, your back-end creates a container.

POST/v3/containers

Request Bodyjson

{
  "crid": "ORD-2026-1234",
  "email": "alice@example.com",
  "language": "en",
  "additionalData": {
    "senderFirstName": "Alice",
    "receiverFirstName": "Bob"
  }
}

Responsejson

{
  "crid": "ORD-2026-1234",
  "urid": "abc123xyz9",
  "state": "recording_open",
  "editKey": "550e8400-e29b-41d4-a716-446655440000",
  "links": {
    "recordingUrl": "https://brand.example/abc123xyz9",
    "previewUrl": "https://brand.example/preview/abc123xyz9"
  }
}

The receiver email is optional for physical card delivery — the QR code is the delivery mechanism.

Display the recording widget

Load the Livstick widget on your confirmation page. The customer records their video message inline.

Widget Embed Codehtml

<!-- Mount point -->
<div id="livstick-plugin"></div>

<!-- Widget script -->
<script
  type="module"
  src="https://app.livstick.com/widget/assets/widget.latest.js"
  data-uid="{urid}"
  data-editKey="{editKey}"
  data-lang="en"
></script>

The widget uses the urid and editKey from Step 1.

Full widget documentation →

Retrieve QR code for printing

Fetch the QR code image to print on a card included in the package.

GET/v3/containers/{crid}/qrcode

Responsejson

// Returns: QR code image (PNG, 300×300px)
// Alternative: GET /v3/containers/{crid}/card
// Returns: Ready-to-print PDF card with QR code + branding

The QR code contains only an opaque identifier — no sensitive data is encoded.

Activate the QR code

When the package ships, activate the QR code by calling /notify. Until activated, scanning shows a "not yet available" message.

POST/v3/containers/{crid}/notify

Responsejson

{
  "result": "ok"
}

This prevents the recipient from seeing the video before receiving the physical package. No request body needed.

Recipient scans the QR code

The recipient opens the package, finds the card, scans the QR code with their phone, and watches the personalized video message in their browser.

No app installation required.

Widget Integration

Embed the Livstick recording widget directly in your checkout or confirmation page.

Add this script to your confirmation page:

<!-- Mount point -->
<div id="livstick-plugin"></div>

<!-- Widget script -->
<script
  type="module"
  src="https://app.livstick.com/widget/assets/widget.latest.js"
  data-uid="{urid}"
  data-editKey="{editKey}"
  data-lang="en"
></script>

Data Attributes

Attribute	Required	Description
`data-uid`	Yes	The urid from the POST /v3/containers response
`data-editKey`	Yes	The editKey from the POST /v3/containers response
`data-lang`	No	Widget UI language (en, fr, de, es, etc.)

JavaScript Events

livstickRecorded

Fired on document when the user completes a video recording. Listen for this event to update your UI (e.g. show a success message).

document.addEventListener('livstickRecorded', () => {
  // Video recorded successfully
  showSuccessMessage();
});

API Reference

Endpoints used in the gifting integration scenarios. All endpoints require Bearer token authentication.

Method	Path	Role	Key	Docs
POST	`/v3/containers`	Create a new video container	Private	View
GET	`/v3/containers/{crid}`	Get container details and status	Private	View
PATCH	`/v3/containers/{crid}`	Update container metadata (tracking, etc.)	Private	View
POST	`/v3/containers/{crid}/notify`	Send notification or activate QR code	Private	View
GET	`/v3/containers/{crid}/qrcode`	Get QR code image (PNG)	Private	View
GET	`/v3/containers/{crid}/card`	Get printable PDF card with QR code	Private	View
GET	`/v3/containers/{crid}/url`	Get the video viewing URL	Private	View

View full interactive API documentation →

Ready to transform your customer experiences?

Let's discuss your project and discover how LIVSTICK can help you create unforgettable moments.

Response within 24h

Personalized demonstration

No commitment