Create New One-Time Offering

Creates a onetime offering.

POST /onetime_offerings

Error

A valid request URL is required to generate request examples

201

{
  "id": "<string>",
  "metadata": {},
  "items": [
    {
      "id": "<string>",
      "price": {
        "amount": 123,
        "currency": {
          "code": "<string>",
          "name": "<string>",
          "symbol": "<string>",
          "base_unit": 123
        }
      },
      "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": "<string>",
        "price": {
          "amount": 123,
          "currency": {
            "code": "<string>",
            "name": "<string>",
            "symbol": "<string>",
            "base_unit": 123
          }
        },
        "metadata": {},
        "entitlement_status": {
          "content_key": "<string>",
          "has_entitlement": true,
          "expires": "2023-11-07T05:31:56Z",
          "recurs_at": "2023-11-07T05:31:56Z"
        }
      }
    }
  ],
  "price": {
    "amount": 123,
    "currency": {
      "code": "<string>",
      "name": "<string>",
      "symbol": "<string>",
      "base_unit": 123
    }
  }
}

{
  "error": {
    "message": "Dynamic message depending on how the price is wrong | The given currency is not enabled for sales | The given currency is not supported by the system",
    "code": "invalid_price | currency_not_enabled | currency_not_supported"
  }
}

{
  "error": {
    "message": "Invalid authentication credentials",
    "code": "invalid_credentials"
  }
}

{
  "error": {
    "message": "The Bearer token does not match the x-supertab-client-id header | Missing or invalid x-supertab-client-id | Invalid subject type {request_subject_type} found, {expected_token_type} expected",
    "code": "client_id_mismatch | missing_or_invalid_x_supertab_client_id | invalid_subject_type"
  }
}

{
  "error": {
    "message": "Purchases are not enabled for the merchant",
    "code": "purchases_not_enabled_for_merchant"
  }
}

{
  "error": [
    {
      "code": "validation_error",
      "message": "Validation Error",
      "errors": [
        {
          "attribute": "query -> subject",
          "code": "missing",
          "message": "field required"
        }
      ]
    }
  ]
}

Required Scopes

mapi:write - Write access to Merchant API resources

Authorizations

Authorization · string · header · required

Supertab OAuth2 flow for MAPI. See Authentication.

Headers

x-api-version · string<date> · default: 2025-04-01

The version of the Merchant 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.

Examples:

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

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

Body

application/json

currency_code · string · required

Required string length: 3

items · CreateOnetimeOfferingItemRequest · object[] · required

Show child attributes

metadata · Metadata · object

Show child attributes

Response

201

application/json

Successful Response

id · string<tagged_id> · 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 · Metadata · object · required

Any additional information about this one-time offering.

Show child attributes

items · OnetimeOfferingItem · object[] · required

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

Show child attributes

price · 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.

Show child attributes