ChargebeeAPI
Using AI coding agents like Claude Code or Cursor? Try the official Chargebee Agent Skills to speed up your development.Try now

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.

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

Sample Request

URL Format

POST https://[site].grow.chargebee.com/api/v2/personalized_offers

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
optional, string, max chars=50

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

JSON object of custom attributes (key-value pairs) used for offer targeting or content. Configure custom attributes in the dashboard.

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

Returns

personalized_offersalways returned
Resource object representing personalized_offer
brandBrand object
Resource object representing brand
expires_atrequired, 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.