API Tutorials
HELP CENTERINTEGRATIONSSTATUS PAGELOGINGET STARTED FREE
Start typing to search…

Redeem Gift Hosted Widget

The Redeem Gift Hosted Widget is a Cleeng hosted customer flow that allows gift recipients to redeem gift subscriptions purchased by others. When a gift is purchased, the recipient receives an email with a redemption link. The widget handles authentication, gift code verification, and subscription activation in a seamless flow.

To see the step-by-step gift redemption user journey, go to the User Flow section of this guide.

📘

If you want to learn more about hosted customer flows, review the currently supported features, and see how they compare to other integration methods, see our overview of available frontend integration options and their benefits.

Key Features

  • Built-in authentication (registration/login)
  • SSO integration support
  • Automatic gift code verification from email links
  • Alternative redemption via checkout flow

Overview

Gift subscriptions feature allows you to configure gift offers and let your customers buy them for their friends and family.

Gift subscriptions feature involves three roles:

  • Gifter - a customer who buys a gift (a current subscriber or non-subscriber).
  • Recipient - a person who receives a gift: a current subscriber or a person that doesn’t have a subscription yet.
  • Gift- a subscription offer: monthly, 3-month, 6-month, or annual (excluding weekly and seasonal subscriptions) that is purchased by a gifter for a recipient.

The Redeem Gift Hosted Widget is used by the recipient to redeem the gift subscription.

Prerequisites

Before integrating the Redeem Gift hosted widget, make sure you have:

  1. A Cleeng account
  2. The cleeng.js embed script integrated on your site.
  3. A subscription offer created in the Cleeng dashboard with Purchasable as a gift option enabled.
  4. A dedicated redemption page URL configured in Cleeng Dashboard (this is where a recipient will be redirected to redeem their gift).
  5. (Optional) SSO authentication tokens if using custom identity management

Code Integration

To embed a Cleeng widget, follow these steps:

1. Include the Cleeng-hosted script in your HTML file

In the index.html, or any HTML file of your app that will be loaded before using a Cleeng widget, include a Cleeng-hosted script in the <head> section of the document.

<script type="module" src="https://widgets.prod.cleeng.com/cleeng.js"></script>

Optional: Sandbox

If you test the widget in Sandbox, the URL for the script will be different:

<script type="module" src="https://widgets.sandbox.cleeng.com/cleeng.js"></script>

2. Create a container for the widget

Create an empty HTML container, e.g., <div /> element, with required data as data-* attributes, as in the example below

<div
  data-cleeng-widget="redeem-gift"
  data-cleeng-publisher-id="123"
  data-cleeng-language="en-US"
/>

Where:

  • data-cleeng-widget: the specific Cleeng widget you would like to render. Value: redeem-gift
  • data-cleeng-publisher-id: Your unique Cleeng publisher ID (found in the Cleeng Dashboard under Admin & Tools > API Keys).
  • data-cleeng-language: The language displayed to the end user. Supported values: en-US English, nl-NL Dutch, de-DE German, fr-FR French, pt-BR Portuguese (Brazil), pt-PT Portuguese (Europe), es-ES Spanish. If you omit this attribute, the widget defaults to English en-US.

3. (Optional) Support for external authentication flow (SSO)

If your application uses an external identity provider, you can integrate Single Sign-On (SSO) with Cleeng’s widgets by programmatically passing authentication tokens.

After a user successfully logs in or registers through your external system, and you've generated the necessary jwt and refreshToken using Cleeng's SSO Login API endpoint, use the window.cleeng.setAuthTokens() method to authenticate the user in the widget.

This function sends the tokens to the widget and ensures that:

  • The user's session is recognized across Cleeng widgets.
  • The authenticated state remains synchronized when tokens are refreshed or reissued.

Call this method whenever the user's authentication state changes – the user logs in, logs out, or their tokens change. This keeps the frontend session in sync across your application and the Cleeng widgets.

Example:

// Set authentication tokens for all widgets
await window.cleeng.setAuthTokens({
  jwt: 'your-jwt-token',
  refreshToken: 'your-refresh-token'
});

As setAuthTokens method returns a Promise object, be sure to await its resolution. This way, you ensure that setting the authentication tokens will not be disrupted, and the application will proceed further only after this operation has finished.

User Flow

A recipient of a gift can redeem it in two ways:

Email link redemption (primary flow)

  1. The recipient receives gift email with a redemption link.
  2. The recipient clicks the link and arrives at your redemption page.
  3. If not authenticated:
    • A registration form is presented
    • The recipient creates an account or logs in. If your application uses an external identity provider, you should use 'setAuthTokens' method.
  4. The gift code is automatically verified from URL parameters.
  5. Upon successful verification, the recipient can redeem the gift.
  6. A success page is presented and the recipient can click a button to be redirected to the redirect URL after successful payment, or to your page.

Manual redemption via checkout

Recipients can also redeem gifts through the checkout widget by clicking Redeem Gift and entering their gift code manually.

Testing

Test purchasing a gift

Publisher's side:

  1. Create a giftable offer in the Cleeng dashboard.
  2. Define a checkout URL in the dashboard. This URL will be sent to a recipient on a delivery date. This will be the URL to which a recipient will be redirected to redeem their gift.

Customer's (gifter's) side:

  1. Display the checkout for the created giftable offer.
  2. Check if Purchase as a gift option is available.
  3. Complete the required information with test data and purchase the offer as gift.
  4. Go to the customer’s (gifter’s) “Transactions list” and check if the transaction is in the list.

Test redeeming a gift (recipient)

For email redemption flow:

  1. Follow the link in the email.
  2. The Redeem your gift screen will appear.
  3. Redeem the gift.
  4. The gift subscription will appear on the account of the user who has redeemed the gift code for it (recipient).
  5. The recipient will have an active subscription on their account, but they won't have any transaction record.

For manual redemption flow:

  1. Click the "Redeem Gift" in the checkout widget.
  2. Enter the gift code manually.
  3. Redeem the gift.
  4. The gift subscription will appear on the account of the user who has redeemed the gift code for it (recipient).
  5. The recipient will have an active subscription on their account, but they won't have any transaction record.

Updated about 3 hours ago