API Tutorials
WE'RE HIRING!HELP CENTERINTEGRATIONSSTATUS PAGESIGN UP

Gift Subscriptions Setup via API

This guide decribes implementation of gift subscriptions with MediaStore SDK API.

Suggest Edits

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 a gifter, a recipient, and a gift.

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.

Gifting process entails:

Follow the guide below to implement gift subscriptions with MediaStore SDK API.

Prerequisites

  1. Enable selling an offer as a gift using the Cleeng dashboard during the offer creation/edition process.

  2. Set a checkout URL in the Cleeng dashboard - this is where a recipient will be redirected to redeem their gift.

    On Cleeng’s side, a parameter ?giftCode=XXXX-XXXX will be added to this URL, and it will be sent to a recipient in an email on a delivery date.

    So the full link in an email can look like that: https://example.company.com/my-account/gift/redeem?giftCode=XXXX-XXXX where XXXX-XXXX will be a real gift code.

    This will be the URL to which a recipient will be redirected to redeem their gift.

    It is recommended to react to this parameter on this page, and prefill input with this gift code as it is done in MediaStore SDK components (see the example).

    It can be achieved with code similar to this:

    const urlParams = new URLSearchParams(window.location.search);
const giftCodeParam = urlParams.get('giftCode');

and then input has to be filled with `giftCodeParam`

See more about enabling selling an offer as a gift

Purchase Gift Offer

In order to purchase an offer as a gift, you will need to implement the following steps:

Step 1: Fetch offer details

Fetch the details of an offer to check if a given offer is purchasable as a gift.
You can do this with the [v2] Fetch offer details (GET /v2/offers/{offerId}) endpoint.

Note: An offer is purchasable as a gift if the appropriate settings have been made in the dashboard.

Step 2: Update order

Update an order with the buyAsAGift flag and deliveryDetails object. You can do this with the following endpoint:

“buyAsAGift”: true, 
“deliveryDetails”: { 
  “recipientEmail”: “[email protected]”, 
  “deliveryDate”: 1691193600, 
  “personalNote”: “Happy Birthday!” 
}

Step 3: Process payment

Process the payment using the regular process.

Once the payment is successfully processed the gift will be scheduled for delivery by Cleeng platform accordingly.

Edit Purchased Gift

Purchased gifts can be updated. It is recommended that they are not edited later than on the last day before the day of delivery.

Example: if today is 22nd August 2023 and the original delivery date for the gift you purchased is 23rd August 2023, 22nd August 2023 should be the last day when you can edit it.

In order to edit a purchased gift, you will need to implement the following steps:

Step 1: Check if offer is a gift

Call Fetch customer transactions (GET /customers/{customerId}/transactions) endpoint to check if a purchased offer is a gift and to get its giftId.

The Fetch customer transactions endpoint has two new fields:

  • targetType - with possible values: giftId or subscriptionId
  • targetId - the identifier (e.g. 205196449) that will be later used as giftId

If targetType = subscriptionId, it is not a gift and edition is not possible.
If targetType = giftId, then it is a gift and the returned targetID is the ID of this gift that you can use to proceed.

Step 2: Get gift details

Use the giftId returned in Step 1 and call the Get a gift endpoint (GET /gifts/{giftId}) to fetch gift delivery details.

Step 3: Update gift

Use the Update a gift (PATCH /gifts/{giftId}) endpoint to update the gift (delivery date, email address, personal note).

Note:

If, for example, you want to change only the delivery date, you still need to provide the current personal note and recipient email.

Once the changes are confirmed the gift will be scheduled for delivery by Cleeng platform accordingly.

Redeem Gift

In order to redeem a gift, you will need to implement following steps:

Step 1: Verify the gift code

Call the Verify a gift (GET /gifts/verification/{code}) endpoint to verify if the gift code provided by the user is valid.
In the response, Cleeng will return the information about the code validity.

  • For redeemable gift codes, there will be information what will happen when the code is redeemed, e.g. a new subscription will be created or an existing subscription will be extended.
  • For not redeemable gift codes, reasons for redeem refusal will be provided.

Step 2: Redeem gift

After successful verification the gift can be redeemed.

Call the Redeem a gift (POST /gifts/redeem/{code}) endpoint to redeem a gift. Cleeng platform will create or update the subscription accordingly.

📘

Good to know

If a recipient has a payment method added to their account, they will be charged on a recurring basis after the gift expires.

You might want to add information to the “Thank you” note after redeeming a gift that to retain access after a gift expires, the recipient will need to add a payment method to their account.

Test your integration

Test purchasing a gift

Broadcaster's side:

  1. Create a giftable offer in the dashboard.
  2. Define a checkout URL in the dashboard. It 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.
  3. Use [v2] Fetch offer details to check if the offer is giftable.

Customer's (gifter's) side:

  1. Purchase a giftable offer:
    • Create/update order for this offer (use Create an order / Update an order) , so that buyAsAGift=true and deliveryDetails are filled.
    • You can set deliveryDate in the past for testing - so that it can be sent as soon as possible (at most 1 hour).
  2. Call Fetch customer transactions to check targetId - the ID of the gift.
  3. Call the Get a gift endpoint with the obtained targetId (the ID of the gift).
  4. Update gift delivery details eith the Update a gift endpoint.

Test redeeming a gift

Customer's (recipient's) side:

  1. Check the email that was provided in the delivery details, and get the gift code or follow the link.
  2. Go through registration or login process.
  3. Verify the gift with the gift code (use the Verify a gift endpoint).
  4. Redeem the gift with the gift code (use the Redem a gift endpoint).
  5. The gift subscription will appear on the account of the user who has redeemed the gift code for it (the recipient).
  6. The recipient will have an active subscription on their account, but they won't have any transaction record.

Updated 5 months ago