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

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

Model Class

 

      Omnichannel subscription item attributes
      
   
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
 
 
active
When the subscription associated with the omnichannel_subscription_item
is active
expired
When the subscription associated with the omnichannel_subscription_item
is expired
cancelled
When the subscription associated with the omnichannel_subscription_item
is cancelled
in_dunning
When 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
 
 
off
The auto-renewal of omnichannel_subscription_item
is disabled.
on
The 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_error
Indicates a billing error, such as the customer's payment information being invalid.
product_not_available
Indicates that the product was unavailable for purchase at the time of renewal.
other
Indicates 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_cancelled
Indicates that the subscription was voluntarily cancelled by the customer.
customer_did_not_consent_to_price_increase
Indicates that the customer did not consent to the price increase for the subscription item.
refunded_due_to_app_issue
Indicates that the subscription was cancelled and refunded due to the app issue.
refunded_for_other_reason
Indicates 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_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.
 
 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 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 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_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.
 
 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
 
 
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 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
      
  
 
  Try in API Explorer
   
Returns a list of omnichannel_subscription_item_scheduled_change
associated with the specified omnichannel_subscription_item
.
  

        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