# Offer fulfillments

> For the complete machine-readable documentation index, see [llms.txt](https://apidocs.chargebee.com/llms.txt).


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"
}
```

## Offer fulfillments attributes

## Input Parameters

- `id` (required, string, max chars=50)
  ID of the fulfillment that was created.

- `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 was selected by the user.

- `processing_type` (required, 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 enum values:
    - `billing_update`
      The offer fulfillment is processed by Chargebee
    - `checkout`
      The offer fulfillment is processed using Chargebee hosted checkout
    - `url_redirect`
      The offer fulfillment is processed by your system
    - `webhook`
      Chargebee triggers webhook and fulfillment is processed by your system
    - `email`
      Chargebee sends an email as configured in the Growth application and the fulfillment is processed by your system

- `status` (required, enumerated string)
  Current status of the offer fulfillment process.
  Possible enum values:
    - `in_progress`
      The offer fulfillment is underway (not yet completed).
    - `completed`
      The 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.
    - `failed`
      The offer fulfillment failed. The `error object` field will be present to provide more details in this case.

- `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` (required, 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` (optional, error)
  Error details describing the reason for failure (present only if status is failed).
  - `code` (required, enumerated string)
    A Chargebee-defined code that corresponds to the specific error encountered during the fulfillment.
    Possible enum values:
      - `billing_update_failed`
        Returned when Chargebee is unable to fulfill the offer while updating the Chargebee billing subscription.
      - `checkout_abandoned`
        Returned when the checkout process was abandoned by the user.
      - `external_fulfillment_failed`
        Returned when the fulfillment is marked as failed by the your system, particularly in cases involving URL redirects, webhooks, and email processing types.
      - `internal_error`
        Returned when a system error occurred during fulfillment via checkout or billing updates.
      - `fulfillment_expired`
        Returned when the fulfillment has been in progress for more than 7 days, resulting in the system automatically marking it as failed.
  - `message` (required, string, max chars=200)
    A descriptive message about the error. This is intended for your consumption and should not be displayed directly to end customers.