Create New One-Time Offering

POST

onetime_offerings

{
  "id": "onetime_offering.61a54647-d5d7-44c4-b56c-d5b073759628",
  "status": "new",
  "metadata": {},
  "items": [
    {
      "id": "onetime_offering_item.94703e8a-0352-444d-b78d-d5a347a8e09d",
      "price": {
        "amount": 50,
        "currency": {
          "code": "USD",
          "name": "US Dollar",
          "symbol": "$",
          "base_unit": 100
        }
      },
      "description": "<string>",
      "metadata": {},
      "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"
        }
      }
    }
  ],
  "price": {
    "amount": 50,
    "currency": {
      "code": "USD",
      "name": "US Dollar",
      "symbol": "$",
      "base_unit": 100
    }
  }
}

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 Merchant 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

currency_code

string

required

Required string length: 3

items

object[]

required

metadata

object

Response

201

application/json

Successful Response

string

required

Example:

"onetime_offering.61a54647-d5d7-44c4-b56c-d5b073759628"

status

enum<string>

required

The status of the one-time offering based on the fact of purchase.

It may be new, a purchase pending or a purchase completed.

Only status purchasing_completed means a payment for the one-time offering purchase has been successfully processed.

Available options:

new,

purchasing_completed,

purchasing_pending,

purchasing_abandoned,

expired

metadata

object

required

Any additional information about this one-time offering.

items

object[]

required

A list of items that belong to this one-time offering.

items.id

string

required

Example:

"onetime_offering_item.94703e8a-0352-444d-b78d-d5a347a8e09d"

items.price

object

required

Price of this single one-time offering item.

items.description

string

required

Description of the one-time offering item provided at the time of creation.

items.metadata

object

required

Any additional information about this one-time offering item.

items.purchase

object | null

required

Purchase created as a result of purchasing this offering.

A null value means the status of the corresponding one-time offering is still 'NEW' and a purchasing event has not yet happened.

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

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

items.purchase.onetime_offering_id

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

items.purchase.purchased_at

string | null

required

The time the purchase completed.

Example:

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

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

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

items.purchase.price

object

required

An amount of money

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

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

items.purchase.entitlement_status

object | null

required

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

price

object

required

The price of this one-time offering combining all the one-time offering items' prices. It is always created on the fly based on the provided information when creating a one-time offering.

Versioning & Changes Retrieve a One-Time Offering

{
  "id": "onetime_offering.61a54647-d5d7-44c4-b56c-d5b073759628",
  "status": "new",
  "metadata": {},
  "items": [
    {
      "id": "onetime_offering_item.94703e8a-0352-444d-b78d-d5a347a8e09d",
      "price": {
        "amount": 50,
        "currency": {
          "code": "USD",
          "name": "US Dollar",
          "symbol": "$",
          "base_unit": 100
        }
      },
      "description": "<string>",
      "metadata": {},
      "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"
        }
      }
    }
  ],
  "price": {
    "amount": 50,
    "currency": {
      "code": "USD",
      "name": "US Dollar",
      "symbol": "$",
      "base_unit": 100
    }
  }
}

Reference

Endpoints

Create New One-Time Offering

Authorizations

Headers

Body

Response