Present Checkout-based offers in-product using Chargebee Growth's Offers APIs

Overview

At key moments in the subscriber lifecycle—such as when a trial is nearing its end—users often have high purchase intent. In these moments, your application can present a personalized Checkout-based offer in-product using Chargebee Growth's Offers APIs to drive conversion.

This tutorial walks through how to integrate your application with Chargebee Growth's Offers APIs to present timely in-product offers and convert trial users to paid subscribers—using an example where a customer's trial is ending soon (for example, 7 days from now). Accepted offers are fulfilled by Chargebee through Checkout.

When a subscriber logs in, your application requests a personalized acquisition offer from Chargebee (for example, "Upgrade to Pro & Save 10%" when the trial is ending within 7 days). Your application then renders the offer to the subscriber. When the user accepts the offer, your application redirects them to a Chargebee-hosted Checkout page. Chargebee then handles payment collection, discount application, trial conversion, and subscription activation.

Architecture overview

The flow splits responsibilities between your backend and Chargebee as follows.

Your application:

• Requests offers from Chargebee when the customer signs in
• Renders the upgrade prompt using the offer content
• Notifies offer engagement events to Chargebee
• Creates an offer fulfillment on acceptance
• Redirects the user to Chargebee Checkout

Chargebee:

• Evaluates offer eligibility
• Selects the appropriate offer
• Records offer engagement events
• Fulfills the offer via Checkout (payment collection, discount application, trial conversion)

A typical flow:

1. When a user signs in, fetch a personalized offer from Chargebee, providing the customer and subscription identifiers.
2. If an offer is returned, show an upgrade prompt (banner, modal, or inline) using the offer content.
3. For engagement tracking, notify Chargebee when the offer is viewed or dismissed. Stop here if the user dismisses the offer.
4. When the user accepts the offer, create an offer fulfillment request at Chargebee.
5. Redirect the user to the Checkout URL returned by Chargebee.
6. Chargebee collects payment from the customer using Checkout and completes trial conversion.

Before you start

For this tutorial to work, you need the following setup:

Set up your development environment

1. Obtain a full-access API key from Chargebee Billing.
2. Install the Chargebee client SDK for your server-side stack.

Set up Chargebee Billing and Growth

Users with access to Chargebee Growth must complete these steps.

1. Have Chargebee Growth enabled and connected to your Chargebee Billing site.
2. Ensure that the required configuration has been completed in Chargebee so the APIs return offers at runtime.

Implementation steps

Follow these steps to implement the trial-to-paid conversion flow using Chargebee Growth's Offers APIs and Checkout.

Step 1: Fetch the personalized offer at sign-in

When a user signs in, call the Personalized Offers API to determine whether they're eligible for any offers.

curl  https://YOUR_CHARGEBEE_SUBDOMAIN.grow.chargebee.com/api/v2/personalized_offers \
     -u YOUR_CHARGEBEE_API_KEY:\
     --header 'Content-Type: application/json;charset=UTF-8' \
     --data '{
     "subscription_id": "AzqapfV9oMu0c1a1s",
     "customer_id": "AzqapfV9oMtif1a1m"
}'

If the subscriber matches one or more configured plays in Growth, Chargebee returns the offer corresponding to the play of highest priority. Example response:

{
  "personalized_offers": [
    {
      "id": "vdyjO2qlLD_715653d4",
      "offer_id": "vdyjO2qlLD",
      "content": {
        "title": "<div class=\"slate-p\">Upgrade to Pro & Save 10%</div>",
        "description": "<div class=\"slate-p\">Your trial is ending soon. Upgrade now and get 10% off the Pro plan.</div>"
      },
      "options": [
        {
          "id": "6cd5280e",
          "label": "Upgrade to Pro",
          "processing_type": "checkout"
        }
      ]
    }
  ],
  "expires_at": 1732790400
}

The response includes a processing_type of checkout, which means the offer is configured for fulfillment via Chargebee Checkout.

When no offer is returned

If the response has an empty personalized_offers list, do not show an upgrade prompt. An empty response means the user isn't eligible (for example, they don't match any active plays, or the offer was already accepted or dismissed).

Step 2: Render the upgrade prompt

If a personalized offer is returned, use the offer content to show an upgrade prompt inside your application. Depending on how prominent you want the message, you can use one of these UI patterns:

• A banner at the top of the dashboard
• A modal
• An inline callout near the trial status or usage indicators

Use the offer content as follows to render the upgrade prompt:

• Title → content.title
• Description → content.description
• CTA label → options[0].label

This ensures that the offer is displayed to the user dynamically based on the current configuration in Chargebee Growth.

Here are some examples of how to render the upgrade prompt:

Step 3: Track offer interactions

To measure engagement in Growth, record the following offer events:

• Record a viewed event each time the offer is displayed.
• Record a dismissed event when the user closes or ignores the offer.

Send these events from your backend after the corresponding UI action using the Offer Events API with the personalized_offer_id from the Personalized Offers response:

curl  https://YOUR_CHARGEBEE_SUBDOMAIN.grow.chargebee.com/api/v2/offer_events \
     -u YOUR_CHARGEBEE_API_KEY:\
     --header 'Content-Type: application/json;charset=UTF-8' \
     --data '{
     "type": "viewed",
     "personalized_offer_id": "vdyjO2qlLD_715653d4"
}'

These events are for reporting; the dismissed event also affects offer cooldown. They do not affect fulfillment or Checkout behavior.

Step 4: Create offer fulfillment on CTA click

When the user clicks the acceptance CTA, call your backend to create an offer fulfillment to get the URL for a Chargebee-hosted checkout page. Use the Offer Fulfillments API with the personalized_offer_id and option_id from the offer returned in Step 1.

curl  https://YOUR_CHARGEBEE_SUBDOMAIN.grow.chargebee.com/api/v2/offer_fulfillments \
     -u YOUR_CHARGEBEE_API_KEY:\
     --header 'Content-Type: application/json;charset=UTF-8' \
     --data '{
     "personalized_offer_id": "vdyjO2qlLD_715653d4",
     "option_id": "6cd5280e"
}'

The API returns a response like the following:

{
  "offer_fulfillment": {
    "id": "507c340b",
    "personalized_offer_id": "vdyjO2qlLD_715653d4",
    "option_id": "6cd5280e",
    "processing_type": "checkout",
    "status": "in_progress"
  },
  "hosted_page": {
    "id": "MLUubELMycut0Cr9sHq8gOTKEZSdcu",
    "url": "https://YOUR_CHARGEBEE_SUBDOMAIN.chargebee.com/pages/v4/p8QLtz5FfIwcdHyedehgQ9LmHpo5rVN5u/?signature=S8lqcuH12GnhzrE0i9XcuOicdKppftrKvx5",
    "state": "created",
    "type": "checkout_existing",
    "expires_at": 1517468263
  }
}

Step 5: Redirect the user to Checkout

Immediately redirect the user to the Checkout URL (hosted_page.url) returned in the fulfillment response in the previous step.

Chargebee then does the following:

1. Render the Checkout page that applies the offer discount, applies the new plan, and collects payment.
2. Activate the subscription with the new plan.
3. Update the fulfillment status to completed.
4. Redirect the customer to the configured success URL.

(Optional) Step 6: Poll fulfillment status

You can optionally poll the fulfillment status for asynchronous tasks such as syncing conversion events to your analytics system. Use the Retrieve an Offer Fulfillment API to do this.

curl  https://YOUR_CHARGEBEE_SUBDOMAIN.grow.chargebee.com/api/v2/offer_fulfillments/507c340b \
     -u YOUR_CHARGEBEE_API_KEY:

As seen in the response below, when checkout has completed successfully and the offer has been applied, offer_fulfillment.status becomes completed.

{
  "offer_fulfillment": {
    "id": "507c340b",
    "personalized_offer_id": "vdyjO2qlLD_715653d4",
    "option_id": "6cd5280e",
    "processing_type": "checkout",
    "status": "completed"
  }
}

Error handling

Fulfillment errors

When you poll the fulfillment status as described in Step 6, use these guidelines:

• If offer_fulfillment.status is in_progress, wait before polling again.
• If offer_fulfillment.status is failed, check the offer_fulfillment.error.code to determine the reason.

Multiple CTA clicks by the same user

As a best practice, disable the offer acceptance CTA button in the UI immediately after it's clicked. If there's a duplicate click and you request a new offer fulfillment, the API returns an error because multiple fulfillments aren't allowed for the same personalized_offer_id.

Handle the error as follows:

1. Fetch the offer_fulfillment.id saved earlier in the Step 4.
2. Retrieve the fulfillment status using the offer_fulfillment.id.
3. Check for fulfillment errors as described in the last section.

Same offer accepted by different users

Calling the Offer Fulfillments API succeeds only once for the same base offer_id when the offer originates from the same Play.

If you're a B2B business with multiple users per subscription, the same offer from the same Play can be seen by different signed-in users at the same time. In this case, after the first user accepts the offer, the Offer Fulfillments API returns the following error for subsequent users:

Fulfillment is already in progress/completed. Retrieve the fulfillment to know the latest status.

Show a message to the user such as, "This offer has already been accepted."

Summary

In this tutorial, you learned how to:

• Fetch a personalized Checkout offer at user sign-in from Chargebee.
• Use the offer content to render an upgrade prompt in your application.
• Record offer events (viewed and dismissed) for reporting.
• Create an offer fulfillment when the user accepts, then redirect to the returned checkout URL.
• Optionally retrieve fulfillment status for analytics.
• Handle fulfillment errors, multiple CTA clicks by the same user, and the same offer accepted by different users.

Appendix