Settings
API Version
Product Catalog
Library

Offer fulfillments

Offer fulfillment allows you to initiate, update, and retrieve the lifecycle of an offer fulfillment, after a personalized offer has been accepted. Whether the personalized offer triggers a direct billing change, a hosted checkout flow, or a redirect-based workflow, these APIs track acceptance, execution status, and completion, providing a consistent interface for fulfillment tracking and notifications.


Features of this object:
  • Records fulfillment IDs for tracking and reference.
  • Captures status (in_progress, completed, failed).
  • Stores redirect/checkout URLs as needed.
  • Contains timestamps for creation, completion, or failure.
  • Includes error codes and messages for failure analysis.

Sample offer fulfillment [ JSON ]

{ "personalized_offer_id": "a52ge40b", "option_id": "b3b4741d", "processing_type": "checkout", "status": "in_progress" }

API Index URL GET

https://{site}.grow.chargebee.com/api/v2/offer_fulfillments

Model Class

 

      Offer fulfillment attributes
      
 
id
 

      string, max chars=50
 ID of the fulfillment that was created. 
 
 
personalized_offer_id
 

      string, max chars=50
 ID of the personalized offer that was accepted. 
 
 
option_id
 

      string, max chars=50
 ID of the offer option that was selected by the user. 
 
 
processing_type
 

      enumerated string
 The processing mode of the option. This indicates how the offer option is fulfilled: e.g., a direct billing change, a checkout flow, or a redirect to a URL. 
 
Possible values are
 
 
billing_updateThe offer fulfillment is processed by ChargebeecheckoutThe offer fulfillment is processed using Chargebee hosted checkouturl_redirectThe offer fulfillment is processed by merchant’s systemwebhookChargebee triggers webhook and fulfillment is processed by merchant’s system
 
 Show all values[+]
 
status
 

      enumerated string
 Current status of the offer fulfillment process. 
 
Possible values are
 
 
in_progressThe offer fulfillment is underway (not yet completed).completedThe offer was successfully applied . For URL redirects, this might be returned immediately if the action is completed, potentially along with a redirect_url if the user should be navigated to a specific page.failedThe offer fulfillment failed. The error object field will be present to provide more details in this case.
 
 Show all values[+]
 
redirect_url
 

      optional, string, max chars=250
 A URL to which the user should be redirected. Returned only if the offer’s processing type is billing_update or url_redirect 
 
 
failed_at
 

      optional, timestamp(UTC) in seconds
 Timestamp when the fulfillment failed (present only when status = failed). 
 
 
created_at
 

      timestamp(UTC) in seconds
 Timestamp when the fulfillment record was created. 
 
 
completed_at
 

      optional, timestamp(UTC) in seconds
 Timestamp when the fulfillment succeeded (present only when status = completed). 
 
 
 

      error
 Show attributes [+]
 
 optional, error
 Error details describing the reason for failure (present only if status is failed).
 
 
 
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
 ID of the fulfillment that was created. 
 
personalized_offer_id personalized_offer_id
 

          string, max chars=50
 ID of the personalized offer that was accepted. 
 
option_id option_id
 

          string, max chars=50
 ID of the offer option that was selected by the user. 
 
processing_type processing_type
 

          enumerated string
 The processing mode of the option. This indicates how the offer option is fulfilled: e.g., a direct billing change, a checkout flow, or a redirect to a URL. 
 
Possible values are
 
 
billing_updateThe offer fulfillment is processed by ChargebeecheckoutThe offer fulfillment is processed using Chargebee hosted checkouturl_redirectThe offer fulfillment is processed by merchant’s systemwebhookChargebee triggers webhook and fulfillment is processed by merchant’s system
 
 Show all values[+]
status status
 

          enumerated string
 Current status of the offer fulfillment process. 
 
Possible values are
 
 
in_progressThe offer fulfillment is underway (not yet completed).completedThe offer was successfully applied . For URL redirects, this might be returned immediately if the action is completed, potentially along with a redirect_url if the user should be navigated to a specific page.failedThe offer fulfillment failed. The error object field will be present to provide more details in this case.
 
 Show all values[+]
redirect_url redirect_url
 

          optional, string, max chars=250
 A URL to which the user should be redirected. Returned only if the offer’s processing type is billing_update or url_redirect 
 
failed_at failed_at
 

          optional, timestamp(UTC) in seconds
 Timestamp when the fulfillment failed (present only when status = failed). 
 
created_at created_at
 

          timestamp(UTC) in seconds
 Timestamp when the fulfillment record was created. 
 
completed_at completed_at
 

          optional, timestamp(UTC) in seconds
 Timestamp when the fulfillment succeeded (present only when status = completed). 
 
error 
 

          optional, error
 Error details describing the reason for failure (present only if status is failed). 
 
 
 
Consent Fields for Offer fulfillment
 
 
Custom Fields for Offer fulfillment
 
  

      Create an offer fulfillment
      
  
 
This API notifies that a user has accepted an offer, logs an accepted event immediately for reporting, and triggers a backend processing depending on the offer’s processing_type. 
You can call this API when a user accepts an offer (e.g., the user clicked Accept Offer or a similar confirmation).
 
 This API will record an accepted event as soon as the API is called and initiate the appropriate fulfillment mechanism according to processing_type:
 
  • billing_update: Initiates subscription or billing record updates (e.g., applying a discount or changing a plan) asynchronously.
    •  
  • checkout: Returns a hosted_page object in the response, which contains a URL to render the hosted checkout flow.
    •  
  • url_redirect: Returns a redirect_url. You are responsible for managing fulfillment on your end and must call the Update Offer Fulfillment API to report either completion or failure.
    •  
  • webhook: Sends a webhook, and you must also manage fulfillment on your end. Be sure to call the Update Offer Fulfillment API to report completion or failure.
    •  
  • email: Sends an email containing the offer details as configured. You are responsible for handling fulfillment on your side and must call the Update Offer Fulfillment API to report completion or failure.
 
You can poll the Retrieve Offer Fulfillment endpoint for final status on billing_update and checkout flows.
 
Upon actual fulfillment completion, the system logs a fulfilled event and sends notifications (webhook, Slack, email, Segment) as configured.
  
Notes
 
 

        Sample Request
      
 

  Try in API Explorer

 
 
curl  https://{site}.grow.chargebee.com/api/v2/offer_fulfillments \
     -u {site_api_key}:\
     --header 'Content-Type: application/json;charset=UTF-8' \
     --data '{
     &quot;personalized_offer_id&quot;: &quot;6Y2g7VklOw_904e543f-39da-451c-9a2c-4583284367e8&quot;,
     &quot;option_id&quot;: &quot;912aaab5-1336-4db2-9dba-18a452ba939c_904e543f-39da-451c-9a2c-4583284367e8&quot;
}'
 

      copy
      
Click to Copy
 
 
202:
 
Accepted
 
STATUS
 

    Sample Response [ JSON ]
 
Show more...
 
{
    "offer_fulfillment": {
        "personalized_offer_id": "a52ge40b",
        "option_id": "b3b4741d",
        "processing_type": "checkout",
        "status": "in_progress"
    },
    "hosted_page": {
        "created_at": 1517464663,
        "embed": false,
        "expires_at": 1517468263,
        "id": "__one_time_checkout___test__cdqM9MLUubELMycut0Cr9sHq8gOTKEZSdcu",
        "resource_version": 1517444863979,
        "state": "created",
        "type": "checkout_one_time",
        "updated_at": 1517444863,
        "url": "https://yourapp.chargebee.com/pages/v3/__one_time_checkout___test__cdqM9MLUubELMycut0Cr9sHq8gOTKEZSdcu/",
        "object": "hosted_page"
    }
}
 

      URL Format
      POST
 

      https://{site}.grow.chargebee.com/api/v2/offer_fulfillments
    
 
Method
 
 
Input Parameters
 
  
 
personalized_offer_id[]
 

      required, string, max chars=50 
 ID of the personalized offer that was accepted. 
 
option_id[]
 

      required, string, max chars=50 
 ID of the Offer Option that the user accepted. 
 
 
    
 
Returns
 
offer_fulfillment  offer_fulfillment
 

      always returned 
 Resource object representing offer_fulfillment
hosted_page  hosted_page
 
 optional
 Resource object representing hosted_page
 
Sample admin console URL
 

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

      Retrieve an offer fulfillment
      
  
 
This API is used to retrieve the fulfillment record. This is typically used to check the latest status of an asynchronous offer fulfillment. You can use this after creating an offer fulfillment (billing update or checkout).
  
Notes
 
 

        Sample Request
      
 

  Try in API Explorer

 
 
curl  https://{site}.grow.chargebee.com/api/v2/offer_fulfillments/9ad57ad8-c22c-451b-b9de-780e7e7d987f \
     -u {site_api_key}:\
     --header 'Content-Type: application/json;charset=UTF-8' \
     --data '{}'
 

      copy
      
Click to Copy
 
 
200:
 
OK
 
STATUS
 

    Sample Response [ JSON ]
 
Show more...
 
{
    "offer_fulfillment": {
        "id": "9ad57ad8-c22c-451b-b9de-780e7e7d987f",
        "personalized_offer_id": "6Y2g7VklOw_904e543f-39da-451c-9a2c-4583284367e8",
        "option_id": "912aaab5-1336-4db2-9dba-18a452ba939c_904e543f-39da-451c-9a2c-4583284367e8",
        "processing_type": "url_redirect",
        "status": "in_progress",
        "redirect_url": "https://mysecurecheckoutflow.com/a52ge40b"
    }
}
 

      URL Format
      GET
 

      https://{site}.grow.chargebee.com/api/v2/offer_fulfillments/{offer-fulfillment-id}
    
 
Method
 
  
   
 
    
 
Returns
 
offer_fulfillment  offer_fulfillment
 

      always returned 
 Resource object representing offer_fulfillment
 
Sample admin console URL
 

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

      Update an offer fulfillment
      
  
 
This API is used to update the status of offer fulfillment for the processing types url_redirect, webhook and email as Chargebee cannot automatically fulfill these offers. 
 If status = failed, you must include a failure_reason to explain why the fulfillment did not succeed. The system logs a fulfilled event when status = completed or a failed event when status = failed.
 Note: If the offer fulfillment is not marked as complted or failed within 7 days, Chargebee will mark the offer fulfillment as failed with the error code as external_fulfillment_failed.
  
Notes
 
 

        Sample Request
      
 

  Try in API Explorer

 
 
curl  https://{site}.grow.chargebee.com/api/v2/offer_fulfillments/9ad57ad8-c22c-451b-b9de-780e7e7d987f \
     -u {site_api_key}:\
     --header 'Content-Type: application/json;charset=UTF-8' \
     --data '{
     &quot;status&quot;: &quot;completed&quot;
}'
 

      copy
      
Click to Copy
 
 
200:
 
OK
 
STATUS
 

    Sample Response [ JSON ]
 
Show more...
 
{
    "offer_fulfillment": {
        "personalized_offer_id": "a52ge40b",
        "option_id": "b3b4741d",
        "processing_type": "url_redirect",
        "status": "completed",
        "redirect_url": "https://mysecurecheckoutflow.com/a52ge40b"
    }
}
 

      URL Format
      POST
 

      https://{site}.grow.chargebee.com/api/v2/offer_fulfillments/{offer-fulfillment-id}
    
 
Method
 
 
Input Parameters
 
  
 
id[]
 

      required, string, max chars=50 
 ID of the fulfillment that is being updated. 
 
status[]
 

      required, enumerated string 
 Final state of the fulfillment. 
Possible values are
 
 
completedPass this if the fulfillment is completed.failedPass this if the fulfillment is failed.
 
 Show all values[+]
 
failure_reason[]
 

      optional, string, max chars=100 
 Explanation for failure; required when status = failed. 
 
 
    
 
Returns
 
offer_fulfillment  offer_fulfillment
 

      always returned 
 Resource object representing offer_fulfillment
 
Sample admin console URL
 

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