Record a purchase

Records an in-app purchase from Apple App Store or Google Play Store in Chargebee. The API starts an asynchronous verification job and returns a recorded_purchase resource. Track progress with status: in_process, completed, failed, or ignored.

Handle the synchronous API response first. The request can fail immediately (for example, an incorrect app_id, a malformed URL or request body, or a customer conflict on an already-recorded purchase) before any job is created—treat these as standard API errors (4xx). Only after the call is accepted and returns a recorded_purchase should you track the asynchronous job via status (in_process → completed, failed, or ignored). Omnichannel subscription or one-time order creation still happens asynchronously after a successful sync acceptance.

Prerequisites

• Configure the omnichannel app (app_id) for Apple or Google in Chargebee.
• Provide exactly one store payload: apple_app_store[...] or google_play_store[...].
• Associate the purchase with a Chargebee customer[id] (created automatically if missing when customer details are supplied).

Synchronous customer conflicts (existing purchase)

If the store purchase is already recorded in Chargebee under a different customer, Record a Purchase returns a synchronous 4xx (customer_id_conflict_use_move_api / customer_id_mismatch) and does not create a recorded_purchase job. To reassign ownership, use Move an omnichannel subscription. Re-recording the same purchase for the same customer typically completes asynchronously with status ignored when the subscription or one-time order already exists.

Apple App Store input (mutually exclusive paths)

• Prefer apple_app_store[transaction_id] for subscriptions and one-time products when you have the StoreKit transaction ID.
• Or pass apple_app_store[receipt] and apple_app_store[product_id].

Google Play Store input (mutually exclusive paths)

• Prefer google_play_store[order_id] for subscriptions and one-time orders.
• Or pass google_play_store[purchase_token] for subscriptions; for one-time orders also pass google_play_store[product_id].

Impacts (when status becomes completed)

• Subscription purchase: Creates/links linked_omnichannel_subscriptions, sets omnichannel_transaction_id, and emits omnichannel_subscription_created (or omnichannel_subscription_imported when historical transactions are present). Chargebee may also emit omnichannel_transaction_created.
• One-time order purchase: Creates/links linked_omnichannel_one_time_orders, sets omnichannel_transaction_id, and emits omnichannel_one_time_order_created.

Impacts (when status is failed)

• Review error_detail and correct the payload. Chargebee emits record_purchase_failed.

Impacts (when status is ignored)

• The purchase already has an omnichannel subscription or one-time order in Chargebee. No new linked resource is created for this job—use the existing resource. Linked IDs and omnichannel_transaction_id appear when status is completed, not for ignored.

See omnichannel events for the full recording and notification mapping tables.