Getting started with Chargebee Growth's Offers APIs

Overview

Chargebee Growth's Offers APIs allow your application to programmatically determine which offer (if any) should be shown to a subscriber at a given moment, track how the subscriber interacts with that offer, and apply or record the outcome when it is accepted.

Chargebee Growth acts as a decisioning and fulfillment layer, while you retain full control over offer delivery and presentation in your own experiences—such as in-product prompts, lifecycle emails, cancellation journeys, or other custom workflows.

When an offer is accepted, fulfillment is handled according to the offer's processing type. Depending on configuration, Chargebee can apply subscription changes automatically, or your application can run its own provisioning logic and update fulfillment status explicitly.

This guide is a developer-focused introduction to Chargebee Growth's Offers APIs. It explains the core concepts, APIs, and integration patterns you need to understand before implementing offer-driven flows such as trial conversion, usage-based upgrades, cancellation saves, or feature unlocks in your application.

Rather than walking through a single end-to-end use case, this guide establishes the mental model and core building blocks you'll reuse across Offer API integrations.

Architecture overview

Offers APIs help you decide which offer to show, track how users interact with it, and trigger or record fulfillment when an offer is accepted. You control how offers are delivered and presented to your users. Think of Offers APIs as the system that answers: "What's the best offer for this user right now, and what happens when they accept it?"

Typical flow:

1. Fetch a personalized offer (Personalized Offers API).
2. Render the offer in your chosen channel (in-product, email, instant messaging, etc.).
3. Record offer interaction events (Offer Events API).
4. Create an offer fulfillment on acceptance (Offer Fulfillments API).
5. Complete fulfillment or let Chargebee handle it (based on the processing type of the offer).

Understanding the core concepts and APIs

This section introduces the core concepts and APIs in Chargebee Growth Offers to help you establish a mental model of how they work together.

Plays

In Chargebee Growth, Plays define how and when personalized offers are evaluated and returned.

A Play encapsulates the targeting logic that determines whether a subscriber should see an offer in a given context. When you call the Personalized Offers API, Chargebee Growth evaluates all active Plays and returns the best eligible offer (if any).

Each play is composed of the following components:

• Audience — Defines who is eligible (for example, trial users, inactive users, users missing an entitlement).
• Trigger — Defines when the offer is eligible (for example, on login, on page view).
• Offer — Defines what is presented (discount, upgrade, feature unlock).

For the Offers APIs to return an offer, at least one relevant Play must be active and associated with an Offer.

Audience conditions are defined using standard and/or custom fields in Chargebee Growth. If your configured Plays rely on data from your application, those fields must be created as custom fields and mapped in Growth before they can be used in API requests. Any values sent for unmapped fields are ignored during eligibility evaluation.

Personalized Offers API

A personalized offer is the result of Chargebee evaluating your request parameters against plays configured in Growth. When matching plays are found, Chargebee Growth returns the offer associated with the highest-priority play. This way, Chargebee returns at most one personalized offer for any given context.

Use this API to fetch a personalized offer for a given context. Some common user actions at which you can fetch an offer are:

• Logs in
• Attempts to access a gated feature
• Visits your pricing page
• Attempts to cancel the service

Alternatively, you can run scheduled jobs to fetch offers for your users at regular intervals.

When an offer is returned, you can deliver it to the user using the channel of your choice: display in-app, send via email, or send via messaging.

When no offer is returned

If no offer is returned, that's a valid outcome and means the user isn't eligible at that moment. An empty response from the Personalized Offers API is common. Typical causes include:

• The customer, subscription, or user details provided don't match any active plays.
• Eligible plays exist but offer cooldown is in effect since the last offer was accepted or dismissed by the user.

Offer Events API

Record offer interactions using the Offer Events API.

• Send a viewed event when the offer is rendered in-app or when the offer is opened in other delivery channels (for example, email or SMS).
• Send a dismissed event when the user dismisses or closes the offer in-app.

These events power Growth reporting and experimentation and influence offer cooldown; they don't directly affect fulfillment.

Offer Fulfillments API

When a user accepts an offer, create an offer fulfillment using the Offer Fulfillments API. Fulfillments track acceptance, processing state, and final outcome. Either you or Chargebee handles fulfillment, depending on the processing_type of the offer option.

• checkout — Chargebee hosts Checkout and completes fulfillment (for example, trial-to-paid and other acquisition offers).
• billing_update — Chargebee applies subscription updates automatically (for example, discounts, addons, and save offers).
• url_redirect — You own the upgrade or provisioning flow and must update fulfillment status explicitly (for example, entitlements, custom billing).

Summary

In this tutorial, you learned how to:

• Understand how audiences, triggers, and plays work together to return offers.
• Describe the role of the Personalized Offers, Offer Events, and Offer Fulfillments APIs.
• Understand the different processing types of offers and how to handle fulfillment.
• Apply the typical flow: fetch offer → render offer → track events → create fulfillment → complete or update fulfillment.

Next steps

Explore the use-case-specific tutorials for Chargebee Growth.