Personalized offers

API Version

Product Catalog

Library

A Personalized Offer represents the best possible offer for a subscriber at a given moment in their lifecycle. It is generated by combining subscriber profile, subscription details, and contextual signals with the plays configured by Growth Managers in the Chargebee Growth dashboard. Learn more about Growth Solutions.

Growth Managers define strategic plays that guide customer engagement. Developers then use the Personalized Offers API to fetch and surface these offers within the subscriber experience; whether in an app, portal, checkout flow, websites or communications like email and SMS. Some common plays include:

Acquire: Incentivize trial users or prospects to subscribe.
Expand: Encourage existing subscribers to purchase higher-value products or add-ons.
Retain: Engage at-risk subscribers with targeted winbacks or discounts.

Note: Growth solutions are currently in Early Access and available only for Chargebee Billing customers at no additional cost during the EAP period. This API is also part of the Early Access Program (EAP). To request access, go to the Chargebee Growth Early Access page in Chargebee Billing.

Features of this object
The Personalized Offers object enables you to:

Fetch context-aware offers generated by the Growth system.
Display offer content (title and description) to subscribers.
Provide subscribers with options they can act on.
Attribute offers to the correct brand (for multi-brand merchants).
Respect time-bound validity with the expires_at attribute.

Sample personalized offer [ JSON ]

{
    "personalized_offers": [
        {
            "id": "a52ge40b",
            "offer_id": "51Ora2PrXz",
            "content": {
                "title": "<div class=\"slate-p\">Need  to take a break?</div>",
                "description": "<div class=\"slate-p\">Instead of canceling why don't you pause your plan? We'll be here when you are ready to get started again.</div>"
            },
            "options": [
                {
                    "id": "af647113-6002-4159-a48a-87f11564963e",
                    "label": "PAUSE MY PLAN",
                    "processing_type": "url_redirect",
                    "redirect_url": "https://mysecurecheckoutflow.com/abcd"
                },
                {
                    "id": "fd63284-6002-4159-a48a-87f11564963e",
                    "label": "CANCEL",
                    "processing_type": "billing_update"
                }
            ]
        }
    ],
    "brand": {
        "id": "1d5QXw39ar",
        "name": "SecureCheck"
    },
    "expires_at": 24134311
}

API Index URL

https://{site}.grow.chargebee.com/api/v2/personalized_offers

id

string, max chars=50
A unique and immutable identifier for the personalized offer.

offer_id

string, max chars=50
ID of the base offer configured. This ID is immutable and always refers to the core offer and its latest published version.

content
Show attributes [+]

required, content
The offer content to display to the user, includes title & description.

options
Show attributes [+]

optional, list of option
List of offer options (choices or call-to-action buttons) in this offer.

Try in API Explorer

This API is used to retrieve a list of personalized offer(s) for a customer based on the context (such as customer or subscription details and end-user attributes). This allows you to retrieve any active offers targeted to the user.

You can pre-call this API as soon as you have the user context at the point of login, or can call this API at any other point in the user journey when an offer is to be shown.

System evaluates eligibility and mapping to the right offer based on:

Customer profile and subscription information.
Device and browsing context.
Custom fields.
Play configurations.

If no eligible offers are found, the API returns an empty list. (No error is thrown in this case; an empty result is a valid response).

Features of this API

The List Personalized Offers endpoint allows you to:

Retrieve context-aware offers targeted to customers or end users.
Leverage multiple signals (profile, subscription, device/browser context, custom fields, and plays).
Call flexibly at login, checkout, renewal, or any point in the user journey.Handle gracefully when no offers are available (returns an empty list, not an error).
Support both B2C (single user per customer) and B2B (multiple end users per customer) scenarios.

Note:

Sample Request

Try in API Explorer

Only for Java

copy full code

Click to Copy

curl  https://{site}.grow.chargebee.com/api/v2/personalized_offers \
     -u {site_api_key}:\
     --header 'Content-Type: application/json;charset=UTF-8' \
     --data '{
     &quot;first_name&quot;: &quot;John&quot;,
     &quot;last_name&quot;: &quot;Doe&quot;,
     &quot;email&quot;: &quot;john.doe@gmail.com&quot;,
     &quot;roles&quot;: [
          &quot;admin&quot;,
          &quot;engineer&quot;
     ],
     &quot;external_user_id&quot;: &quot;abcd&quot;,
     &quot;subscription_id&quot;: &quot;FfV4CXxpR8nAqB&quot;,
     &quot;customer_id&quot;: &quot;cb69c692-afd8-43b1-b737-c49e1f6d5fdb&quot;,
     &quot;custom&quot;: {
          &quot;visit_count&quot;: 3,
          &quot;offer_eligible&quot;: true
     },
     &quot;request_context&quot;: {
          &quot;user_agent&quot;: &quot;Mozilla/5.0&quot;,
          &quot;locale&quot;: &quot;en-US&quot;,
          &quot;timezone&quot;: &quot;America/Denver&quot;,
          &quot;url&quot;: &quot;https://www.chargebee.com/pricing/&quot;,
          &quot;referrer_url&quot;: &quot;https://www.chargebee.com/&quot;
     }
}'

copy

Click to Copy

200:

STATUS

Sample Response [ JSON ]

{
    "personalized_offers": [
        {
            "id": "a52ge40b",
            "offer_id": "51Ora2PrXz",
            "content": {
                "title": "<div class=\"slate-p\">Need  to take a break?</div>",
                "description": "<div class=\"slate-p\">Instead of canceling why don't you pause your plan? We'll be here when you are ready to get started again.</div>"
            },
            "options": [
                {
                    "id": "af647113-6002-4159-a48a-87f11564963e",
                    "label": "PAUSE MY PLAN",
                    "processing_type": "url_redirect",
                    "redirect_url": "https://mysecurecheckoutflow.com/abcd"
                },
                {..}
            ]
        },
        {..}
    ],
    "brand": {
        "id": "1d5QXw39ar",
        "name": "SecureCheck"
    },
    "expires_at": 24134311
}

URL Format POST

https://{site}.grow.chargebee.com/api/v2/personalized_offers

first_name[]

optional, string, max chars=150
First name of the customer. Will be ignored if not mapped to any field in the settings.

last_name[]

optional, string, max chars=150
Last name of the customer. Will be ignored if not mapped to any field in the settings.

email[]

optional, string, max chars=70
Customer's email address. Will be ignored if not mapped to any field in the settings.

roles[[0..n]][0..n]

optional, list of string
Roles or user types associated with the end user. (Useful in offer targeting for B2B scenarios with multiple user roles.).

external_user_id[]

optional, string, max chars=50
The unique identifier of the user in the your system. This is used to identify the user for whom the offer is being created.

subscription_id[]

optional, string, max chars=50
The unique identifier of the subscription for which the offer should be retrieved.
Notes:

Required if multiple brands are configured in your Growth application.
Recommended to always provide.
If omitted and the customer has multiple subscriptions, the system attempts to retrieve the offer associated with one of their subscriptions.

customer_id[]

required, string, max chars=50
The ID of the customer in the billing system (Chargebee customer ID).

custom[]

optional, jsonobject
A JSON object of custom attributes (key-value pairs) that can be used in offer targeting or content (per field mapping configuration).

request_context

Parameters for request_context
pass parameters as request_context[<param name>]

user_agent

optional, string, max chars=255

locale

optional, string, max chars=50

timezone

optional, string, max chars=64

url

optional, string, max chars=250

referrer_url

optional, string, max chars=250

personalized_offers

always returned
Resource object representing personalized_offers

brand

optional
Resource object representing brand

expires_at

required, timestamp(UTC) in seconds
The timestamp until which the offer remains active. After this time, you must retrieve the offer again via the List Personalised Offers API to get the latest.

Sample personalized offer [ JSON ]

API Index URL

Model Class

Personalized offer attributes

Consent Fields for Personalized offer

Custom Fields for Personalized offer

List personalized offers ¶

Notes

Sample Response [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL