Settings
API Version
Product Catalog
Library

Personalized offers

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

Model Class

 

      Personalized offer attributes
      
 
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.
 
 
  
id id
 

          string, max chars=50
 A unique and immutable identifier for the personalized offer. 
 
offer_id 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 
 

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

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

      List personalized offers
      
  
 
  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: Although the response is modeled as a list, the API currently returns at most one personalized offer (the best-matched offer for the user). If no offers are available, the list will be empty.
    • 

  

        Sample Request
      
 

  Try in API Explorer

 
 
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:
 
OK
 
STATUS
 

    Sample Response [ JSON ]
 
Show more...
 
{
    "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
    
 
Method
 
 
Input Parameters
 
  
 
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). 
 
 
 
 
 
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 
  
   
 
Returns
 
personalized_offers  personalized_offers
 

      always returned 
 Resource object representing personalized_offers
brand  brand
 
 optional
 Resource object representing brand
expires_at  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 admin console URL
 

      https://{site}.chargebee.com/admin-console/personalized_offers/123x