Purchase an offering

Error

A valid request URL is required to generate request examples

{
  "purchase": {
    "id": "purchase.cf637646-71a4-430d-aaea-a66f1a48a83c",
    "offering_id": "offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9",
    "onetime_offering_id": "onetime_offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9",
    "purchased_at": "2025-01-01T12:00:00Z",
    "completed_at": "2025-01-01T12:00:00Z",
    "description": "<string>",
    "price": {
      "amount": 123,
      "currency": {
        "code": "<string>",
        "name": "<string>",
        "symbol": "<string>",
        "base_unit": 123
      }
    },
    "status": "completed",
    "metadata": {},
    "entitlement_status": {
      "content_key": "<string>",
      "has_entitlement": true,
      "expires": "2023-11-07T05:31:56Z",
      "recurs_at": "2023-11-07T05:31:56Z"
    }
  },
  "action_required": true,
  "action_required_details": {
    "next": "<string>",
    "reason": "<string>"
  }
}

POST

purchases

offerings

Error

A valid request URL is required to generate request examples

{
  "purchase": {
    "id": "purchase.cf637646-71a4-430d-aaea-a66f1a48a83c",
    "offering_id": "offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9",
    "onetime_offering_id": "onetime_offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9",
    "purchased_at": "2025-01-01T12:00:00Z",
    "completed_at": "2025-01-01T12:00:00Z",
    "description": "<string>",
    "price": {
      "amount": 123,
      "currency": {
        "code": "<string>",
        "name": "<string>",
        "symbol": "<string>",
        "base_unit": 123
      }
    },
    "status": "completed",
    "metadata": {},
    "entitlement_status": {
      "content_key": "<string>",
      "has_entitlement": true,
      "expires": "2023-11-07T05:31:56Z",
      "recurs_at": "2023-11-07T05:31:56Z"
    }
  },
  "action_required": true,
  "action_required_details": {
    "next": "<string>",
    "reason": "<string>"
  }
}

Required Scopes

capi:write - Write access to Customer API resources

Authorizations

Authorization

string

header

required

Supertab OAuth2 flow for CAPI. See Authentication.

Headers

x-api-version

string<date>

default:9999-01-01

The version of the Customer API you are using. The version of the Customer API you are using.

x-supertab-client-id

string<tagged_id>

required

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

Body

application/json

offering_id

string<tagged_id>

required

currency_code

string

required

Required string length: 3

metadata

Metadata · object

Show child attributes

metadata.{key}

Response

Successful Response

purchase

Purchase · object

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<tagged_id> | 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<tagged_id> | null

required

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

Example:

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

purchase.onetime_offering_id

string<tagged_id> | null

required

Which one-time offering was purchased, if this purchase resulted from purchasing a one-time offering.

Example:

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

purchase.purchased_at

string<date-time> | null

required

The time the purchase completed.

Example:

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

purchase.completed_at

string<date-time> | 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.

purchase.price

Price · object

required

An amount of money

Show child attributes

purchase.price.amount

integer

required

Price amount expressed in currency base units

purchase.price.currency

Currency · object

required

The price's currency

Show child attributes

purchase.price.currency.code

string

required

ISO2417 currency code

purchase.price.currency.name

string

required

Full name

purchase.price.currency.symbol

string

required

Unicode currency symbol

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

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

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

EntitlementStatus · object

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

purchase.entitlement_status.has_entitlement

boolean

required

If the customer has access to this content

purchase.entitlement_status.expires

string<date-time> | null

required

When the customer's access will expire

purchase.entitlement_status.recurs_at

string<date-time> | 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

Determines if 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

ActionRequiredDetails · object

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.

action_required_details.reason

string

required

Describes why action should be taken

Retrieve site Retrieve a one-time offering

⌘I

Introduction

Reference

Guides

Endpoints

Required Scopes

Authorizations

Headers

Body

Response

Introduction

Reference

Guides

Endpoints

​Required Scopes

Authorizations

Headers

Body

Response

Required Scopes