> ## Documentation Index > Fetch the complete documentation index at: https://docs.supertab.co/llms.txt > Use this file to discover all available pages before exploring further. # Create New One-Time Offering > Creates a onetime offering.

Required Scopes

`mapi:write` - Write access to Merchant API resources ## OpenAPI ````yaml post /onetime_offerings openapi: 3.1.0 info: title: FastAPI version: '2025-04-01' servers: - url: /mapi security: [] paths: /onetime_offerings: post: tags: - Merchant summary: Create a one-time offering description: Creates a onetime offering. operationId: create-onetime-offering parameters: - name: x-api-version in: header required: false schema: type: string format: date title: Merchant API version description: The version of the Merchant API you are using. default: '2025-04-01' description: The version of the Merchant API you are using. examples: default: value: '2025-04-01' - name: x-supertab-client-id in: header required: true schema: title: Client Id type: string format: tagged_id examples: - live_client.4df706b5-297a-49c5-a4cd-2a10eca12ff9 - test_client.4df706b5-297a-49c5-a4cd-2a10eca12ff9 description: >- Your Client ID with Supertab. Used to identify the website on which Customer is making a Purchase. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateOnetimeOfferingRequest' responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/OnetimeOffering' '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: >- Dynamic message depending on how the price is wrong | The given currency is not enabled for sales | The given currency is not supported by the system code: >- invalid_price | currency_not_enabled | currency_not_supported 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 '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 code: 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 security: - oauth: - mapi:write components: schemas: CreateOnetimeOfferingRequest: properties: 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: {} items: items: $ref: '#/components/schemas/CreateOnetimeOfferingItemRequest' type: array title: Items type: object required: - currency_code - items title: CreateOnetimeOfferingRequest OnetimeOffering: properties: id: type: string format: tagged_id title: Id examples: - onetime_offering.61a54647-d5d7-44c4-b56c-d5b073759628 status: $ref: '#/components/schemas/OnetimeOfferingStatus' description: >- The status of the one-time offering based on the fact of purchase. It may be new, a purchase pending or a purchase completed. Only status `purchasing_completed` means a payment for the one-time offering purchase has been successfully processed. metadata: additionalProperties: anyOf: - type: number - type: boolean - type: integer - type: string - type: 'null' type: object title: Metadata description: Any additional information about this one-time offering. default: {} items: items: $ref: '#/components/schemas/OnetimeOfferingItem' type: array title: Items description: A list of items that belong to this one-time offering. price: $ref: '#/components/schemas/Price' description: >- The price of this one-time offering combining all the one-time offering items' prices. It is always created on the fly based on the provided information when creating a one-time offering. type: object required: - id - status - metadata - items - price title: OnetimeOffering CreateOnetimeOfferingItemRequest: properties: price_amount: type: integer exclusiveMaximum: 2147483646 exclusiveMinimum: -1 title: Price Amount 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: - price_amount - description title: CreateOnetimeOfferingItemRequest OnetimeOfferingStatus: type: string enum: - new - purchasing_completed - purchasing_pending - purchasing_abandoned - expired title: OnetimeOfferingStatus OnetimeOfferingItem: properties: id: type: string format: tagged_id title: Id examples: - onetime_offering_item.94703e8a-0352-444d-b78d-d5a347a8e09d price: $ref: '#/components/schemas/Price' description: Price of this single one-time offering item. description: type: string title: Description description: >- Description of the one-time offering item provided at the time of creation. metadata: additionalProperties: anyOf: - type: number - type: boolean - type: integer - type: string - type: 'null' type: object title: Metadata description: Any additional information about this one-time offering item. default: {} purchase: anyOf: - $ref: '#/components/schemas/Purchase' - type: 'null' description: >- Purchase created as a result of purchasing this offering. A null value means the status of the corresponding one-time offering is still 'NEW' and a purchasing event has not yet happened. type: object required: - id - price - description - metadata - purchase title: OnetimeOfferingItem 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. Where 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. Purchases may be pending or completed. Only 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. This 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 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. For 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. PurchaseStatus: type: string enum: - completed - pending - abandoned title: PurchaseStatus description: |- We use this enum to represent the status of a purchase. The status can be: - completed: the purchase was successfully completed - pending: the purchase is pending - abandoned: the purchase was abandoned The logic to determine the status of a purchase is: PAY_LATER on Tab -> purchase.status PAY_NOW in a paid Tab -> completed PAY_NOW in an unpaid Tab -> pending Abandoned purchases are not being set at the moment. Purchases are going to be marked as abandoned when new pending purchases are added to the tab. 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 securitySchemes: oauth: type: oauth2 description: >- Supertab OAuth2 flow for MAPI. See [Authentication](/merchant-api/authentication). flows: clientCredentials: scopes: mapi:read: Access to view mapi mapi:write: Access to write for mapi tokenUrl: https://auth.supertab.co/oauth2/token ````