Settings
API Version
Product Catalog
Library

Omnichannel subscription items

This resource unifies representation of a Subscription item across multiple source.
Note: This resource represents in-app subscriptions made on Apple App Store and Google Play Store.

Sample omnichannel subscription item [ JSON ]

{ "omnichannel_subscription_item_scheduled_change": { "omnichannel_subscription_item_id": "__test__osi_BXswds133lf1", "scheduled_at": 1739345778, "change_type": "downgrade", "object": "omnichannel_subscription_item_scheduled_change", "current_state": { "item_id_at_source": "com.example.landmarks.premium" }, "scheduled_state": { "item_id_at_source": "com.example.landmarks.basic" } } }

API Index URL GET

https://{site}.chargebee.com/api/v2/omnichannel_subscription_items

Model Class

 

      Omnichannel subscription item attributes
      
  
Event types
 

      This is a list of the event types we currently support. We will continue
      to add more events moving forward. All events follow a uniform pattern -
      <resource>_<event_name>. The resources that will be
      present in the event content are provided beneath each event type's
      description.
    
 
Note: If consolidated invoicing is enabled, the
      attributes invoice.subscription_id and
      credit_note.subscription_id should not be used
      (as it will not be present if the invoice / credit note has lines from
      multiple subscriptions). Instead to know the related subscriptions,
      their line_items' subscription_id attribute should be referred.
    
 
 
id id
 

          string, max chars=40
 Uniquely identifies a omnichannel_subscription_item. 
 
item_id_at_source item_id_at_source
 

          string, max chars=100
 Product ID in the source. 
 
item_parent_id_at_source item_parent_id_at_source
 

          optional, string, max chars=100
 The parent name of the product ID in the source. 
 
status status
 

          enumerated string
 Status of the omnichannel_subscription_item. Learn more about status and their mapping with the store's status. 
 
Possible values are
 
 
activeWhen the subscription associated with the omnichannel_subscription_item is activeexpiredWhen the subscription associated with the omnichannel_subscription_item is expiredcancelledWhen the subscription associated with the omnichannel_subscription_item is cancelledin_dunningWhen the subscription associated with the omnichannel_subscription_item is in_dunning
 
 Show all values[+]
auto_renew_status auto_renew_status
 

          optional, enumerated string
 The renewal status for the omnichannel_subscription_item. 
 
Possible values are
 
 
offThe auto-renewal of omnichannel_subscription_item is disabled.onThe auto-renewal of omnichannel_subscription_item is enabled.
 
 Show all values[+]
current_term_start 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 is active. 
 
current_term_end current_term_end
 

          optional, timestamp(UTC) in seconds
 End of the current billing period of the subscription item. It is applicable only if the status is active. 
 
expired_at expired_at
 

          optional, timestamp(UTC) in seconds
 Indicates timestamp when the subscription associated with the omnichannel_subscription_item was expired in the source 
 
expiration_reason expiration_reason
 

          optional, enumerated string
 Specifies the reason for the subscription expiration. 
 
Possible values are
 
 
billing_errorIndicates a billing error, such as the customer's payment information being invalid.product_not_availableIndicates that the product was unavailable for purchase at the time of renewal.otherIndicates that the subscription associated with the item expired for an unspecified reason.
 
 Show all values[+]
cancelled_at cancelled_at
 

          optional, timestamp(UTC) in seconds
 Indicates timestamp when the subscription associated with the omnichannel_subscription_item was cancelled in the source 
 
cancellation_reason cancellation_reason
 

          optional, enumerated string
 The reason of canceling the subscription. 
 
Possible values are
 
 
customer_cancelledIndicates that the subscription was voluntarily cancelled by the customer.customer_did_not_consent_to_price_increaseIndicates that the customer did not consent to the price increase for the subscription item.refunded_due_to_app_issueIndicates that the subscription was cancelled and refunded due to the app issue.refunded_for_other_reasonIndicates that the subscription was cancelled and refunded for another reason.
 
 Show all values[+]
grace_period_expires_at grace_period_expires_at
 

          optional, timestamp(UTC) in seconds
 Indicates timestamp when the grace period of subscription associated with the omnichannel_subscription_item expires in the source 
 
resumes_at resumes_at
 

          optional, timestamp(UTC) in seconds
 Indicates timestamp when the subscription automatically resumes after being set to paused. 
 
has_scheduled_changes has_scheduled_changes
 

          boolean, default=false
 Indicates whether the omnichannel_subscription_item has any scheduled changes. 
 
resource_version 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
 This field contains information about the upcoming renewal. It is present only if the source provides renewal information (currently available only for Google Play Store purchases) and the omnichannel_subscription_item's auto_renew_status is set to on to renew for the next term. Otherwise, this field is absent. 
 
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. 
 
 

          Omnichannel Subscription Item Offer attributes
          
 
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. 
 
 

      resource_version
 Show attributes [+]
 
 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.
 
 
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. 
 
 

      offer_term_end
 Show attributes [+]
 
 optional, timestamp(UTC) in seconds
 Timestamp when the offer becomes invalid. After this time, regular pricing or terms apply to the subscription item.
 
 
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_start
 Show attributes [+]
 
 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.
 
 
price_nanos
 

      optional, long
 Fractional part of the offer amount in nanos (billionths of the currency unit). For example, 500000000 represents 0.50. Combine with price_units to construct the total price (for example, $10.50). 
 
 

      price_nanos
 Show attributes [+]
 
 optional, long
 Fractional part of the offer amount in nanos (billionths of the currency unit). For example, 500000000 represents 0.50. Combine with price_units to construct the total price (for example, $10.50).
 
 
price_units
 

      optional, long
 Whole-unit portion of the offer amount (for example, 10 for $10.00). 
 
 

      price_units
 Show attributes [+]
 
 optional, long
 Whole-unit portion of the offer amount (for example, 10 for $10.00).
 
 
price_currency
 

      optional, string, max chars=3
 Three-letter ISO 4217 currency code for the offer price (for example, USD, EUR, INR). 
 
 

      price_currency
 Show attributes [+]
 
 optional, string, max chars=3
 Three-letter ISO 4217 currency code for the offer price (for example, USD, EUR, INR).
 
 
percentage
 

      optional, double, min=0.01, max=100.0
 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. 
 
 

      percentage
 Show attributes [+]
 
 optional, double, min=0.01, max=100.0
 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.
 
 
duration
 

      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. 
 
 

      duration
 Show attributes [+]
 
 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.
 
 
discount_type
 

      optional, enumerated string
 Discount strategy: percentage discount, fixed amount off, or fixed price override. 
 
Possible values are
 
 
fixed_amountDiscount that subtracts a fixed amount from the original price of the subscription item.percentageApplies a percentage discount on the original price of the subscription item. For example, 20% off.priceOverrides the original price with a fixed discounted price for the offer term. For example, set the price to $9.99 during the offer.
 
 Show all values[+]
 

      discount_type
 Show attributes [+]
 
 optional, enumerated string
 Discount strategy: percentage discount, fixed amount off, or fixed price override.
 
 
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), such as code>category_at_source is useful for tracking and audit. 
 
 

      type_at_source
 Show attributes [+]
 
 optional, string, max chars=100
 Offer type as recorded by the source platform (for example, Apple App Store or Google Play Store), such as code>category_at_source is useful for tracking and audit.
 
 
type
 

      enumerated string
 Indicates how the offer is applied from a pricing-model perspective. 
 
Possible values are
 
 
free_trialProvides a free trial period. The customer is not charged during the trial; regular billing begins after the trial ends.pay_up_frontRequires a fixed upfront payment for a defined subscription period, often at a discount. For example, pay for two months in advance.pay_as_you_goApplies 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.
 
 Show all values[+]
 

      type
 Show attributes [+]
 
 required, enumerated string
 Indicates how the offer is applied from a pricing-model perspective.
 
 
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. 
 
 

      category_at_source
 Show attributes [+]
 
 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.
 
 
category
 

      enumerated string
 Indicates functional purpose of the offer. For example, introductory indicates a first-time offer for new subscribers. 
 
Possible values are
 
 
introductoryIntroductory offer for first-time subscribers, typically providing special pricing or terms for the first billing cycle.promotionalPromotional offer that may be available to both new and existing subscribers, often featuring limited-time pricing or terms.developer_determinedOffer terms that are determined by the developer, potentially including unique pricing or features.
 
 Show all values[+]
 

      category
 Show attributes [+]
 
 required, enumerated string
 Indicates functional purpose of the offer. For example, introductory indicates a first-time offer for new subscribers.
 
 
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. 
 
 

      offer_id_at_source
 Show attributes [+]
 
 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.
 
 
id
 

      string, max chars=40
 Unique identifier for the omnichannel_subscription_item_offer. System-generated. 
 
 

      id
 Show attributes [+]
 
 required, string, max chars=40
 Unique identifier for the omnichannel_subscription_item_offer. System-generated.
 
 
 
Consent Fields for Omnichannel subscription item
 
 
Custom Fields for Omnichannel subscription item
 
  

      List scheduled changes for omnichannel subscription item
      
  
 
Returns a list of omnichannel_subscription_item_scheduled_change associated with the specified omnichannel_subscription_item.
  
Notes
 
 

        Sample Request
      
 

  Try in API Explorer

 
 
curl  https://{site}.chargebee.com/api/v2/omnichannel_subscription_items/{omnichannel-subscription-item-id}/scheduled_changes \
     -G  \
     -u {site_api_key}:
 

      copy
      
Click to Copy
 
 
200:
 
OK
 
STATUS
 

    Sample Response [ JSON ]
 
Show more...
 
{
    "list": [
        {
            "omnichannel_subscription_item_scheduled_change": {
                "omnichannel_subscription_item_id": "__test__osi_BXswds133lf1",
                "scheduled_at": 1739345778,
                "change_type": "downgrade",
                "object": "omnichannel_subscription_item_scheduled_change",
                "current_state": {
                    "item_id_at_source": "com.example.landmarks.premium"
                },
                "scheduled_state": {
                    "item_id_at_source": "com.example.landmarks.basic"
                }
            }
        },
        {..}
    ]
}
 

      URL Format
      GET
 

      https://{site}.chargebee.com/api/v2/omnichannel_subscription_items/{omnichannel-subscription-item-id}/scheduled_changes
    
 
Method
 
 
Input Parameters
 
limit[]
 

      optional, integer, default=10, min=1, max=100 
 The number of resources to be returned. 
offset[]
 

      optional, string, max chars=1000 
 Determines your position in the list for pagination. To ensure that the next page is retrieved correctly, always set 'offset' to the value of 'next_offset' obtained in the previous iteration of the API call. 
   
 
    
 
Returns
 
omnichannel_subscription_item_scheduled_change  omnichannel_subscription_item_scheduled_change
 

      always returned 
 Resource object representing omnichannel_subscription_item_scheduled_change
next_offset  next_offset
 
 optional, string, max chars=1000
 This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter `offset`.
 
Sample admin console URL
 

      https://{site}.chargebee.com/admin-console/omnichannel_subscription_items/123x