Purchase an offering

Purchases a pre-defined offering by placing it on the customer’s current tab.

Depending on the customer’s existing relationship with Supertab they may be required to make purchases in a specific currency. Check /customers/me for information on what currency the customer makes purchases in.

If the new purchase causes the tab to become full a payment is required before the purchase will complete.

Authorizations

Authorization

string

header

required

The access token received from the authorization server in the OAuth 2.0 flow.

Headers

x-api-version

string

required

The version of the Customer API you are using.

x-supertab-client-id

string

required

Your Client ID with Supertab. Used to identify the website on which Customer is making a Purchase.

Example:

"live_client.4df706b5-297a-49c5-a4cd-2a10eca12ff9"

Body

application/json

offering_id

string

required

Example:

"offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9"

currency_code

string

required

Required string length: 3

metadata

object

Show child attributes

metadata.{key}

Response

201

application/json

Successful Response

purchase

object | null

required

Purchase created as a result of purchasing this offering.

A null value means no purchase was created, see action_required_details for the reason.

Show child attributes

purchase.id

string | null

required

When a Purchase has been made with you, shows the ID of the Purchase. Otherwise obfuscated and is shown as null.

Example:

"purchase.cf637646-71a4-430d-aaea-a66f1a48a83c"

purchase.offering_id

string | null

required

Which offering was purchased, if this purchase resulted from purchasing a pre-defined offering.

Example:

"offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9"

purchase.purchased_at

string | null

required

The time the purchase completed.

Example:

"2025-01-01T12:00:00Z"

purchase.completed_at

string | null

required

The time the purchase completed.

Where Supertab requires a payment this will be null until the payment completes.

Example:

"2025-01-01T12:00:00Z"

purchase.description

string

required

A summary of the purchase, usually including the site name and the type of a given entitlement.

Example:

"The Leek - 24 Hours Time Pass"

purchase.price

object

required

An amount of money

Show child attributes

purchase.price.amount

integer

required

Price amount expressed in currency base units

Example:

50

purchase.price.currency

object

required

The price's currency

Show child attributes

purchase.price.currency.code

string

required

ISO2417 currency code

Example:

"USD"

purchase.price.currency.name

string

required

Full name

Example:

"US Dollar"

purchase.price.currency.symbol

string

required

Unicode currency symbol

Example:

"$"

purchase.price.currency.base_unit

integer

required

The relationship between the currency's minor and major unit.

For most currencies including USD & EUR this will be 100. For currencies which do not use decimals (e.g JPY) this will 1

Example:

100

purchase.status

enum<string>

required

The status of the purchase.

Purchases may be pending or completed.

Only completed purchases grant access, pending purchases are purchases which require payment before entitlement is granted

Available options:

completed,

pending,

abandoned

purchase.metadata

object

required

Freeform metadata associated with the purchase.

This can be used for e.g associating the purchase with a user identifier in your system

Show child attributes

purchase.metadata.{key}

purchase.entitlement_status

object | null

required

The customer's access (if any) as a result of this purchase

Show child attributes

purchase.entitlement_status.content_key

string

required

The content_key being checked

Example:

"site.cf637646-71a4-430d-aaea-a66f1a48a83c"

purchase.entitlement_status.has_entitlement

boolean

required

If the customer has access to this content

purchase.entitlement_status.expires

string | null

required

When the customer's access will expire

purchase.entitlement_status.recurs_at

string | null

required

If this access is a result of a subscription, the time the subscription will renew unless cancelled by the customer.

action_required

boolean

required

Is further interaction with the customer required on Supertab in order to complete this purchase.

Most commonly this will be when Supertab required a customer to make a payment before continuing.

action_required_details

object | null

required

Details of what to do next to complete pending purchases

Show child attributes

action_required_details.next

string

required

Forward the user here to start e.g. a checkout session which should then be opened in a pop-up window.

Example:

"https://checkout.supertab.co?tab_id=tab.13de9ebb-83bd-4aeb-80aa-6f2a21c1be69"

action_required_details.reason

string

required

Describes why action should be taken