# Recorded purchases

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


**Important**

-   Handle the **synchronous** API response first. Record a Purchase can fail immediately (for example, an incorrect `app_id`, a malformed URL or request, or recording a purchase that already belongs to a different customer) before a job is created—treat these as standard API errors (`4xx`). To reassign an existing omnichannel subscription to another customer, use [Move an omnichannel subscription](/docs/api/omnichannel_subscriptions/move-an-omnichannel-subscription) instead of re-recording the purchase.
-   After the call is accepted, purchase validation with Apple or Google is **asynchronous**. Track the job with `status` (`in_process` → `completed`, `failed`, or `ignored`). Omnichannel subscription or one-time order creation happens only after successful async completion.
-   This resource is applicable for Apple App Store and Google Play Store.

The recorded purchase resource represents a background job that syncs in-app purchases made through Apple App Store and Google Play Store with Chargebee. The `[status](/docs/api/recorded_purchases/recorded_purchase-object#status)` (`in_process`, `completed`, `failed`, and `ignored`) attribute represents the current status of the background job.

### Record Apple and Google in-app purchases and retrieve linked omnichannel resources[](#record-apple-and-google-in-app-purchases-and-retrieve-linked-omnichannel-resources)

You can record subscription and one-time-order purchases made on Apple App Store or Google Play Store, then retrieve the resulting omnichannel resources.

To record a purchase and retrieve details, follow these steps:

1.  Use the [Record a Purchase API](/docs/api/recorded_purchases/record-a-purchase) with `app_id`, `customer[id]`, and exactly one store payload:
    
    -   **Apple App Store (preferred)**: `apple_app_store[transaction_id]` for a new subscription, expired re-purchase, or one-time product.
        
    -   **Apple App Store (receipt path)**: `apple_app_store[receipt]` and `apple_app_store[product_id]`.
        
    -   **Google Play Store (preferred)**: `google_play_store[order_id]` for a subscription or one-time order.
        
    -   **Google Play Store (subscription token path)**: `google_play_store[purchase_token]`.
        
    -   **Google Play Store (one-time order token path)**: `google_play_store[purchase_token]` and `google_play_store[product_id]`.
        
2.  The API response includes a `recorded_purchase` object with the `[status](/docs/api/recorded_purchases/recorded_purchase-object#status)` of the job.
    
3.  When recording completes successfully, `status` updates from `in_process` to `completed` and Chargebee sets `omnichannel_transaction_id` plus either:
    
    -   **Subscription**: `linked_omnichannel_subscriptions`, with webhook [`omnichannel_subscription_created`](/docs/api/events/webhook/omnichannel_subscription_created) (or [`omnichannel_subscription_imported`](/docs/api/events/webhook/omnichannel_subscription_imported)).
    -   **One-time order**: `linked_omnichannel_one_time_orders`, with webhook [`omnichannel_one_time_order_created`](/docs/api/events/webhook/omnichannel_one_time_order_created).
4.  In addition to webhooks, retrieve the job by the `recorded_purchase` [id](/docs/api/recorded_purchases/recorded_purchase-object#id) returned when you record the purchase.
    

If `status` is `failed`, review `[error_detail](/docs/api/recorded_purchases/recorded_purchase-object#error_detail)` and see [`record_purchase_failed`](/docs/api/events/webhook/record_purchase_failed).

If `status` is `ignored`, the purchase was already recorded in Chargebee as an omnichannel subscription or one-time order. Chargebee does not create a new linked resource for this job—use the existing omnichannel subscription or one-time order. Linked IDs and `omnichannel_transaction_id` are populated when `status` is `completed`, not for `ignored`.

See also [omnichannel events](/docs/api/omnichannel_events).

## Sample Recorded purchase

```json
{
  "id": "__test__rp_ASDsdfs123ld1",
  "app_id": "__test__aas_sdfwerzx5134",
  "customer_id": "__test__XpbTXGTSRp3gEsD8",
  "source": "apple_app_store",
  "status": "completed",
  "omnichannel_transaction_id": "__test__ot_LKedfs123ld1",
  "linked_omnichannel_subscriptions": [
    {
      "omnichannel_subscription_id": "__test__os_AHsdfs123ld1"
    },
    {..}
  ],
  "created_at": 1517487053,
  "object": "recorded_purchase"
}
```

## Recorded purchases attributes

## Input Parameters

- `id` (required, string, max chars=40)
  A unique ID generated by Chargebee for the recorded purchase job.

- `customer_id` (required, string, max chars=100)
  The `id` of the [customer](/docs/api/customers/customer-object#id) object associated with this purchase. If the `customer_id` is not present in Chargebee when the `[record_a_purchase](/docs/api/recorded_purchases/record-a-purchase)` API request is made, Chargebee automatically creates the customer using the details provided in the request.

- `app_id` (required, string, max chars=100)
  App Identifier in Chargebee. This is the handle created by Chargebee for your app. To get the `app_id`:
  
  -   For **Apple**, follow [these steps](https://www.chargebee.com/docs/billing/2.0/mobile-subscriptions/omnichannel-app-store#create-an-omnichannel-subscription-for-in-app-purchases).
  -   For **Google**, follow [these steps](https://www.chargebee.com/docs/billing/2.0/mobile-subscriptions/omnichannel-play-store#connect-google-app-to-chargebee-to-generate-unique-app-id-and-notifications-url).

- `source` (required, enumerated string)
  The source where the purchase is originally made and managed.
  Possible enum values:
    - `apple_app_store`
      The purchase originated from the Apple App Store.
    - `google_play_store`
      The purchase originated from the Google Play Store.

- `status` (required, enumerated string)
  Current status of the recorded purchase operation.
  Possible enum values:
    - `in_process`
      The purchase recording job is in progress. You do **not** yet receive `omnichannel_transaction_id` or linked subscription / one-time-order objects.
    - `completed`
      The purchase recording job completed successfully. You receive `omnichannel_transaction_id` and either `linked_omnichannel_subscriptions` (subscription purchase) or `linked_omnichannel_one_time_orders` (one-time order purchase).
    - `failed`
      The purchase recording job failed. You do **not** receive `omnichannel_transaction_id` or linked subscription / one-time-order objects. Check the `[error_detail](/docs/api/recorded_purchases/recorded_purchase-object#error_detail)` attribute for the failure reason. Chargebee may also emit [`record_purchase_failed`](/docs/api/events/webhook/record_purchase_failed).
    - `ignored`
      Terminal status when the purchase was already recorded in Chargebee as an omnichannel subscription or one-time order (same store purchase / customer association). Chargebee does **not** create a new linked resource for this job. Use the existing omnichannel subscription or one-time order in Chargebee rather than treating this job as a new successful recording. `linked_omnichannel_subscriptions` / `linked_omnichannel_one_time_orders` and `omnichannel_transaction_id` are returned when `status` is `completed`, not for `ignored`.

- `omnichannel_transaction_id` (optional, string, max chars=100)
  The `id` of the [omnichannel transaction](/docs/api/omnichannel_transactions/omnichannel_transaction-object#id) object associated with the purchase. Present when `status` is `completed`.

- `created_at` (required, timestamp(UTC) in seconds)
  Timestamp when the `recorded_purchase` resource was created in Chargebee.

- `resource_version` (optional, long)
  Version number of this resource. The `resource_version` is updated with a new timestamp in milliseconds for every change made to the resource.

- `linked_omnichannel_subscriptions` (optional, list of linked_omnichannel_subscription)
  The list of omnichannel subscriptions created for this purchase. Applicable when the recorded purchase is a subscription. Present when `status` is `completed`.
  - `omnichannel_subscription_id` (optional, string, max chars=100)
    The `id` of the [omnichannel subscription](/docs/api/omnichannel_subscriptions/omnichannel_subscription-object#id) object associated with this purchase.

- `linked_omnichannel_one_time_orders` (optional, list of linked_omnichannel_one_time_order)
  The list of omnichannel one-time orders created for this purchase. Applicable when the recorded purchase is a one-time order. Present when `status` is `completed`.
  - `omnichannel_one_time_order_id` (optional, string, max chars=100)
    The `id` of the [omnichannel one-time order](/docs/api/omnichannel_one_time_orders/omnichannel_one_time_order-object#id) object associated with this purchase.

- `error_detail` (optional, error_detail)
  Applicable only for recorded purchases where the job status is `failed`. It provides more details about the failure.
  - `error_message` (optional, string, max chars=500)
    A descriptive message about the `error_detail`.