From f84045875bf5c1bf4b0ad056a6e5cb2577d04e02 Mon Sep 17 00:00:00 2001 From: Andy Bestvater Date: Fri, 23 Jan 2026 06:58:33 +0100 Subject: [PATCH] fix: Remove upsell --- customer-api/openapi-2025-04-01.json | 2406 ++++++++++++++++++++++- supertab-experiences/experiences.mdx | 11 +- supertab-js/reference/api.mdx | 45 +- updates/experiences-2025-02-06.mdx | 1 - updates/product.mdx | 47 +- updates/upsell-offerings-2025-07-29.mdx | 29 - 6 files changed, 2454 insertions(+), 85 deletions(-) delete mode 100644 updates/upsell-offerings-2025-07-29.mdx diff --git a/customer-api/openapi-2025-04-01.json b/customer-api/openapi-2025-04-01.json index 5e18621..9b75291 100644 --- a/customer-api/openapi-2025-04-01.json +++ b/customer-api/openapi-2025-04-01.json @@ -1 +1,2405 @@ -{"openapi":"3.1.0","info":{"title":"FastAPI","version":"9999-01-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":"9999-01-01"},"description":"The version of the Customer API you are using.","examples":{"default":{"value":"9999-01-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"}}}},"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 | 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"},"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"},{"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":"9999-01-01"},"description":"The version of the Customer API you are using.","examples":{"default":{"value":"9999-01-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"}}}},"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 | Forbidden","code":"client_id_mismatch | missing_or_invalid_x_supertab_client_id | invalid_subject_type | forbidden"}}}},"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"}]}]}}}}}}},"/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":"9999-01-01"},"description":"The version of the Customer API you are using.","examples":{"default":{"value":"9999-01-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"}}}},"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 | 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":"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"},"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":"9999-01-01"},"description":"The version of the Customer API you are using.","examples":{"default":{"value":"9999-01-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"},"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 | 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"},"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"},"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":"9999-01-01"},"description":"The version of the Customer API you are using.","examples":{"default":{"value":"9999-01-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"},"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"},"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 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"},"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":"9999-01-01"},"description":"The version of the Customer API you are using.","examples":{"default":{"value":"9999-01-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"}}}},"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 | 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"},"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":"9999-01-01"},"description":"The version of the Customer API you are using.","examples":{"default":{"value":"9999-01-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"}}}},"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"},"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"},"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","description":"Used by Supertab to associate Offerings together for best customer value"}},"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."}},"type":"object","required":["id","description","entitlement_details","price","is_pay_now"],"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"}},"type":"object","required":["name","url","auth_redirect_uri","logo_url","content_keys","offerings","experiences","test_mode"],"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"}},"type":"object","required":["id","email","first_name","last_name"],"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"}},"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"}}}}}} \ No newline at end of file +{ + "openapi": "3.1.0", + "info": { "title": "FastAPI", "version": "9999-01-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": "9999-01-01" + }, + "description": "The version of the Customer API you are using.", + "examples": { "default": { "value": "9999-01-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" } + } + } + }, + "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 | 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" + }, + "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" + }, + { + "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": "9999-01-01" + }, + "description": "The version of the Customer API you are using.", + "examples": { "default": { "value": "9999-01-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" } + } + } + }, + "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 | Forbidden", + "code": "client_id_mismatch | missing_or_invalid_x_supertab_client_id | invalid_subject_type | forbidden" + } + } + } + }, + "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" + } + ] + } + ] + } + } + } + } + } + } + }, + "/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": "9999-01-01" + }, + "description": "The version of the Customer API you are using.", + "examples": { "default": { "value": "9999-01-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" } + } + } + }, + "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 | 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": "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" + }, + "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": "9999-01-01" + }, + "description": "The version of the Customer API you are using.", + "examples": { "default": { "value": "9999-01-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" + }, + "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 | 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" + }, + "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" + }, + "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": "9999-01-01" + }, + "description": "The version of the Customer API you are using.", + "examples": { "default": { "value": "9999-01-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" + }, + "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" + }, + "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 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" + }, + "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": "9999-01-01" + }, + "description": "The version of the Customer API you are using.", + "examples": { "default": { "value": "9999-01-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" } + } + } + }, + "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 | 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" + }, + "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": "9999-01-01" + }, + "description": "The version of the Customer API you are using.", + "examples": { "default": { "value": "9999-01-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" } + } + } + }, + "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" + }, + "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" + }, + "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" + } + }, + "type": "object", + "required": ["ui_config", "on_close"], + "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." + } + }, + "type": "object", + "required": [ + "id", + "description", + "entitlement_details", + "price", + "is_pay_now" + ], + "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" + } + }, + "type": "object", + "required": [ + "name", + "url", + "auth_redirect_uri", + "logo_url", + "content_keys", + "offerings", + "experiences", + "test_mode" + ], + "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." + }, + "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" + } + }, + "type": "object", + "required": ["id", "email", "first_name", "last_name"], + "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" } + }, + "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" + } + } + } + } + } +} diff --git a/supertab-experiences/experiences.mdx b/supertab-experiences/experiences.mdx index 9afb649..808ea00 100644 --- a/supertab-experiences/experiences.mdx +++ b/supertab-experiences/experiences.mdx @@ -15,7 +15,6 @@ The Paywall is simple, yet adaptable: - The layout will react to the number of Offerings you select - A second screen can be added for more customization -- Upsells give you an option to encourage customers to choose other (e.g. longer) offerings. If we detect savings for the user, we will show a calculated discount. - To align with your brand, colors can be customized and the logo will be displayed at the top of the Paywall (if you added it to the Website) - Parts of the Paywall text can be edited in all languages we support. @@ -45,20 +44,14 @@ We automatically create the first Paywall for each new Website using default tim You cannot use the same Offering on a screen twice. - For each Offering, you can choose an upsell. We will calculate the difference between prices and if we detect a discount, it will be displayed on the Paywall. Upsells are only displayed when customer clicks on the associated Offering. - - If we detect no discount, the Paywall will adapt to not show the savings badge. - - There are no restrictions for upsells other than the Offering and the associated upsell cannot be the same (e.g. all your time passes can upsell to the same subscription) - If you choose two or three Offerings on one screen, you will have an option to select which one of them should be highlighted by default to grab the attention of customers. Use **Button text color** to edit the **Put it on my Tab** and **More access options** button text. - **Button color** controls the background of the **Put it on my Tab** button, highlighted Offering box, and the upsell box when active. + **Button color** controls the background of the **Put it on my Tab** button, highlighted Offering box. - **Highlighted text color** controls the color of text on highlighted Offerings and the savings badge on upsells to ensure proper contrast. + **Highlighted text color** controls the color of text on highlighted Offerings to ensure proper contrast. Parts of Paywall text (such as title) can be edited in all languages we support. They will not be translated automatically. If you choose not to provide a translation, we will use default values. diff --git a/supertab-js/reference/api.mdx b/supertab-js/reference/api.mdx index 29ca4e1..89203b7 100644 --- a/supertab-js/reference/api.mdx +++ b/supertab-js/reference/api.mdx @@ -11,7 +11,11 @@ This interface is particularly useful for custom integrations that require direc ## Methods -Each method returns a promise which resolves with the response from the Customer API endpoint with object keys transformed from snake_case to camelCase. + + Each method returns a promise which resolves with the response from the + Customer API endpoint with object keys transformed from snake_case to + camelCase. + See Errors for a list of common exceptions. @@ -26,6 +30,7 @@ Retrieves the current customer. Call this method again after auth to get limits in the user's tab currency. You must re-fetch this information after a new auth session is started. + #### Returns @@ -33,7 +38,6 @@ Retrieves the current customer. Customer object. See Retrieve current customer. Supertab.js returns the response object keys in camelCase. - #### Type ```typescript retrieveCustomer return type [expandable] @@ -104,7 +108,6 @@ Supertab.js returns the response object keys in camelCase. } ``` - #### Example ```typescript @@ -124,6 +127,7 @@ Retrieves the site object associated with the client ID used to [initialize Supe Call this method again after auth to get prices in the user's tab currency. You must re-fetch this information after a new auth session is started in order to show correct pricing. + #### Returns @@ -170,11 +174,6 @@ Supertab.js returns the response object keys in camelCase. offerings: string[]; configuration: { onClose: string | (string | null)[] | null; - upsells: { - mainOffering: string; - upsellOffering: string; - discount: number; - }[]; uiConfig?: unknown; }; }[]; @@ -198,7 +197,7 @@ This method checks the entitlement details for a given content key. #### Parameters - The content key of the entitlement to check. + The content key of the entitlement to check. #### Returns @@ -221,7 +220,7 @@ Supertab.js returns the response object keys in camelCase. ```typescript Check entitlement for a specific content key await supertabClient.api.checkEntitlement({ - contentKey: "content-key" + contentKey: "content-key", }); ``` @@ -231,9 +230,9 @@ const { contentKeys } = await supertabClient.api.retrieveSite(); // Check entitlement const entitlement = await Promise.all( - contentKeys.map(async (contentKey) => { - return await supertabClient.api.checkEntitlement({ contentKey }); - }) + contentKeys.map(async (contentKey) => { + return await supertabClient.api.checkEntitlement({ contentKey }); + }), ); ``` @@ -250,20 +249,22 @@ Purchases an offering or a one-time offering. Either `offeringId` or `onetimeOfferingId` must be provided. - The offering ID to purchase. + The offering ID to purchase. - The onetime offering ID to purchase. + The onetime offering ID to purchase. - ISO4217 currency code. - Must match the currency of user's tab, otherwise the purchase will fail. + ISO4217 currency code. + + Must match the currency of user's tab, otherwise the purchase will fail. + - Free-form metadata to associate with the purchase. + Free-form metadata to associate with the purchase. #### Returns @@ -318,8 +319,8 @@ Supertab.js returns the response object keys in camelCase. ```typescript await supertabClient.api.purchase({ - offeringId: "offering-id", - currencyCode: "USD" + offeringId: "offering-id", + currencyCode: "USD", }); ``` @@ -334,7 +335,7 @@ This method retrieves a purchase object for a given purchase ID. #### Parameters - The purchase ID to retrieve. + The purchase ID to retrieve. #### Returns @@ -380,6 +381,6 @@ Supertab.js returns the response object keys in camelCase. ```typescript await supertabClient.api.retrievePurchase({ - purchaseId: "purchase-id" + purchaseId: "purchase-id", }); ``` diff --git a/updates/experiences-2025-02-06.mdx b/updates/experiences-2025-02-06.mdx index 4b4bec8..2f6cdd8 100644 --- a/updates/experiences-2025-02-06.mdx +++ b/updates/experiences-2025-02-06.mdx @@ -16,7 +16,6 @@ We’re thrilled to announce major updates to the Supertab Experiences, includin subscriptions can now stand alone or be combined with other offerings. - **Flexible Basic Paygate**: - A new two-screen layout for a cleaner, more engaging experience. - - Upsells to highlight savings and encourage users to stay engaged longer. - Design customization, including logo support, for better brand alignment. - **More Flexibility**: Create **multiple paygate** for different part of your site and control where each one appears using specific installation codes. diff --git a/updates/product.mdx b/updates/product.mdx index ca59a1f..3e29b88 100644 --- a/updates/product.mdx +++ b/updates/product.mdx @@ -8,74 +8,75 @@ mode: "wide" ## [Trigger Purchases Anywhere with Supertab.js](/updates/trigger-purchase-flow-2025-10-02) - The new createPurchase method in Supertab.js, makes it easier for developers to bring Supertab’s purchase flow directly into their applications programatically. This speeds up custom integrations via a simple function call and allows customization to tailor the purchase flow to your brand's design. [Read more...](/updates/trigger-purchase-flow-2025-10-02) +The new createPurchase method in Supertab.js, makes it easier for developers to bring Supertab’s purchase flow directly into their applications programatically. This speeds up custom integrations via a simple function call and allows customization to tailor the purchase flow to your brand's design. [Read more...](/updates/trigger-purchase-flow-2025-10-02) + ## [New Purchase Flow and Tab auto-closing: better UX for users, improved fund collection and branding options for Merchants](/updates/context-aware-purchase-flow-2025-08-22) - ![Group3625316 Pn](/Group3625316.png) - - Our new purchase flow delivers a smoother, more consistent experience—fully styled to match your brand. - You can now enable card capture on a per-site basis and activate Tab auto-closing: after 30 days of inactivity, open Tabs are automatically charged, helping you secure revenue more reliably. [Read more...](/updates/context-aware-purchase-flow-2025-08-22) - - - - ## [Set Upsell Offerings as the Default on Your Paywall](/updates/upsell-offerings-2025-07-29) +![Group3625316 Pn](/Group3625316.png) - ![Upsell as default offering in paywall](/images/upsell-default-paywall.png) +Our new purchase flow delivers a smoother, more consistent experience—fully styled to match your brand. +You can now enable card capture on a per-site basis and activate Tab auto-closing: after 30 days of inactivity, open Tabs are automatically charged, helping you secure revenue more reliably. [Read more...](/updates/context-aware-purchase-flow-2025-08-22) - You can now set an upsell offering as the default selection on your paywall. [Read more...](/updates/upsell-offerings-2025-07-29) ## [Off-App Purchase Flow](/updates/off-app-purchase-flow-2025-06-09) - Enable direct transactions outside of app stores with Supertab’s new Off-App Purchase flow, keeping more revenue in your hands while offering a seamless user experience. [Read more...](/updates/off-app-purchase-flow-2025-06-09) +Enable direct transactions outside of app stores with Supertab’s new Off-App Purchase flow, keeping more revenue in your hands while offering a seamless user experience. [Read more...](/updates/off-app-purchase-flow-2025-06-09) + ## [Improved Navigation with Site-Driven Architecture](/updates/site-driven-architecture-2025-05-10) - ![Frame64 Pn](/images/Frame64.png) +![Frame64 Pn](/images/Frame64.png) + +We’ve restructured how you navigate Offerings, Experiences, and settings—so it’s easier to manage multiple Sites and stay focused. [Read more...](/updates/site-driven-architecture-2025-05-10) - We’ve restructured how you navigate Offerings, Experiences, and settings—so it’s easier to manage multiple Sites and stay focused. [Read more...](/updates/site-driven-architecture-2025-05-10) ## [Dynamic Tab Limits to Close Payments Faster](/updates/dynamic-tab-limits-2025-05-10) - First-time users now get a smaller Tab limit to start, making it easier to complete a payment early and unlock the full \$5 Tab. Faster conversions for Merchants, shorter time-to-value value for users. [Read more...](/updates/dynamic-tab-limits-2025-05-10) +First-time users now get a smaller Tab limit to start, making it easier to complete a payment early and unlock the full \$5 Tab. Faster conversions for Merchants, shorter time-to-value value for users. [Read more...](/updates/dynamic-tab-limits-2025-05-10) + ## [Get Started Faster — KYC Now Only Required at Payout](/updates/kyc-at-payout-2025-05-10) - Whether you’re using Supertab directly or through our integration with Google Ad Manager, you can now start earning without completing KYC upfront. [Read more...](/updates/kyc-at-payout-2025-05-10) +Whether you’re using Supertab directly or through our integration with Google Ad Manager, you can now start earning without completing KYC upfront. [Read more...](/updates/kyc-at-payout-2025-05-10) + ## [Customize Your Paygate Messaging in Multiple Languages](/updates/editable-paygate-copy-2025-04-16) - ![Editablecopyandlangsupport Pn](/images/editablecopyandlangsupport.png) +![Editablecopyandlangsupport Pn](/images/editablecopyandlangsupport.png) + +Tailor your Paygate messaging to fit your use case, test what converts best, and speak to users in one of eight supported languages. [Read more...](/updates/editable-paygate-copy-2025-04-16) - Tailor your Paygate messaging to fit your use case, test what converts best, and speak to users in one of eight supported languages. [Read more...](/updates/editable-paygate-copy-2025-04-16) ## [Validate Purchases with Server-Side Webhooks](/updates/webhooks-2025-02) - ![Webhooks Pn](/images/Webhooks.png) +![Webhooks Pn](/images/Webhooks.png) + +You can now securely confirm purchases and trigger real-time workflows—grant access, send emails, update analytics, and more. Plus, `onPurchaseComplete` now gives you detailed purchase data. [Read more...](/updates/webhooks-2025-02) - You can now securely confirm purchases and trigger real-time workflows—grant access, send emails, update analytics, and more. Plus, `onPurchaseComplete` now gives you detailed purchase data. [Read more...](/updates/webhooks-2025-02) ## [New Basic Paygate, Changes to the Purchase Button and Unlimited Offerings](/updates/experiences-2025-02-06) - ![Paygatepreview2 Pn](/Paygatepreview2.png) +![Paygatepreview2 Pn](/Paygatepreview2.png) + +You can now use the all new Supertab Paygate to secure and monetize your content or access to your SaaS product. The new Basic Paygate replaces existing Paygate installations and offers enhanced options for controlling how you price and sell your content. - You can now use the all new Supertab Paygate to secure and monetize your content or access to your SaaS product. The new Basic Paygate replaces existing Paygate installations and offers enhanced options for controlling how you price and sell your content. +Setup and installation takes minutes, existing customers are encouraged to migrate to the new Paygate Experience. [Read more...](/updates/experiences-2025-02-06) - Setup and installation takes minutes, existing customers are encouraged to migrate to the new Paygate Experience. [Read more...](/updates/experiences-2025-02-06) diff --git a/updates/upsell-offerings-2025-07-29.mdx b/updates/upsell-offerings-2025-07-29.mdx deleted file mode 100644 index 9cd37f5..0000000 --- a/updates/upsell-offerings-2025-07-29.mdx +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: "Set Upsell Offerings as the Default on Your Paywall" -description: "Make higher-value plans the default choice on your paywall. Pre-selecting an upsell offering helps increase ARPU with less friction, while still giving users the freedom to choose another option." ---- - -### What’s new - -You can now set an upsell offering as the **default selection** on your paywall. - -![UpsellDefaultPaywall](/images/upsell-default-paywall.png) - -### Why it matters - -Most users stick with the option that’s pre-selected. By making an upsell the default, you can nudge customers toward higher-value plans without adding clicks or friction. It’s a low-lift way to boost ARPU while still giving users freedom of choice. - -### How it works - -When configuring your paywall offerings, choose which plan should appear as the default selection. This can be: - -- A longer time pass -- A subscription -- A bundled package -- Any upsell you want to feature - -The default appears pre-selected when the paywall loads, but users can switch to another option at any time. - ---- - -We’ll keep refining paywall controls as we grow—[let us know what you’d like to see next](mailto:product@supertab.co).