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.

POST /purchases/offerings

Error

A valid request URL is required to generate request examples

201

{
  "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"
    }
  },
  "action_required": true,
  "action_required_details": {
    "next": "<string>",
    "reason": "<string>"
  }
}

{
  "error": {
    "message": "Cannot open a tab in the given currency. Check allowed currency with 'Get Current User' endpoint | Recurring Sales Model is not supported in test mode. | 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": "tab_currency_not_allowed | recurring_sales_model_not_supported_for_test_clients | 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 | Merchant does not have access to offering",
    "code": "client_id_mismatch | missing_or_invalid_x_supertab_client_id | invalid_subject_type | offering_access_not_allowed"
  }
}

{
  "error": {
    "message": "No offering price found",
    "code": "offering_price_not_found"
  }
}

{
  "error": {
    "message": "Purchases are not enabled for the merchant | The purchase's currency does not match the tab's currency",
    "code": "purchases_not_enabled_for_merchant | currency_mismatch_error"
  }
}

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

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.

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

offering_id · string<tagged_id> · required

Example:

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

currency_code · string · required

Required string length: 3

metadata · Metadata · object

Show child attributes

Response

201

application/json

Successful Response

purchase · 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

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 | null · required

Details of what to do next to complete pending purchases

Show child attributes