Skip to main content

List offerings

GET 

/subscriptions/offerings

Retrieves a list of all subscription offerings.

Filtering

This endpoint supports filtering. For the general syntax, see Filtering.

The following attributes and operators are supported.

OperatorAttributeDescription
eqexternal_ref, proration_policy_idEquals. Checks if the values of two operands are equal. If they are, the condition is true.
inexternal_product_refsIn. Checks if the values are included in the specified string. If they are, the condition is true.

Request

Query Parameters

    page[offset] int64

    Possible values: <= 10000

    The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the page length store setting is used.

    page[limit] int64

    The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the page length store setting is used.

    include string
    filter string

Responses

Success. A list of offerings is returned.

Schema
    data Offering[]
  • Array [
  • id UUID (string)

    The unique identifier.

    type SubscriptionOfferingType (string)required

    Possible values: [subscription_offering]

    attributes OfferingAttributesrequired
    external_ref ExternalRef (string)

    Possible values: <= 2048 characters

    A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.

    name stringrequired

    Possible values: >= 3 characters and <= 1024 characters

    The name of the offering.

    description string

    Possible values: <= 1024 characters

    The offering description to display to customers.

    updated_at stringrequired

    The date and time a resource was updated.

    created_at stringrequired

    The date and time a resource was created.

    relationships Relationships

    Relationships are established between different subscription entities. For example, a product and a plan are related to an offering, as both are attached to it.

    anyOf
    title
    meta OfferingMetarequired
    external_product_refs string[]required
    owner stringrequired

    The owner of a resource, either store or organization.

    timestamps Timestampsrequired
    updated_at stringrequired

    The date and time a resource was updated.

    created_at stringrequired

    The date and time a resource was created.

  • ]
  • included OfferingIncludes
    products OfferingProduct[]
  • Array [
  • id UUID (string)

    The unique identifier.

    type SubscriptionOfferingProductType (string)required

    Possible values: [subscription_offering_product]

    attributes ProductAttributesrequired
    external_ref ExternalRef (string)

    Possible values: <= 2048 characters

    A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.

    name stringrequired

    Possible values: >= 3 characters and <= 1024 characters

    The name of the product.

    description string

    Possible values: <= 1024 characters

    The product or service description to display to customers.

    sku string

    Possible values: <= 1024 characters

    A stock keeping unit for the product, if appropriate.

    main_image uri

    Possible values: <= 1024 characters

    A URL from which an image or file for the product can be fetched. You can either upload your images and files to Commerce using the Commerce Files API or you can use your own content delivery network. If you are using the Commerce Files API, use Create a File to upload your file and return an HREF link in the response. An extensive range of media and file extensions are supported.

    price Price
    property name* object

    The base price.

    amount int64required

    The value as a whole number of the currency's smallest subdivision.

    includes_tax boolean

    Indicates whether the amount includes any taxes.

    price_units object

    The timeframe during which the product price is applicable. For example, for a streaming service, the price is $12.99 and the unit is months and the amount is 1. In other words, the streaming service is available for $12.99 a month. You may want to specify a unit price if you have many products that all have different prices. Rather than having to create separate plans for each product, you can specify the timeframe during which the product price is applicable and then create one plan that determines the billing frequency for those products.

    unit stringrequired

    Possible values: [day, month]

    A unit of time.

    amount integerrequired

    Possible values: >= 1

    The number of days or months the period covers.

    updated_at stringrequired

    The date and time a resource was updated.

    created_at stringrequired

    The date and time a resource was created.

    relationships Relationships

    Relationships are established between different subscription entities. For example, a product and a plan are related to an offering, as both are attached to it.

    anyOf
    title
    meta ProductMetarequired
    display_price DisplayPrice
    without_tax PriceFormatting
    amount int64required

    The unformatted amount for the objects.

    currency stringrequired

    The three-letter ISO currency code in uppercase, associated with a price.

    formatted stringrequired

    The formatted amount for the objects.

    with_tax PriceFormatting
    amount int64required

    The unformatted amount for the objects.

    currency stringrequired

    The three-letter ISO currency code in uppercase, associated with a price.

    formatted stringrequired

    The formatted amount for the objects.

    owner stringrequired

    The owner of a resource, either store or organization.

    timestamps Timestampsrequired
    updated_at stringrequired

    The date and time a resource was updated.

    created_at stringrequired

    The date and time a resource was created.

  • ]
  • plans OfferingPlan[]
  • Array [
  • id UUID (string)

    The unique identifier.

    type SubscriptionOfferingPlanType (string)required

    Possible values: [subscription_offering_plan]

    attributes PlanAttributesrequired
    external_ref ExternalRef (string)

    Possible values: <= 2048 characters

    A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.

    name stringrequired

    Possible values: >= 3 characters and <= 1024 characters

    A name for the plan.

    description string

    Possible values: <= 1024 characters

    The plan description to display to customers.

    billing_interval_type stringrequired

    Possible values: [day, week, month, year]

    The unit of time that billing intervals are measured.

    billing_frequency integerrequired

    Possible values: >= 1

    The number of intervals between issuing bills.

    trial_period integer

    The number of intervals from the start of the subscription before billing starts. Used with billing_interval_type. For example, if billing_interval_type is months, and trial_period is 1, the trial period is 1 month.

    plan_length integerrequired

    Possible values: >= 1

    The number of intervals that the subscription runs for.

    end_behavior stringrequired

    Possible values: [close, roll]

    Enables you to specify recurring payments. If end_behavior is roll, customers pay regularly and repeatedly. If end_behavior is close, customers pay a total amount in a limited number of partial payments.

    can_pause booleanrequired

    The subscriber can pause a subscription.

    can_resume booleanrequired

    The subscriber can resume a paused subscription.

    can_cancel booleanrequired

    The subscriber can cancel a subscription.

    base_price_percentage double

    Possible values: <= 100

    A percentage discount on the total cost of any products within an offering. For example, you can configure a percentage that equates the cost of a plan to the total value of all products within the offering, reduced by a percentage. For example, if you specify 10, a 10% discount is applied to the total value of all repeat products in an offering.

    fixed_price Price
    property name* object

    The base price.

    amount int64required

    The value as a whole number of the currency's smallest subdivision.

    includes_tax boolean

    Indicates whether the amount includes any taxes.

    updated_at stringrequired

    The date and time a resource was updated.

    created_at stringrequired

    The date and time a resource was created.

    relationships Relationships

    Relationships are established between different subscription entities. For example, a product and a plan are related to an offering, as both are attached to it.

    anyOf
    title
    meta OfferingPlanMetarequired
    price Price
    property name* object

    The base price.

    amount int64required

    The value as a whole number of the currency's smallest subdivision.

    includes_tax boolean

    Indicates whether the amount includes any taxes.

    display_price DisplayPrice
    without_tax PriceFormatting
    amount int64required

    The unformatted amount for the objects.

    currency stringrequired

    The three-letter ISO currency code in uppercase, associated with a price.

    formatted stringrequired

    The formatted amount for the objects.

    with_tax PriceFormatting
    amount int64required

    The unformatted amount for the objects.

    currency stringrequired

    The three-letter ISO currency code in uppercase, associated with a price.

    formatted stringrequired

    The formatted amount for the objects.

    active_plan ActivePlan (boolean)

    Whether a plan is active on a subscription using that offering. The active_plan attribute is null if a plan is not active in a subscription.

    owner stringrequired

    The owner of a resource, either store or organization.

    timestamps Timestampsrequired
    updated_at stringrequired

    The date and time a resource was updated.

    created_at stringrequired

    The date and time a resource was created.

  • ]
  • links object
    anyOf
    title
Loading...