# Omnichannel subscription items

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


Represents a product entitlement (item) within an [`omnichannel_subscription`](/docs/api/omnichannel_subscriptions) purchased on Apple App Store or Google Play Store.

Status, auto-renew, term dates, and cancel/expire reasons live on this resource. See [omnichannel statuses](/docs/api/omnichannel_statuses) for store mappings.

When `has_scheduled_changes` is `true`, use [List scheduled changes](/docs/api/omnichannel_subscription_items/list-scheduled-changes-for-omnichannel-subscription-item) to retrieve deferred product or pause changes.

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

## Sample Omnichannel-subscription-item

```json
{
  "omnichannel_subscription_item": {
    "id": "osi_16A4DbUTLvGh35",
    "item_id_at_source": "com.chargebee.demo.landmarks.premium.monthly",
    "status": "active",
    "auto_renew_status": "on",
    "current_term_start": 1730902131,
    "current_term_end": 1730902431,
    "object": "omnichannel_subscription_item"
  }
}
```

## Omnichannel subscription items 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. Applicable when `status` 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)
  Timestamp when the subscription associated with the `omnichannel_subscription_item` expired in the `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)
  Timestamp when the subscription associated with the `omnichannel_subscription_item` was cancelled in the `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)
  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`.

- `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)
    Timestamp when the mapping between the `omnichannel_subscription_item` and the Chargebee `item` was created in Chargebee.

## Omnichannel subscription item offer attributes

## Input Parameters

- `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.
  
  **Apple App Store**: Offer identifier from App Store Connect / StoreKit.
  
  **Google Play Store**: Offer / base-plan offer identifier from Play Console when applicable.

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