API docs by Redocly

Shift72 Shopping API (1.0.0)

Download OpenAPI specification:Download

Get Purchase Options

Returns the available purchase options for an item. For example, an item could be rented directly, or accessed via a pass, subscription, or bundle.

This API is specific to the user making the request.

If no auth token is provided, only public purchase options will be returned.

With an auth token it will take into account a user's plans for Plan Based Pricing, whether they already own the item, etc.

The purchase options returned are payment-provider specific too. By default the API will use the default payment provider, but an API consumer can list the payment methods it specifically supports or is interested in (e.g. ?providers=vista_loyalty,apple). This filters out incompatible options (e.g. subscriptions are not supported with loyalty points or IAPs)

This API can also provide a pricing preview when a promo code is being used (e.g. ?promo=RENT25).

Prices will reflect any applicable discounts and will include the original price, amount off, and metadata describing whether the promo code applies to each option.

A UI may want to disable or hide those options once the user enters the promo code, or show an error if the promocode doesn't apply to any options.

Contract

  1. The options provided will be location-specific, based on the IP geolocation of the requester.
  2. The options will be user-specific if an auth token is provided. This might take into account plan-based pricing / availability.
  3. The options array will only include purchasable options. If an offering is unavailable it will not be returned. In future, the API might return an unavailable_options array as well, if this information is useful.
  4. The options returned are indicative and not a guaranteed quote. Pricing, availability, promo limits, or expiry conditions may change before a shopping session is created..
  5. The API will return purchase options for related items — e.g. bundles and plans that would give access to this content too. Callers should inspect the slug on each purchase option to determine the item being purchased.
path Parameters
slug
required
string
Example: /film/123

The slug to get the purchase options for.

query Parameters
providers
string
Example: providers=stripe_elements,vista_loyalty

a comma-separated list of payment providers to find purchase options for. If not provided, the default provider for the site will be used. Payment providers that the backend doesn't support or are not configured will be ignored.

Responses

Response Schema: application/json
Array of objects (PurchaseOption)
Array
type
string
Enum: "purchase" "subscription" "loyalty" "free" "promo_only"

Type of purchase option, and the sort of payment flow that might be needed:

  • purchase: One-off payment
  • subscription: Recurring payment
  • loyalty: Uses loyalty credits, fairly provider specific
  • free: No payment required
  • promo_only: Only available via 100% discount code
slug
string

The Shift72 identifier for the item being purchased. This could be a film, TV season, a plan, a bundle, etc.

Usually, requesting purchase options for a particular slug would return purchase options matching that, but it could also return other suggestions -- e.g. for bundles or plans that grant access to the content too.

id
string

A human-readable ID that should be stable across calls, to assist with selection UIs. Do not attempt to parse this string as the format is not guaranteed.

provider
string

The payment provider this purchase option is intended to be used with.

quality
string
Enum: "hd" "sd"

For video content purchases, is this an HD or SD purchase. Not present for plans.

ownership
string
Enum: "rent" "buy"

For video content purchases, is this a rental or a longer term ownership (buy / EST). Not present for plans.

object

The price the user will pay for this. This taken into account any discounts and plan based pricing. Will be absent if there is no monetary price to pay.

value
string^\d+(\.\d+)?$

Decimal monetary value as a string to preserve precision (e.g. "7.99")

formatted
string

A formatted representation of this currency value. (e.g. "$7.99" or "7.99€")

currency
string
sku
string

The SKU to use when doing an IAP purchase. This may be provider specific. The presence of this field implies the purchase option is an IAP.

tax_inclusive
boolean
Default: true

Whether this price is tax inclusive. This may be omitted if it's not a total price (e.g. amount off for a discount)

object

Present for recurring prices (e.g. subscriptions)

interval
string
Enum: "day" "week" "month" "year"

The unit used (month, year)

interval_count
integer

The number of units (e.g. 3 months)

object

If a discount was applied, this is the base price.

value
string^\d+(\.\d+)?$

Decimal monetary value as a string to preserve precision (e.g. "7.99")

formatted
string

A formatted representation of this currency value. (e.g. "$7.99" or "7.99€")

currency
string
sku
string

The SKU to use when doing an IAP purchase. This may be provider specific. The presence of this field implies the purchase option is an IAP.

tax_inclusive
boolean
Default: true

Whether this price is tax inclusive. This may be omitted if it's not a total price (e.g. amount off for a discount)

object

Present for recurring prices (e.g. subscriptions)

interval
string
Enum: "day" "week" "month" "year"

The unit used (month, year)

interval_count
integer

The number of units (e.g. 3 months)

object

Present for subscriptions. This should match the period on the price.

value
string^\d+(\.\d+)?$

Decimal monetary value as a string to preserve precision (e.g. "7.99")

formatted
string

A formatted representation of this currency value. (e.g. "$7.99" or "7.99€")

currency
string
sku
string

The SKU to use when doing an IAP purchase. This may be provider specific. The presence of this field implies the purchase option is an IAP.

tax_inclusive
boolean
Default: true

Whether this price is tax inclusive. This may be omitted if it's not a total price (e.g. amount off for a discount)

object

Present for recurring prices (e.g. subscriptions)

interval
string
Enum: "day" "week" "month" "year"

The unit used (month, year)

interval_count
integer

The number of units (e.g. 3 months)

object

Information about the discount

eligible
boolean

Whether the promo-code can be applied to this purchase option.

type
string
Enum: "percentage" "value"

The kind of discount. Percentage or a fixed value off

object

How much the price was discounted by (positive value)

value
string^\d+(\.\d+)?$

Decimal monetary value as a string to preserve precision (e.g. "7.99")

formatted
string

A formatted representation of this currency value. (e.g. "$7.99" or "7.99€")

currency
string
sku
string

The SKU to use when doing an IAP purchase. This may be provider specific. The presence of this field implies the purchase option is an IAP.

tax_inclusive
boolean
Default: true

Whether this price is tax inclusive. This may be omitted if it's not a total price (e.g. amount off for a discount)

object

Present for recurring prices (e.g. subscriptions)

interval
string
Enum: "day" "week" "month" "year"

The unit used (month, year)

interval_count
integer

The number of units (e.g. 3 months)

Response samples

Content type
application/json
Example
{
  • "options": [
    • {
      • "type": "purchase",
      • "slug": "/film/2858",
      • "provider": "stripe_elements",
      • "price": {
        },
      • "quality": "hd",
      • "ownership": "rent",
      • "id": "/film/2858|hd-rent-stripe-elements-purchase"
      }
    ]
}