{ "openapi": "3.1.0", "info": { "title": "FastAPI", "version": "2025-04-01" }, "servers": [ { "url": "/capi" } ], "paths": { "/customers/me": { "get": { "tags": [ "Customer" ], "summary": "Retrieve the current customer.", "description": "Retrieve the current customer.\n\nIf the user is authenticated, retrieve the customer's current tab.\n\nFor unauthenticated requests, retrieve a predicted currency and tab limit based on the user's location.", "operationId": "retrieve-customer", "security": [ { "oauth": [ "capi:read" ] } ], "parameters": [ { "name": "x-api-version", "in": "header", "required": false, "schema": { "type": "string", "format": "date", "title": "Customer API version", "description": "The version of the Customer API you are using.", "default": "2025-04-01" }, "description": "The version of the Customer API you are using.", "examples": { "default": { "value": "2025-04-01" } } }, { "name": "x-supertab-client-id", "in": "header", "required": true, "schema": { "title": "Client Id", "type": "string", "format": "tagged_id", "examples": [ "live_client.4df706b5-297a-49c5-a4cd-2a10eca12ff9", "test_client.4df706b5-297a-49c5-a4cd-2a10eca12ff9" ] }, "description": "Your Client ID with Supertab. Used to identify the website on which Customer is making a Purchase." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "A codename for the error" }, "message": { "type": "string", "description": "A human-readable error message" } } } }, "type": "object", "title": "Forbidden" }, "example": { "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 | Forbidden", "code": "client_id_mismatch | missing_or_invalid_x_supertab_client_id | invalid_subject_type | forbidden" } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "A codename for the error" }, "message": { "type": "string", "description": "A human-readable error message" } } } }, "type": "object", "title": "Not Found" }, "example": { "error": { "message": "User not found", "code": "user_not_found" } } } }, "description": "Not Found" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "A codename for the error" }, "message": { "type": "string", "description": "A human-readable error message" } } } }, "type": "object", "title": "Unauthorized" }, "example": { "error": { "message": "Invalid authentication credentials", "code": "invalid_credentials" } } } }, "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "properties": { "error": { "type": "array", "description": "A general error code and message accompanied by the list of attributes that failed validation", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "A short generic error code" }, "message": { "type": "string", "description": "A human-readable error message" }, "errors": { "type": "array", "description": "A list of attributes that failed validation", "items": { "type": "object", "properties": { "attribute": { "type": "string", "description": "The path to the attribute that failed validation" }, "code": { "type": "string", "description": "An error code of this attribute's specific validation error" }, "message": { "type": "string", "description": "A human-readable error message of this attribute's specific validation error" } } } } } } } }, "type": "object", "title": "Validation Error" }, "example": { "error": [ { "code": "validation_error", "message": "Validation Error", "errors": [ { "attribute": "query -> subject", "code": "missing", "message": "field required" } ] } ] } } } } } } }, "/entitlements/{content_key}": { "get": { "tags": [ "Customer" ], "summary": "Retrieve entitlement status", "description": "Retrieves the entitlement status for the given content key.", "operationId": "check-user-entitlement", "security": [ { "oauth": [ "capi:read" ] } ], "parameters": [ { "name": "content_key", "in": "path", "required": true, "schema": { "type": "string", "title": "content_key", "description": "The content_key to check access for", "examples": [ "site.cf637646-71a4-430d-aaea-a66f1a48a83c" ] }, "description": "The content_key to check access for", "example": {} }, { "name": "x-api-version", "in": "header", "required": false, "schema": { "type": "string", "format": "date", "title": "Customer API version", "description": "The version of the Customer API you are using.", "default": "2025-04-01" }, "description": "The version of the Customer API you are using.", "examples": { "default": { "value": "2025-04-01" } } }, { "name": "x-supertab-client-id", "in": "header", "required": true, "schema": { "title": "Client Id", "type": "string", "format": "tagged_id", "examples": [ "live_client.4df706b5-297a-49c5-a4cd-2a10eca12ff9", "test_client.4df706b5-297a-49c5-a4cd-2a10eca12ff9" ] }, "description": "Your Client ID with Supertab. Used to identify the website on which Customer is making a Purchase." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitlementStatus" } } } }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "A codename for the error" }, "message": { "type": "string", "description": "A human-readable error message" } } } }, "type": "object", "title": "Forbidden" }, "example": { "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 | Forbidden", "code": "client_id_mismatch | missing_or_invalid_x_supertab_client_id | invalid_subject_type | forbidden" } } } }, "description": "Forbidden" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "A codename for the error" }, "message": { "type": "string", "description": "A human-readable error message" } } } }, "type": "object", "title": "Unauthorized" }, "example": { "error": { "message": "Invalid authentication credentials", "code": "invalid_credentials" } } } }, "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "properties": { "error": { "type": "array", "description": "A general error code and message accompanied by the list of attributes that failed validation", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "A short generic error code" }, "message": { "type": "string", "description": "A human-readable error message" }, "errors": { "type": "array", "description": "A list of attributes that failed validation", "items": { "type": "object", "properties": { "attribute": { "type": "string", "description": "The path to the attribute that failed validation" }, "code": { "type": "string", "description": "An error code of this attribute's specific validation error" }, "message": { "type": "string", "description": "A human-readable error message of this attribute's specific validation error" } } } } } } } }, "type": "object", "title": "Validation Error" }, "example": { "error": [ { "code": "validation_error", "message": "Validation Error", "errors": [ { "attribute": "query -> subject", "code": "missing", "message": "field required" } ] } ] } } } } } } }, "/onetime_offerings/{onetime_offering_id}": { "get": { "tags": [ "Customer" ], "summary": "Retrieve a one-time offering", "description": "Retrieves a One-Time Offering. Usually a One-Time Offering would be created on the backend using\nthe Merchant API in order that a customer can immediately retrieve and purchase it using the Customer API.", "operationId": "retrieve-onetime-offering", "security": [ { "oauth": [ "capi:read" ] } ], "parameters": [ { "name": "onetime_offering_id", "in": "path", "required": true, "schema": { "type": "string", "title": "onetime_offering_id", "description": "An ID of a One-time Offering", "examples": [ "onetime_offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9" ], "format": "tagged_id" }, "description": "An ID of a One-time Offering" }, { "name": "x-api-version", "in": "header", "required": false, "schema": { "type": "string", "format": "date", "title": "Customer API version", "description": "The version of the Customer API you are using.", "default": "2025-04-01" }, "description": "The version of the Customer API you are using.", "examples": { "default": { "value": "2025-04-01" } } }, { "name": "x-supertab-client-id", "in": "header", "required": true, "schema": { "title": "Client Id", "type": "string", "format": "tagged_id", "examples": [ "live_client.4df706b5-297a-49c5-a4cd-2a10eca12ff9", "test_client.4df706b5-297a-49c5-a4cd-2a10eca12ff9" ] }, "description": "Your Client ID with Supertab. Used to identify the website on which Customer is making a Purchase." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnetimeOffering" } } } }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "A codename for the error" }, "message": { "type": "string", "description": "A human-readable error message" } } } }, "type": "object", "title": "Not Found" }, "example": { "error": { "message": "One-time offering not found", "code": "onetime_offering_not_found" } } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "A codename for the error" }, "message": { "type": "string", "description": "A human-readable error message" } } } }, "type": "object", "title": "Conflict" }, "example": { "error": { "message": "This one-time offering has expired | This one-time offering was already consumed", "code": "onetime_offering_expired | onetime_offering_already_consumed" } } } }, "description": "Conflict" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "A codename for the error" }, "message": { "type": "string", "description": "A human-readable error message" } } } }, "type": "object", "title": "Forbidden" }, "example": { "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 | Forbidden", "code": "client_id_mismatch | missing_or_invalid_x_supertab_client_id | invalid_subject_type | forbidden" } } } }, "description": "Forbidden" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "A codename for the error" }, "message": { "type": "string", "description": "A human-readable error message" } } } }, "type": "object", "title": "Unauthorized" }, "example": { "error": { "message": "Invalid authentication credentials", "code": "invalid_credentials" } } } }, "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "properties": { "error": { "type": "array", "description": "A general error code and message accompanied by the list of attributes that failed validation", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "A short generic error code" }, "message": { "type": "string", "description": "A human-readable error message" }, "errors": { "type": "array", "description": "A list of attributes that failed validation", "items": { "type": "object", "properties": { "attribute": { "type": "string", "description": "The path to the attribute that failed validation" }, "code": { "type": "string", "description": "An error code of this attribute's specific validation error" }, "message": { "type": "string", "description": "A human-readable error message of this attribute's specific validation error" } } } } } } } }, "type": "object", "title": "Validation Error" }, "example": { "error": [ { "code": "validation_error", "message": "Validation Error", "errors": [ { "attribute": "query -> subject", "code": "missing", "message": "field required" } ] } ] } } } } } } }, "/purchases/offerings": { "post": { "tags": [ "Customer" ], "summary": "Purchase an offering", "description": "Purchases a pre-defined offering by placing it on the customer's current tab.\n\nDepending on the customer's existing relationship with Supertab they may be required to make purchases\nin a specific currency. Check /customers/me for information on what currency the customer makes purchases in.\n\nIf the new purchase causes the tab to become full a payment is required before the purchase will complete.", "operationId": "purchase-offering", "security": [ { "oauth": [ "capi:write" ] } ], "parameters": [ { "name": "x-api-version", "in": "header", "required": false, "schema": { "type": "string", "format": "date", "title": "Customer API version", "description": "The version of the Customer API you are using.", "default": "2025-04-01" }, "description": "The version of the Customer API you are using.", "examples": { "default": { "value": "2025-04-01" } } }, { "name": "x-supertab-client-id", "in": "header", "required": true, "schema": { "title": "Client Id", "type": "string", "format": "tagged_id", "examples": [ "live_client.4df706b5-297a-49c5-a4cd-2a10eca12ff9", "test_client.4df706b5-297a-49c5-a4cd-2a10eca12ff9" ] }, "description": "Your Client ID with Supertab. Used to identify the website on which Customer is making a Purchase." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseOfferingRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfferingPurchaseResult" } } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "A codename for the error" }, "message": { "type": "string", "description": "A human-readable error message" } } } }, "type": "object", "title": "Bad Request" }, "example": { "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" } } } }, "description": "Bad Request" }, "409": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "A codename for the error" }, "message": { "type": "string", "description": "A human-readable error message" } } } }, "type": "object", "title": "Conflict" }, "example": { "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" } } } }, "description": "Conflict" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "A codename for the error" }, "message": { "type": "string", "description": "A human-readable error message" } } } }, "type": "object", "title": "Forbidden" }, "example": { "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" } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "A codename for the error" }, "message": { "type": "string", "description": "A human-readable error message" } } } }, "type": "object", "title": "Not Found" }, "example": { "error": { "message": "No offering price found", "code": "offering_price_not_found" } } } }, "description": "Not Found" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "A codename for the error" }, "message": { "type": "string", "description": "A human-readable error message" } } } }, "type": "object", "title": "Unauthorized" }, "example": { "error": { "message": "Invalid authentication credentials", "code": "invalid_credentials" } } } }, "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "properties": { "error": { "type": "array", "description": "A general error code and message accompanied by the list of attributes that failed validation", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "A short generic error code" }, "message": { "type": "string", "description": "A human-readable error message" }, "errors": { "type": "array", "description": "A list of attributes that failed validation", "items": { "type": "object", "properties": { "attribute": { "type": "string", "description": "The path to the attribute that failed validation" }, "code": { "type": "string", "description": "An error code of this attribute's specific validation error" }, "message": { "type": "string", "description": "A human-readable error message of this attribute's specific validation error" } } } } } } } }, "type": "object", "title": "Validation Error" }, "example": { "error": [ { "code": "validation_error", "message": "Validation Error", "errors": [ { "attribute": "query -> subject", "code": "missing", "message": "field required" } ] } ] } } } } } } }, "/purchases/onetime_offerings": { "post": { "tags": [ "Customer" ], "summary": "Purchase a one-time offering", "description": "Purchases a one-time offering by placing it on the customer's current tab.\n\nIf the new purchase(s) causes the tab to become full a payment is required before the purchase(s) will complete.", "operationId": "purchase-onetime-offering", "security": [ { "oauth": [ "capi:write" ] } ], "parameters": [ { "name": "x-api-version", "in": "header", "required": false, "schema": { "type": "string", "format": "date", "title": "Customer API version", "description": "The version of the Customer API you are using.", "default": "2025-04-01" }, "description": "The version of the Customer API you are using.", "examples": { "default": { "value": "2025-04-01" } } }, { "name": "x-supertab-client-id", "in": "header", "required": true, "schema": { "title": "Client Id", "type": "string", "format": "tagged_id", "examples": [ "live_client.4df706b5-297a-49c5-a4cd-2a10eca12ff9", "test_client.4df706b5-297a-49c5-a4cd-2a10eca12ff9" ] }, "description": "Your Client ID with Supertab. Used to identify the website on which Customer is making a Purchase." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurchaseOnetimeOfferingRequest" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnetimeOfferingPurchaseResult" } } } }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "A codename for the error" }, "message": { "type": "string", "description": "A human-readable error message" } } } }, "type": "object", "title": "Bad Request" }, "example": { "error": { "message": "The given currency is not supported by the system", "code": "currency_not_supported" } } } }, "description": "Bad Request" }, "409": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "A codename for the error" }, "message": { "type": "string", "description": "A human-readable error message" } } } }, "type": "object", "title": "Conflict" }, "example": { "error": { "message": "This one-time offering was already consumed | The amount of the Pay-Now tab is below the allowed limit | Purchases are not enabled for the merchant", "code": "onetime_offering_already_consumed | pay_now_tab_amount_below_limit | purchases_not_enabled_for_merchant" } } } }, "description": "Conflict" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "A codename for the error" }, "message": { "type": "string", "description": "A human-readable error message" } } } }, "type": "object", "title": "Not Found" }, "example": { "error": { "message": "One-time offering not found", "code": "onetime_offering_not_found" } } } }, "description": "Not Found" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "A codename for the error" }, "message": { "type": "string", "description": "A human-readable error message" } } } }, "type": "object", "title": "Unauthorized" }, "example": { "error": { "message": "Invalid authentication credentials", "code": "invalid_credentials" } } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "A codename for the error" }, "message": { "type": "string", "description": "A human-readable error message" } } } }, "type": "object", "title": "Forbidden" }, "example": { "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" } } } }, "description": "Forbidden" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "properties": { "error": { "type": "array", "description": "A general error code and message accompanied by the list of attributes that failed validation", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "A short generic error code" }, "message": { "type": "string", "description": "A human-readable error message" }, "errors": { "type": "array", "description": "A list of attributes that failed validation", "items": { "type": "object", "properties": { "attribute": { "type": "string", "description": "The path to the attribute that failed validation" }, "code": { "type": "string", "description": "An error code of this attribute's specific validation error" }, "message": { "type": "string", "description": "A human-readable error message of this attribute's specific validation error" } } } } } } } }, "type": "object", "title": "Validation Error" }, "example": { "error": [ { "code": "validation_error", "message": "Validation Error", "errors": [ { "attribute": "query -> subject", "code": "missing", "message": "field required" } ] } ] } } } } } } }, "/purchases/{purchase_id}": { "get": { "tags": [ "Customer" ], "summary": "Retrieve a purchase", "description": "Retrieve a purchase\n\nYou may use this endpoint to poll pending purchases when you expect them to complete.", "operationId": "retrieve-purchase", "security": [ { "oauth": [ "capi:read" ] } ], "parameters": [ { "name": "purchase_id", "in": "path", "required": true, "schema": { "type": "string", "title": "purchase_id", "description": "An ID of a Purchase", "examples": [ "purchase.4df706b5-297a-49c5-a4cd-2a10eca12ff9" ], "format": "tagged_id" }, "description": "An ID of a Purchase" }, { "name": "x-api-version", "in": "header", "required": false, "schema": { "type": "string", "format": "date", "title": "Customer API version", "description": "The version of the Customer API you are using.", "default": "2025-04-01" }, "description": "The version of the Customer API you are using.", "examples": { "default": { "value": "2025-04-01" } } }, { "name": "x-supertab-client-id", "in": "header", "required": true, "schema": { "title": "Client Id", "type": "string", "format": "tagged_id", "examples": [ "live_client.4df706b5-297a-49c5-a4cd-2a10eca12ff9", "test_client.4df706b5-297a-49c5-a4cd-2a10eca12ff9" ] }, "description": "Your Client ID with Supertab. Used to identify the website on which Customer is making a Purchase." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Purchase" } } } }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "A codename for the error" }, "message": { "type": "string", "description": "A human-readable error message" } } } }, "type": "object", "title": "Forbidden" }, "example": { "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 | Forbidden", "code": "client_id_mismatch | missing_or_invalid_x_supertab_client_id | invalid_subject_type | forbidden" } } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "A codename for the error" }, "message": { "type": "string", "description": "A human-readable error message" } } } }, "type": "object", "title": "Not Found" }, "example": { "error": { "message": "Purchase not found", "code": "purchase_not_found" } } } }, "description": "Not Found" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "A codename for the error" }, "message": { "type": "string", "description": "A human-readable error message" } } } }, "type": "object", "title": "Unauthorized" }, "example": { "error": { "message": "Invalid authentication credentials", "code": "invalid_credentials" } } } }, "description": "Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "properties": { "error": { "type": "array", "description": "A general error code and message accompanied by the list of attributes that failed validation", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "A short generic error code" }, "message": { "type": "string", "description": "A human-readable error message" }, "errors": { "type": "array", "description": "A list of attributes that failed validation", "items": { "type": "object", "properties": { "attribute": { "type": "string", "description": "The path to the attribute that failed validation" }, "code": { "type": "string", "description": "An error code of this attribute's specific validation error" }, "message": { "type": "string", "description": "A human-readable error message of this attribute's specific validation error" } } } } } } } }, "type": "object", "title": "Validation Error" }, "example": { "error": [ { "code": "validation_error", "message": "Validation Error", "errors": [ { "attribute": "query -> subject", "code": "missing", "message": "field required" } ] } ] } } } } } } }, "/site": { "get": { "tags": [ "Customer" ], "summary": "Retrieve inventory available for sale.", "description": "Retrieves information about the current site, identified by the Client ID.\nThe response contains information about all the available offerings, configuration for the experiences\n(e.g. paygates and buttons), and some other metadata.", "operationId": "retrieve-site", "security": [ { "oauth": [ "capi:read" ] } ], "parameters": [ { "name": "x-api-version", "in": "header", "required": false, "schema": { "type": "string", "format": "date", "title": "Customer API version", "description": "The version of the Customer API you are using.", "default": "2025-04-01" }, "description": "The version of the Customer API you are using.", "examples": { "default": { "value": "2025-04-01" } } }, { "name": "x-supertab-client-id", "in": "header", "required": true, "schema": { "title": "Client Id", "type": "string", "format": "tagged_id", "examples": [ "live_client.4df706b5-297a-49c5-a4cd-2a10eca12ff9", "test_client.4df706b5-297a-49c5-a4cd-2a10eca12ff9" ] }, "description": "Your Client ID with Supertab. Used to identify the website on which Customer is making a Purchase." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Site" } } } }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "A codename for the error" }, "message": { "type": "string", "description": "A human-readable error message" } } } }, "type": "object", "title": "Not Found" }, "example": { "error": { "message": "Currency not found | No offering price found | Site not found.", "code": "currency_not_found | offering_price_not_found | site_not_found" } } } }, "description": "Not Found" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "A codename for the error" }, "message": { "type": "string", "description": "A human-readable error message" } } } }, "type": "object", "title": "Unauthorized" }, "example": { "error": { "message": "Invalid authentication credentials", "code": "invalid_credentials" } } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "A codename for the error" }, "message": { "type": "string", "description": "A human-readable error message" } } } }, "type": "object", "title": "Forbidden" }, "example": { "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" } } } }, "description": "Forbidden" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "properties": { "error": { "type": "array", "description": "A general error code and message accompanied by the list of attributes that failed validation", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "A short generic error code" }, "message": { "type": "string", "description": "A human-readable error message" }, "errors": { "type": "array", "description": "A list of attributes that failed validation", "items": { "type": "object", "properties": { "attribute": { "type": "string", "description": "The path to the attribute that failed validation" }, "code": { "type": "string", "description": "An error code of this attribute's specific validation error" }, "message": { "type": "string", "description": "A human-readable error message of this attribute's specific validation error" } } } } } } } }, "type": "object", "title": "Validation Error" }, "example": { "error": [ { "code": "validation_error", "message": "Validation Error", "errors": [ { "attribute": "query -> subject", "code": "missing", "message": "field required" } ] } ] } } } } } } } }, "components": { "schemas": { "ActionRequiredDetails": { "properties": { "next": { "type": "string", "title": "Next", "description": "Forward the user here to start e.g. a checkout session which should then be opened in a pop-up window.", "examples": [ "https://checkout.supertab.co?tab_id=tab.13de9ebb-83bd-4aeb-80aa-6f2a21c1be69" ] }, "reason": { "type": "string", "title": "Reason", "description": "Describes why action should be taken", "examples": [ "Payment required to complete purchase", "Before you can make new purchases, payment is required" ] } }, "type": "object", "required": [ "next", "reason" ], "title": "ActionRequiredDetails", "description": "Details of what to do next to complete pending purchases" }, "Currency": { "properties": { "code": { "type": "string", "title": "Code", "description": "ISO2417 currency code", "examples": [ "USD" ] }, "name": { "type": "string", "title": "Name", "description": "Full name", "examples": [ "US Dollar" ] }, "symbol": { "type": "string", "title": "Symbol", "description": "Unicode currency symbol", "examples": [ "$" ] }, "base_unit": { "type": "integer", "title": "Base Unit", "description": "The relationship between the currency's minor and major unit.\n\nFor most currencies including USD & EUR this will be `100`. For currencies which do not use decimals (e.g JPY) this will `1`", "examples": [ 100 ] } }, "type": "object", "required": [ "code", "name", "symbol", "base_unit" ], "title": "Currency", "description": "Supertab is available in many currencies." }, "Customer": { "properties": { "authenticated": { "type": "boolean", "title": "Authenticated", "description": "This represents either an authenticated user or location-based adjacent details inferred by Supertab" }, "user": { "anyOf": [ { "$ref": "#/components/schemas/User" }, { "type": "null" } ], "description": "The user data of the authenticated user. This will be `null` for unauthenticated users" }, "tab": { "$ref": "#/components/schemas/Tab", "description": "The Tab is at the heart of Supertab. It aggregates purchases customers make and tracks when they are required to make payment.\n\nWhile the Tab powers much of our underlying behaviour you will not often directly interact with it." } }, "type": "object", "required": [ "authenticated", "user", "tab" ], "title": "Customer" }, "Entitlement": { "properties": { "duration": { "type": "string", "maxLength": 9, "minLength": 2, "pattern": "^\\d*[s|m|h|d|w|M|y]$", "title": "Duration", "description": "Duration of the timepass, as `{length}{unit}`.\n\nPossible units:\n\n| **Directive** | **Meaning** |\n| ------------- | ------------- |\n| y | years |\n| M | months |\n| w | weeks |\n| d | days |\n| h | hours |\n| m | minutes |\n| s | seconds |\n\nExamples:\n\n```\n{\n // 1 year\n \"duration\": \"1y\",\n // 2 months\n \"duration\": \"2M\",\n // 3 weeks\n \"duration\": \"3w\",\n // 4 days\n \"duration\": \"4d\",\n // 5 hours\n \"duration\": \"5h\",\n // 6 minutes\n \"duration\": \"6m\",\n // 7 seconds\n \"duration\": \"7s\"\n}\n```" }, "is_recurring": { "type": "boolean", "title": "Is Recurring", "description": "Is entitlement sold on a recurring (subscription) basis" }, "content_key": { "type": "string", "title": "Content Key", "description": "The content key being purchased, if you have chosen to have Supertab manage customer entitlement for you." } }, "type": "object", "required": [ "duration", "is_recurring", "content_key" ], "title": "Entitlement", "description": "Specifies the nature and duration of purchased entitlement. Where you have chosen to have Supertab manage\nentitlements for you, customer's purchasing such an offering will be granted access to the content\nassociated with the offering for the length of time specified." }, "EntitlementStatus": { "properties": { "content_key": { "type": "string", "title": "Content Key", "description": "The content_key being checked", "examples": [ "site.cf637646-71a4-430d-aaea-a66f1a48a83c" ] }, "has_entitlement": { "type": "boolean", "title": "Has Entitlement", "description": "If the customer has access to this content" }, "expires": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Expires", "description": "When the customer's access will expire" }, "recurs_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Recurs At", "description": "If this access is a result of a subscription, the time the subscription will renew unless cancelled by the customer." } }, "type": "object", "required": [ "content_key", "has_entitlement", "expires", "recurs_at" ], "title": "EntitlementStatus", "description": "A customer's entitlement status to a given content_key" }, "Experience": { "properties": { "id": { "type": "string", "title": "Id", "description": "The experience ID", "examples": [ "experience.cf637646-71a4-430d-aaea-a66f1a48a83c" ] }, "name": { "type": "string", "title": "Name", "description": "The experience name" }, "type": { "$ref": "#/components/schemas/ExperienceType", "description": "The type of the experience, used by Supertab to determine how to display the experience UI" }, "offerings": { "items": { "type": "string", "format": "tagged_id", "examples": [ "offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9" ] }, "type": "array", "title": "Offerings", "description": "List of offering IDs attached to this experience.\n\nThis includes all possible offerings sold by this experience, details of how to display these to customers are found in `ui_config`." }, "configuration": { "$ref": "#/components/schemas/ExperienceConfiguration" } }, "type": "object", "required": [ "id", "name", "type", "offerings", "configuration" ], "title": "Experience" }, "ExperienceConfiguration": { "properties": { "ui_config": { "additionalProperties": true, "type": "object", "title": "Ui Config", "description": "Used by Supertab to control look, feel & branding" }, "on_close": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "On Close", "description": "Used by Supertab to control experience dismissal behaviour" }, "upsells": { "items": { "$ref": "#/components/schemas/Upsell" }, "type": "array", "title": "Upsells", "default": [], "deprecated": true } }, "type": "object", "required": [ "ui_config", "on_close", "upsells" ], "title": "ExperienceConfiguration" }, "ExperienceType": { "type": "string", "enum": [ "basic_paygate", "basic_supertab_button", "rich_paygate", "rich_supertab_button" ], "title": "ExperienceType" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "Offering": { "properties": { "id": { "type": "string", "title": "Id", "examples": [ "offering.cf637646-71a4-430d-aaea-a66f1a48a83c" ] }, "description": { "type": "string", "title": "Description", "description": "Customer facing name for the offering.", "examples": [ "1 week access to theleek.com" ] }, "entitlement_details": { "anyOf": [ { "$ref": "#/components/schemas/Entitlement" }, { "type": "null" } ], "description": "Specifies the nature and duration of purchased entitlement.\n\nWhere you have chosen to have Supertab manage entitlements for you, customer's purchasing such an offering will be granted entitlement to the content associated with the offering for the length of time specified.", "examples": [ { "content_key": "site.cf637646-71a4-430d-aaea-a66f1a48a83c", "duration": "1w", "is_recurring": false }, { "content_key": "site.cf637646-71a4-430d-aaea-a66f1a48a83c", "duration": "1M", "is_recurring": true } ] }, "price": { "$ref": "#/components/schemas/Price", "description": "The price of this offering.\n\nThe available price is customer-aware when possible, Supertab restricts some customers to certain currencies depending on their location and prior interactions with Supertab." }, "is_pay_now": { "type": "boolean", "title": "Is Pay Now", "description": "Offering requires upfront payment, customer will be taken to checkout immediately on purchase.\n\nUsed to control Call To Action during purchase confirmation." }, "guest_checkout_available": { "type": "boolean", "title": "Guest Checkout Available", "description": "Whether this offering is eligible for guest checkout in the displayed currency. When True, the frontend can initiate a guest checkout session for this offering." } }, "type": "object", "required": [ "id", "description", "entitlement_details", "price", "is_pay_now", "guest_checkout_available" ], "title": "Offering" }, "OfferingPurchaseResult": { "properties": { "purchase": { "anyOf": [ { "$ref": "#/components/schemas/Purchase" }, { "type": "null" } ], "description": "Purchase created as a result of purchasing this offering.\n\nA null value means no purchase was created, see action_required_details for the reason." }, "action_required": { "type": "boolean", "title": "Action Required", "description": "Determines if further interaction with the customer required on Supertab in order to complete this purchase.\n\nMost commonly this will be when Supertab required a customer to make a payment before continuing." }, "action_required_details": { "anyOf": [ { "$ref": "#/components/schemas/ActionRequiredDetails" }, { "type": "null" } ], "description": "Details of what to do next to complete pending purchases" } }, "type": "object", "required": [ "purchase", "action_required", "action_required_details" ], "title": "OfferingPurchaseResult" }, "OnetimeOffering": { "properties": { "id": { "type": "string", "format": "tagged_id", "title": "Id", "examples": [ "onetime_offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9" ] }, "items": { "items": { "$ref": "#/components/schemas/OnetimeOfferingItem" }, "type": "array", "title": "Items" }, "price": { "$ref": "#/components/schemas/Price" } }, "type": "object", "required": [ "id", "items", "price" ], "title": "OnetimeOffering", "description": "Represents a one-time offering." }, "OnetimeOfferingItem": { "properties": { "id": { "type": "string", "format": "tagged_id", "title": "Id", "examples": [ "onetime_offering_item.4df706b5-297a-49c5-a4cd-2a10eca12ff9" ] }, "price": { "$ref": "#/components/schemas/Price" }, "description": { "type": "string", "title": "Description" }, "metadata": { "additionalProperties": { "anyOf": [ { "type": "number" }, { "type": "boolean" }, { "type": "integer" }, { "type": "string" }, { "type": "null" } ] }, "type": "object", "title": "Metadata", "default": {} } }, "type": "object", "required": [ "id", "price", "description", "metadata" ], "title": "OnetimeOfferingItem", "description": "Represents an item in a one-time offering." }, "OnetimeOfferingPurchaseResult": { "properties": { "purchases": { "anyOf": [ { "items": { "$ref": "#/components/schemas/Purchase" }, "type": "array" }, { "type": "null" } ], "title": "Purchases", "description": "Purchases created as a result of purchasing this one-time offering.\n\nAn empty list means no purchases were created, see action_required_details for the reason." }, "action_required": { "type": "boolean", "title": "Action Required", "description": "Determines if further interaction with the customer required on Supertab in order to complete this purchases.\n\nMost commonly this will be when Supertab required a customer to make a payment before continuing." }, "action_required_details": { "anyOf": [ { "$ref": "#/components/schemas/ActionRequiredDetails" }, { "type": "null" } ], "description": "Details of what to do next to complete pending purchases" } }, "type": "object", "required": [ "purchases", "action_required", "action_required_details" ], "title": "OnetimeOfferingPurchaseResult" }, "Price": { "properties": { "amount": { "type": "integer", "title": "Amount", "description": "Price amount expressed in currency base units", "examples": [ 50 ] }, "currency": { "$ref": "#/components/schemas/Currency", "description": "The price's currency" } }, "type": "object", "required": [ "amount", "currency" ], "title": "Price", "description": "An amount of money" }, "Purchase": { "properties": { "id": { "anyOf": [ { "type": "string", "format": "tagged_id", "examples": [ "purchase.4df706b5-297a-49c5-a4cd-2a10eca12ff9" ] }, { "type": "null" } ], "title": "Id", "description": "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" ] }, "offering_id": { "anyOf": [ { "type": "string", "format": "tagged_id", "examples": [ "offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9" ] }, { "type": "null" } ], "title": "Offering Id", "description": "Which offering was purchased, if this purchase resulted from purchasing a pre-defined offering." }, "onetime_offering_id": { "anyOf": [ { "type": "string", "format": "tagged_id", "examples": [ "onetime_offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9" ] }, { "type": "null" } ], "title": "Onetime Offering Id", "description": "Which one-time offering was purchased, if this purchase resulted from purchasing a one-time offering." }, "purchased_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Purchased At", "description": "The time the purchase completed.", "examples": [ "2025-01-01T12:00:00Z" ] }, "completed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Completed At", "description": "The time the purchase completed.\n\nWhere Supertab requires a payment this will be null until the payment completes.", "examples": [ "2025-01-01T12:00:00Z" ] }, "description": { "type": "string", "title": "Description", "description": "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" ] }, "price": { "$ref": "#/components/schemas/Price" }, "status": { "$ref": "#/components/schemas/PurchaseStatus", "description": "The status of the purchase.\n\nPurchases may be pending or completed.\n\nOnly completed purchases grant access, pending purchases are purchases which require payment before entitlement is granted" }, "metadata": { "additionalProperties": { "anyOf": [ { "type": "number" }, { "type": "boolean" }, { "type": "integer" }, { "type": "string" }, { "type": "null" } ] }, "type": "object", "title": "Metadata", "description": "Freeform metadata associated with the purchase.\n\nThis can be used for e.g associating the purchase with a user identifier in your system", "default": {} }, "entitlement_status": { "anyOf": [ { "$ref": "#/components/schemas/EntitlementStatus" }, { "type": "null" } ], "description": "The customer's access (if any) as a result of this purchase" } }, "type": "object", "required": [ "id", "offering_id", "onetime_offering_id", "purchased_at", "completed_at", "description", "price", "status", "metadata", "entitlement_status" ], "title": "Purchase" }, "PurchaseOfferingRequest": { "properties": { "offering_id": { "type": "string", "format": "tagged_id", "title": "Offering Id", "examples": [ "offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9" ] }, "currency_code": { "type": "string", "maxLength": 3, "minLength": 3, "title": "Currency Code" }, "metadata": { "additionalProperties": { "anyOf": [ { "type": "number" }, { "type": "boolean" }, { "type": "integer" }, { "type": "string" }, { "type": "null" } ] }, "type": "object", "title": "Metadata", "default": {} } }, "type": "object", "required": [ "offering_id", "currency_code" ], "title": "PurchaseOfferingRequest" }, "PurchaseOnetimeOfferingRequest": { "properties": { "onetime_offering_id": { "type": "string", "format": "tagged_id", "title": "Onetime Offering Id", "examples": [ "onetime_offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9" ] } }, "type": "object", "required": [ "onetime_offering_id" ], "title": "PurchaseOnetimeOfferingRequest" }, "PurchaseStatus": { "type": "string", "enum": [ "completed", "pending", "abandoned" ], "title": "PurchaseStatus", "description": "We use this enum to represent the status of a purchase.\n\nThe status can be:\n- completed: the purchase was successfully completed\n- pending: the purchase is pending\n- abandoned: the purchase was abandoned\n\nThe logic to determine the status of a purchase is:\n PAY_LATER on Tab -> purchase.status\n PAY_NOW in a paid Tab -> completed\n PAY_NOW in an unpaid Tab -> pending\n\n Abandoned purchases are not being set at the moment.\n Purchases are going to be marked as abandoned when new pending\n purchases are added to the tab." }, "Site": { "properties": { "name": { "type": "string", "title": "Name", "description": "The name of the site" }, "url": { "type": "string", "minLength": 1, "format": "uri", "title": "Url", "description": "URL of the site. Supertab will not authenticate customers unless this matches the domain you are serving from.", "examples": [ "https://supertab.co" ] }, "auth_redirect_uri": { "type": "string", "minLength": 1, "format": "uri", "title": "Auth Redirect Uri", "description": "Passed to Supertab when authenticating customers on this site", "examples": [ "https://signon.supertab.co/auth-proxy" ] }, "logo_url": { "anyOf": [ { "type": "string", "minLength": 1, "format": "uri" }, { "type": "null" } ], "title": "Logo Url", "description": "The URL of the logo for this site provided to Supertab" }, "content_keys": { "items": { "type": "string" }, "type": "array", "title": "Content Keys", "description": "List of content_keys to use when checking entitlement to your site." }, "offerings": { "items": { "$ref": "#/components/schemas/Offering" }, "type": "array", "title": "Offerings", "description": "Offerings are what is available for customers to purchase.\n\nYou can define your available offerings in the [Supertab Business Portal](https://business.supertab.co/)." }, "experiences": { "items": { "$ref": "#/components/schemas/Experience" }, "type": "array", "title": "Experiences", "description": "When using Supertab to manage your sales UI, this list of experiences contains the information we use to display an Experience to your customers." }, "test_mode": { "type": "boolean", "title": "Test Mode", "description": "See Test Mode's [Documentation](https://docs.supertab.co/supertab-experiences/test-mode) for details" }, "white_label": { "type": "boolean", "title": "White Label", "description": "Whether the merchant has the white-label option enabled. When True, Supertab surfaces (paywall, button, checkout) should render the white-labelled version with Supertab branding removed.", "default": false } }, "type": "object", "required": [ "name", "url", "auth_redirect_uri", "logo_url", "content_keys", "offerings", "experiences", "test_mode", "white_label" ], "title": "Site", "description": "A site is any website, SaaS product or any other place you deploy Supertab.\n\nIt is the top level object in your inventory and contains all offerings." }, "Tab": { "properties": { "test_mode": { "type": "boolean", "title": "Test Mode", "description": "Is this a test mode tab.\n\nTest mode tabs grant entitlement as usual but will not result in actual charges to customers. Test mode tabs are generated from test clients." }, "currency": { "$ref": "#/components/schemas/Currency", "description": "The currency of the tab. All purchases on this tab must be made in this currency." }, "total": { "$ref": "#/components/schemas/Price", "description": "The current total value of purchases made on this tab" }, "limit": { "$ref": "#/components/schemas/Price", "description": "The limit which when reached will require the customer to make payment." }, "purchases": { "items": { "$ref": "#/components/schemas/Purchase" }, "type": "array", "title": "Purchases", "description": "Details of what this customer has purchased from your merchant account.\n\nThe purchases of the user that have been made with the other merchants are shown as a single purchase, which accumulates all totals into one and has a `null` value instead of a Purchase ID." } }, "type": "object", "required": [ "test_mode", "currency", "total", "limit", "purchases" ], "title": "Tab", "description": "The Tab is at the heart of Supertab.\nIt aggregates purchases customers make and tracks when they are required to make payment.\n\nWhile the Tab powers much of our underlying behaviour you will not often directly interact with it." }, "Upsell": { "properties": { "main_offering": { "type": "string", "format": "tagged_id", "title": "Main Offering", "examples": [ "offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9" ] }, "upsell_offering": { "type": "string", "format": "tagged_id", "title": "Upsell Offering", "examples": [ "offering.4df706b5-297a-49c5-a4cd-2a10eca12ff9" ] }, "discount": { "type": "number", "title": "Discount" } }, "type": "object", "required": [ "main_offering", "upsell_offering", "discount" ], "title": "Upsell" }, "User": { "properties": { "id": { "type": "string", "format": "tagged_id", "title": "Id", "examples": [ "user.4df706b5-297a-49c5-a4cd-2a10eca12ff9" ] }, "email": { "anyOf": [ { "type": "string", "format": "email" }, { "type": "null" } ], "title": "Email" }, "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "First Name" }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Name" }, "is_guest": { "type": "boolean", "title": "Is Guest" }, "guest_email": { "anyOf": [ { "type": "string", "format": "email" }, { "type": "null" } ], "title": "Guest Email" } }, "type": "object", "required": [ "id", "email", "first_name", "last_name", "is_guest", "guest_email" ], "title": "User" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } }, "securitySchemes": { "oauth": { "type": "oauth2", "description": "Supertab OAuth2 flow for CAPI. See [Authentication](/customer-api/authentication).", "flows": { "authorizationCode": { "scopes": { "capi:read": "Access to view capi", "capi:write": "Access to write for capi" }, "authorizationUrl": "https://auth.supertab.co/oauth2/auth", "tokenUrl": "https://auth.supertab.co/oauth2/token" } } } } } }