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

Servers

{protocol}://{site}.{environment}:{port}/api/v2
{protocol}://{site}-test.{environment}:{port}/api/v2

Request headers

Name	Type	Required	Description
`chargebee-request-origin-device`	String	No	The device from which the customer has made the request
`Content-Type`	String	Yes	The media type of the request body. Default value: "application/x-www-form-urlencoded"
`chargebee-event-webhook`	String	No	skip only webhooks Valid values: `"all-disabled"`
`chargebee-business-entity-id`	String	No	If the site has multiple business entities, you can use this custom HTTP header to specify the business entity for which Chargebee should perform the operation.
`chargebee-event-actions`	String	No	skip all actions to be done on the events Valid values: `"all-disabled"`
`chargebee-request-origin-user`	String	No	The email address of your customer/user. Use this when the email address has only ASCII characters.
`chargebee-request-origin-ip`	String	No	The IP address of the customer where the request originated
`chargebee-request-origin-user-encoded`	String	No	The Base64-encoded email address of your customer/user. Use this if the email address has UTF-8 characters. When this header is provided, the header chargebee-request-origin-user is ignored.
`chargebee-event-email`	String	No	skip only emails Valid values: `"all-disabled"`

Request body fields

Name	Type	Required	Description
`custom`	Object	No	A JSON object of custom attributes (key-value pairs) that can be used in offer targeting or content (per field mapping configuration).
`customer_id`	String	Yes	The ID of the customer in the billing system (Chargebee customer ID).
`email`	String	No	Customer's email address. Will be ignored if not mapped to any field in the settings.
`last_name`	String	No	Last name of the customer. Will be ignored if not mapped to any field in the settings.
`external_user_id`	String	No	The unique identifier of the user in the your system. This is used to identify the user for whom the offer is being created.
`first_name`	String	No	First name of the customer. Will be ignored if not mapped to any field in the settings.
`roles[]`	Array	No	Roles or user types associated with the end user. (Useful in offer targeting for B2B scenarios with multiple user roles.).
`request_context`	Object	No	A JSON object with standard context attributes (browser, device, locale, etc.) of the end user's session. This can help in offer targeting based on user environment.
`request_context.timezone`	String	No	The user's timezone identifier (e.g., America/New_York). Used for contextual targeting based on time.
`request_context.url`	String	No	The current page URL where the offer is being displayed. Useful for context-sensitive offers.
`request_context.referrer_url`	String	No	The referring page URL, i.e., the previous page that navigated the user to the current one. Can help with attribution analysis.
`request_context.user_agent`	String	No	The user's browser or device user agent string. Helps determine browser and platform details. For example, chrome/7.10
`request_context.locale`	String	No	The user's locale setting (e.g., en-US, fr-FR). Useful for regional offer targeting.
`subscription_id`	String	No	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.

How to start integrating

Add HTTP Task to your workflow definition.
Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
Click Test request to test run your request to the API and see the API's response.