Purchase an offering

POST

purchases

offerings

{
  "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": "The Leek - 24 Hours Time Pass",
    "price": {
      "amount": 50,
      "currency": {
        "code": "USD",
        "name": "US Dollar",
        "symbol": "$",
        "base_unit": 100
      }
    },
    "status": "completed",
    "metadata": {},
    "entitlement_status": {
      "content_key": "site.cf637646-71a4-430d-aaea-a66f1a48a83c",
      "has_entitlement": true,
      "expires": "2023-11-07T05:31:56Z",
      "recurs_at": "2023-11-07T05:31:56Z"
    }
  },
  "action_required": true,
  "action_required_details": {
    "next": "https://checkout.supertab.co?tab_id=tab.13de9ebb-83bd-4aeb-80aa-6f2a21c1be69",
    "reason": "Payment required to complete purchase"
  }
}

Required Scopes

capi:write - Write access to Customer API resources

Headers

x-api-version

string

default:2025-04-01

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.

Examples:

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

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

Body

application/json

offering_id

string

required

Examples:

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

currency_code

string

required

Required string length: 3

metadata

object

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.

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.

Examples:

"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.

Examples:

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

purchase.onetime_offering_id

string | null

required

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

Examples:

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

purchase.purchased_at

string | null

required

The time the purchase completed.

Examples:

"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.

Examples:

"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.

Examples:

"The Leek - 24 Hours Time Pass"

"1 Month Subscription"

purchase.price

object

required

An amount of money

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

purchase.entitlement_status

object | null

required

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

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

object | null

required

Details of what to do next to complete pending purchases

Retrieve site Retrieve a one-time offering

{
  "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": "The Leek - 24 Hours Time Pass",
    "price": {
      "amount": 50,
      "currency": {
        "code": "USD",
        "name": "US Dollar",
        "symbol": "$",
        "base_unit": 100
      }
    },
    "status": "completed",
    "metadata": {},
    "entitlement_status": {
      "content_key": "site.cf637646-71a4-430d-aaea-a66f1a48a83c",
      "has_entitlement": true,
      "expires": "2023-11-07T05:31:56Z",
      "recurs_at": "2023-11-07T05:31:56Z"
    }
  },
  "action_required": true,
  "action_required_details": {
    "next": "https://checkout.supertab.co?tab_id=tab.13de9ebb-83bd-4aeb-80aa-6f2a21c1be69",
    "reason": "Payment required to complete purchase"
  }
}

Introduction

Reference

Guides

Endpoints

Required Scopes

Headers

Body

Response

Introduction

Reference

Guides

Endpoints

​Required Scopes

Headers

Body

Response

Required Scopes