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 in our Help Docs.

Growth Managers define plays such as:

  • Acquire: Incentivize trial users or prospects to subscribe.
  • Expand: Engage at-risk subscribers with targeted winbacks or discounts.
  • 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, contact eap@chargebee.com .


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 GET

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.
 
 
 
Event types
 

      This is a list of the event types we currently support. We will continue
      to add more events moving forward. All events follow a uniform pattern -
      <resource>_<event_name>. The resources that will be
      present in the event content are provided beneath each event type's
      description.
    
 
Note: If consolidated invoicing is enabled, the
      attributes invoice.subscription_id and
      credit_note.subscription_id should not be used
      (as it will not be present if the invoice / credit note has lines from
      multiple subscriptions). Instead to know the related subscriptions,
      their line_items' subscription_id attribute should be referred.
    
 
 
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
      
  
 
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. 
  
Notes
 
 

        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 merchant’s 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