# Omnichannel subscriptions

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


Represents a subscription purchased and managed in an external app marketplace (`apple_app_store` or `google_play_store`), normalized into Chargebee's omnichannel model.

Omnichannel subscriptions are typically created when you [record a purchase](/docs/api/recorded_purchases/record-a-purchase) and are kept in sync via store server notifications. They are store-managed: lifecycle changes come from Apple or Google, not from the Chargebee Subscriptions API.

Use [omnichannel statuses](/docs/api/omnichannel_statuses) for how store statuses map to `omnichannel_subscription_item.status`, and [omnichannel events](/docs/api/omnichannel_events) for notification-to-webhook mappings.

**Identifier tip:** Parent `id_at_source` is the Apple **Transaction ID** or Google **purchase token**. Nested `initial_purchase_transaction.id_at_source` is the Apple **Transaction ID** or Google **Order ID** (`GPA.…`). See attribute descriptions below.

**Note:** This resource represents in-app subscriptions made on Apple App Store and Google Play Store.

## Sample Omnichannel-subscription

```json
{
  "omnichannel_subscription": {
    "id": "__test__os_AHsdfs123ld1",
    "app_id": "__test__gps_sdfwerzx5134",
    "customer_id": "__test__XpbTXGTSRp3gEsD8",
    "id_at_source": "20000006743",
    "source": "google_play_store",
    "created_at": 1517487053,
    "object": "omnichannel_subscription",
    "omnichannel_subscription_items": [
      {
        "id": "__test__osi_BXswds133lf1",
        "id_at_source": "com.example.landmarks.premium",
        "status": "active",
        "current_term_start": 1728988425,
        "current_term_end": 1731666825,
        "omnichannel_subscription_item_offers": [
          {
            "id": "__test__off__AHsdfs123LD1",
            "offer_id_at_source": "intro_offer_google_monthly",
            "category": "introductory",
            "category_at_source": "INTRODUCTORY",
            "type": "free_trial",
            "type_at_source": "FREE_TRIAL",
            "discount_type": "percentage",
            "duration": "P1M",
            "percentage": 50,
            "price_currency": "USD",
            "price_units": 2,
            "price_nanos": 90000000,
            "offer_term_start": 1752676649,
            "offer_term_end": 1755268649
          },
          {..}
        ]
      },
      {..}
    ]
  }
}
```

## Omnichannel subscriptions attributes

## Input Parameters

- `id` (required, string, max chars=50)
  The ID generated by Chargebee for the omnichannel subscription.

- `id_at_source` (required, string, max chars=500)
  The identifier of the subscription in the `source`.
  
  **Apple App Store**: The original purchase **Transaction ID** (stable for the subscription lifecycle).
  
  **Google Play Store**: The subscription **purchase token**. This value can change when Google issues a new token after certain subscription changes; Chargebee updates `id_at_source` to the latest token.
  
  > **Note:** Do not confuse this with `initial_purchase_transaction.id_at_source`. For Google, the nested transaction uses the **Order ID** (`GPA.…`), not the purchase token.

- `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 storefront where the purchase is originally made and managed (`apple_app_store` or `google_play_store`).
  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.

- `customer_id` (optional, string, max chars=100)
  The `id` of the [customer](/docs/api/customers/customer-object#id) object that is associated with this purchase.

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

- `purchased_at` (optional, timestamp(UTC) in seconds)
  Timestamp (UTC) when the subscription was originally purchased in the app marketplace (initial purchase). This corresponds to the time of the initial purchase transaction in the [`source`](/docs/api/omnichannel_subscriptions/omnichannel_subscription-object#source).

- `updated_at` (required, timestamp(UTC) in seconds)
  Indicates timestamp when the `omnichannel_subscription` was last updated .

- `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.

- `omnichannel_subscription_items` (required, list of omnichannel_subscription_item)
  Items associated with the omnichannel\_subscription.

- `initial_purchase_transaction` (optional, omnichannel_transaction)
  Refers to the record created when a customer makes their first purchase.

## Omnichannel subscription item attributes

## Input Parameters

- `id` (required, string, max chars=40)
  Uniquely identifies an `omnichannel_subscription_item`.

- `item_id_at_source` (required, string, max chars=100)
  Product identifier of this subscription item in the source store.
  
  **Apple App Store**: The App Store Connect product identifier.
  
  **Google Play Store**: The Google Play product / base-plan identifier associated with the active entitlement. See also `item_parent_id_at_source` when a parent/child hierarchy applies.

- `item_parent_id_at_source` (optional, string, max chars=100)
  Parent product identifier in the source store, when the store exposes a parent/child product hierarchy.
  
  **Apple App Store**: Typically the subscription group / parent product context when applicable.
  
  **Google Play Store**: Typically the parent product ID associated with the base plan / offer hierarchy when applicable.

- `status` (required, enumerated string)
  Status of the `omnichannel_subscription_item`. Status lives on the item, not on the parent subscription. [Learn more](/docs/api/omnichannel_statuses) about status and store mappings.
  Possible enum values:
    - `active`
      The subscription item is active and entitled for the current term.
      
      **Google Play Store**: Also used when Google has canceled auto-renew but the term has not ended (`auto_renew_status` = `off`).
    - `expired`
      The subscription item expired for a non-cancellation reason. See `expiration_reason`.
    - `cancelled`
      The subscription item is cancelled (entitlement ended due to cancellation / revoke / refund contexts). See `cancellation_reason`.
    - `in_dunning`
      Billing is retrying after a payment failure and access may be restricted (Apple billing retry / Google account hold).
    - `in_grace_period`
      Billing is retrying during a grace period; service should typically continue.
    - `paused`
      The subscription item is paused. See `resumes_at` when available.

- `auto_renew_status` (optional, enumerated string)
  Whether the subscription item is set to auto-renew at the end of the current term (`on` or `off`).
  
  **Google Play Store**: When the customer cancels but remains in-term, `status` stays `active` and `auto_renew_status` is `off`.
  Possible enum values:
    - `off`
      Auto-renewal is disabled for the `omnichannel_subscription_item`.
    - `on`
      Auto-renewal is enabled for the `omnichannel_subscription_item`.

- `current_term_start` (optional, timestamp(UTC) in seconds)
  Start of the current billing period of the subscription item. It is applicable only if the [`status`](/docs/api/omnichannel_subscriptions/omnichannel_subscription-object#omnichannel_subscription_items) is `active` .

- `current_term_end` (optional, timestamp(UTC) in seconds)
  End of the current billing period of the subscription item. Applicable when [`status`](/docs/api/omnichannel_subscription_items/omnichannel_subscription_item-object#status) is `active`.
  
  **Apple App Store**: Closest analogue to [`next_billing_at`](/docs/api/subscriptions/subscription-object#next_billing_at) because Apple does not expose a separate next-renewal timestamp. Apple may renew up to 24 hours before expiry and, in billing retry, may retry for up to 60 days. [Learn more](https://developer.apple.com/documentation/storekit/in-app_purchase/original_api_for_in-app_purchase/subscriptions_and_offers/handling_subscriptions_billing#3221910).
  
  **Google Play Store**: Corresponds to the subscription expiry / next billing boundary from Play. When the customer has canceled but the term has not ended, `status` remains `active` with `auto_renew_status` = `off` (see [omnichannel statuses](/docs/api/omnichannel_statuses)).

- `expired_at` (optional, timestamp(UTC) in seconds)
  Indicates timestamp when the subscription associated with the `omnichannel_subscription_item` was `expired` in the [`source`](/docs/api/omnichannel_subscriptions/omnichannel_subscription-object#source)

- `expiration_reason` (optional, enumerated string)
  Specifies the reason for the subscription expiration. Present when `status` is `expired`.
  
  **Apple App Store**: Commonly maps from Apple expiration intents such as `BILLING_ERROR`, `PRODUCT_NOT_AVAILABLE`, and `OTHER`.
  
  **Google Play Store**: User-initiated and merchant-revoked expirations typically map to `cancelled` with a `cancellation_reason` instead of `expired`.
  Possible enum values:
    - `billing_error`
      Billing error, such as invalid customer payment information.
      
      **Apple App Store**: Maps from expiration intent `BILLING_ERROR`.
    - `product_not_available`
      The product was unavailable for purchase at the time of renewal.
      
      **Apple App Store**: Maps from expiration intent `PRODUCT_NOT_AVAILABLE`.
    - `other`
      The subscription associated with the item expired for an unspecified reason.
      
      **Apple App Store**: Maps from expiration intent `OTHER`.

- `cancelled_at` (optional, timestamp(UTC) in seconds)
  Indicates timestamp when the subscription associated with the `omnichannel_subscription_item` was `cancelled` in the [`source`](/docs/api/omnichannel_subscriptions/omnichannel_subscription-object#source)

- `cancellation_reason` (optional, enumerated string)
  The reason the subscription item was cancelled. Present when `status` is `cancelled`. Store applicability varies by enum value.
  Possible enum values:
    - `customer_cancelled`
      The customer voluntarily cancelled the subscription.
      
      **Apple App Store**: Commonly maps from expiration intent `CUSTOMER_CANCELLED`.
      
      **Google Play Store**: Commonly maps from user-initiated cancellation / cancel-at-term-end flows.
    - `customer_did_not_consent_to_price_increase`
      The customer did not consent to a price increase for the subscription item.
      
      **Apple App Store**: Maps from expiration intent `CUSTOMER_DID_NOT_CONSENT_TO_PRICE_INCREASE`.
      
      **Google Play Store**: Not typically used for this reason code.
    - `refunded_due_to_app_issue`
      The subscription was cancelled and refunded due to an app issue.
      
      **Apple App Store**: Commonly set for refund notifications with an app-issue refund reason.
      
      **Google Play Store**: Not typically used for this reason code.
    - `refunded_for_other_reason`
      The subscription was cancelled and refunded for another reason.
      
      **Apple App Store**: Commonly set for refund notifications with a non-app-issue refund reason.
      
      **Google Play Store**: Not typically used for this reason code.
    - `merchant_revoked`
      The merchant revoked access to the subscription.
      
      **Apple App Store**: Can apply when access is revoked (for example, `REVOKED` / related refund revoke flows).
      
      **Google Play Store**: Commonly maps from revoke / chargeback-style contexts (for example, `SUBSCRIPTION_REVOKED`).

- `grace_period_expires_at` (optional, timestamp(UTC) in seconds)
  Timestamp when the grace period for the `omnichannel_subscription_item` expires in the `source`.
  
  **Apple App Store**: Present when the item is in `in_grace_period` (Apple billing grace period).
  
  **Google Play Store**: Present when the item is in `in_grace_period` (`SUBSCRIPTION_STATE_IN_GRACE_PERIOD`).

- `resumes_at` (optional, timestamp(UTC) in seconds)
  Timestamp when the subscription automatically resumes after being set to `paused`.
  
  **Google Play Store**: Typically present for paused subscriptions.
  
  **Apple App Store**: Pause is not generally applicable in the same way; this attribute is usually absent.

- `has_scheduled_changes` (required, boolean, default=false)
  Indicates whether the `omnichannel_subscription_item` has any scheduled changes. When `true`, use [List scheduled changes for an omnichannel subscription item](/docs/api/omnichannel_subscription_items/list-scheduled-changes-for-omnichannel-subscription-item) to retrieve them.

- `updated_at` (required, timestamp(UTC) in seconds)
  Indicates timestamp when the `omnichannel_subscription_item` was last updated 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.

- `omnichannel_subscription_item_offers` (optional, list of omnichannel_subscription_item_offer)
  Represents the `omnichannel_subscription_item_offers` associated with the `omnichannel_subscription_item` .
  - `id` (required, string, max chars=40)
    Unique identifier for the `omnichannel_subscription_item_offer`. System-generated.
  - `offer_id_at_source` (optional, string, max chars=100)
    Identifier of the offer on the source platform (for example, Apple App Store or Google Play Store). Used to map Chargebee's record to the source.
  - `category` (required, enumerated string)
    Indicates functional purpose of the offer. For example, `introductory` indicates a first-time offer for new subscribers.
    Possible enum values:
      - `introductory`
        Introductory offer for first-time subscribers, typically providing special pricing or terms for the first billing cycle.
      - `promotional`
        Promotional offer that may be available to both new and existing subscribers, often featuring limited-time pricing or terms.
      - `developer_determined`
        Offer terms are determined by the developer and may include unique pricing or features. **Note**: Support for this category is planned for a future update.
  - `category_at_source` (optional, string, max chars=100)
    Category label as defined by the source platform (for example, Apple App Store or Google Play Store). Directly fetched from the source; useful for debugging or platform-specific workflows.
  - `type` (required, enumerated string)
    Indicates how the offer is applied from a pricing-model perspective.
    Possible enum values:
      - `free_trial`
        Provides a free trial period. The customer is not charged during the trial; regular billing begins after the trial ends.
      - `pay_up_front`
        Requires a fixed upfront payment for a defined subscription period, often at a discount. For example, pay for two months in advance.
      - `pay_as_you_go`
        Applies a recurring discounted price at each billing cycle over multiple renewals, such as on a monthly plan, a discount on the initial purchase, and the next three billing cycles.
  - `type_at_source` (optional, string, max chars=100)
    Offer type as recorded by the source platform (for example, Apple App Store or Google Play Store). Like `category_at_source`, this is useful for tracking and audit.
  - `discount_type` (optional, enumerated string)
    Discount strategy: percentage discount, fixed amount off, or fixed price override.
    Possible enum values:
      - `fixed_amount`
        Discount that subtracts a fixed amount from the original price of the subscription item.
      - `percentage`
        Applies a percentage discount on the original price of the subscription item. For example, 20% off.
      - `price`
        Overrides the original price with a fixed discounted price for the offer term. For example, set the price to $9.99 during the offer.
  - `duration` (required, string, max chars=5)
    Indicates how long the offer applies to the subscription. This attribute uses ISO 8601 duration format. For example, `P1M` (1 month), `P7D` (7 days). After this duration, regular pricing resumes.
  - `percentage` (optional, double, min=0.01, max=100)
    Used when `discount_type` is `percentage`. Specifies the discount as a decimal value. For example, a value of 12.5 corresponds to a 12.5% discount.
  - `price_currency` (optional, string, max chars=3)
    Three-letter [ISO 4217](https://www.chargebee.com/docs/billing/2.0/site-configuration/supported-currencies) currency code for the offer price (for example, USD, EUR, INR).
  - `price_units` (optional, long)
    Whole-unit portion of the offer amount (for example, `10` for $10.00). **Note:** Depending on the discount type, this value can represent different meanings. For a `fixed_amount` discount, it indicates the amount deducted from the original price; for a `price` discount, it reflects the final amount payable by the customer.
  - `price_nanos` (optional, long)
    Fractional part of the offer amount, expressed in nanos (billionths of the currency unit). For example, `500000000` represents 0.50. Combine with `price_units` to determine the total price (for example, $10.50). **Note:** Depending on the discount type, this value can represent different meanings. For a `fixed_amount` discount, it indicates the amount deducted from the original price; for a `price` discount, it reflects the final amount payable by the customer.
  - `offer_term_start` (optional, timestamp(UTC) in seconds)
    Timestamp when the offer becomes effective for the subscription item. It is typically set to the time when the offer is first applied or activated.
  - `offer_term_end` (optional, timestamp(UTC) in seconds)
    Timestamp when the offer becomes invalid. After this time, regular pricing or terms apply to the subscription item.
  - `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.

- `upcoming_renewal` (optional, upcoming_renewal)
  Information about the upcoming renewal price.
  
  **Google Play Store**: Present when Google provides renewal price information and [`auto_renew_status`](/docs/api/omnichannel_subscription_items/omnichannel_subscription_item-object#auto_renew_status) is `on`.
  
  **Apple App Store**: Not applicable; this field is absent.
  - `price_currency` (optional, string, max chars=3)
    The three-letter [ISO 4217](https://www.chargebee.com/docs/supported-currencies.html) currency code in which the next renewal is set to occur (`price_currency`).
  - `price_units` (optional, long)
    The whole units of the amount. For example: if `price_currency` is **USD** (two-decimal currency), then the unit value for **USD** **1.23** will be **1** if `price_currency` is **JPY** (zero-decimal currency), then the unit value for **JPY** **123** will be **123** if `price_currency` is **BHD** (three-decimal currency), then the unit value for **BHD** **1.234** will be **1**
  - `price_nanos` (optional, long)
    The fractional price amount, in nanos (billionths of the currency unit), for the next renewal. The value must be between **0** and **+999,999,999** inclusive. For example: If `price_currency` is **USD** (two-decimal currency), then nanos value for **USD** **1.23** will be **230,000,000** If `price_currency` is **JPY** (zero-decimal currency), then nanos value for **JPY** **123** will be **0** If `price_currency` is **BHD** (three-decimal currency), then nanos value for **BHD** **1.234** will be **234,000,000**

- `linked_item` (optional, linked_item)
  Represents an active product catalog mapping between an `omnichannel_subscription_item` and a Chargebee `item`. Use this attribute to retrieve entitlements for the `omnichannel_subscription_item` that are associated with the linked Chargebee `item` .
  - `id` (required, string, max chars=100)
    Represents the `item_id` of the Chargebee item linked to the `omnichannel_subscription_item` .
  - `linked_at` (optional, timestamp(UTC) in seconds)
    Indicates the timestamp when the mapping between the `omnichannel_subscription_item` and the Chargebee `item` was created in Chargebee.

## Initial purchase transaction attributes

## Input Parameters

- `id` (required, string, max chars=40)
  Unique ID of an `omnichannel_transaction`.

- `id_at_source` (required, string, max chars=100)
  The store-native identifier for this transaction.
  
  **Apple App Store**: **Transaction ID** for this transaction.
  
  **Google Play Store**: **Order ID** for this transaction (typically `GPA.…`). This is not the subscription purchase token (that is the parent `omnichannel_subscription.id_at_source`).

- `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).

- `price_currency` (optional, string, max chars=3)
  The three-letter ISO 4217 currency code associated with the transaction (`price_currency`).

- `price_units` (optional, long)
  The whole units of the amount. For example: if `price_currency` is **USD** (two-decimal currency), then the unit value for **USD** **1.23** will be **1** if `price_currency` is **JPY** (zero-decimal currency), then the unit value for **JPY** **123** will be **123** if `price_currency` is **BHD** (three-decimal currency), then the unit value for **BHD** **1.234** will be **1**

- `price_nanos` (optional, long)
  The fractional price amount, in nanos (billionths of the currency unit). The value must be between **0** and **+999,999,999** inclusive. For example: If `price_currency` is **USD** (two-decimal currency), then nanos value for **USD** **1.23** will be **230,000,000** If `price_currency` is **JPY** (zero-decimal currency), then nanos value for **JPY** **123** will be **0** If `price_currency` is **BHD** (three-decimal currency), then nanos value for **BHD** **1.234** will be **234,000,000**
  
  **Apple App Store**: Typically present for purchase and renewal transactions.
  
  **Google Play Store**: May be present when Google provides price data for the transaction; otherwise absent.

- `type` (required, enumerated string)
  Omnichannel transaction type that describes this transaction.
  Possible enum values:
    - `purchase`
      Indicates that the transaction occurred for an initial purchase (subscription or one-time order).
    - `renewal`
      Indicates that the transaction was initiated as part of a renewal for a previously completed subscription purchase.

- `transacted_at` (optional, timestamp(UTC) in seconds)
  Timestamp denoting when the transaction occurred in the `source`.
  
  **Apple App Store**: Typically present.
  
  **Google Play Store**: May be present when Google provides purchase time for the transaction; otherwise absent.

- `created_at` (required, timestamp(UTC) in seconds)
  The timestamp of transaction creation

- `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. This attribute will be present only if the resource has been updated after 2016-09-28.

- `linked_omnichannel_subscriptions` (optional, list of linked_omnichannel_subscription)
  A list of `omnichannel_subscription` objects linked to this transaction. Each entry represents a subscription associated with the transaction.
  - `omnichannel_subscription_id` (optional, string, max chars=100)
    The `id` of a linked [`omnichannel_subscription`](/docs/api/omnichannel_subscriptions/omnichannel_subscription-object#id).

- `linked_omnichannel_one_time_orders` (optional, list of linked_omnichannel_one_time_order)
  A list of `omnichannel_one_time_order` objects linked to this transaction. Each entry represents a one-time order associated with the transaction.
  - `omnichannel_one_time_order_id` (optional, string, max chars=100)
    The `id` of a linked [`omnichannel_one_time_order`](/docs/api/omnichannel_one_time_orders/omnichannel_one_time_order-object#id).