openapi: 3.1.0
info:
  title: VyaFac API
  description: >-
    VyaFac is a powerful and secure payment gateway API designed to streamline
    transaction processing. Developers can leverage OpenAPI specifications to
    manage products, pricing options with tax plans, and customer accounts along
    with their payment methods. The API also enables the creation and management
    of subscriptions and payment links, providing a seamless and efficient
    payment experience.
  version: 1.0.0
tags:
  - name: Products
    description: >-
      Manage and retrieve product details, create new products, update existing
      ones, and remove products from the system.
  - name: PricingOptions
    description: >-
      Define and manage pricing options, including discounts, offers, and
      different pricing tiers for products and services.
  - name: Customers
    description: >-
      Manage customer accounts, retrieve customer details, and handle
      customer-related operations such as creation, updates, and deletions.
  - name: PaymentMethods
    description: >-
      Handle the configuration and management of different payment methods,
      including credit cards, PayPal, and other online payment systems.
  - name: Subscriptions
    description: >-
      Manage and retrieve subscription details, create new subscriptions, update
      existing ones, and handle cancellations or renewals.
  - name: SubscriptionItems
    description: >-
      Define and manage items within a subscription, including adding, updating,
      or removing items linked to an active subscription.
  - name: PaymentLinks
    description: >-
      Generate and manage payment links for one-time or recurring payments,
      allowing users to complete transactions securely via a hosted link.
  - name: PaymentLinkItems
    description: >-
      Manage specific items associated with payment links, including their
      details, pricing, and configurations for seamless checkout experiences.
  - name: Calculate Taxes
    description: Endpoints related to calculating and retrieving tax information.
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
security:
  - BearerAuth: []
paths:
  /products:
    get:
      tags:
        - Products
      summary: Product listing
      description: >-
        Fetch a paginated list of products with optional filters like date,
        search query, limit, without_pagination and without_one_off.
      operationId: listProducts
      parameters:
        - name: date
          in: query
          schema:
            type: string
            format: date
            example: '2024-12-06'
          description: Filter products created on a specific date.
        - name: query
          in: query
          schema:
            type: string
            example: Christie
          description: Search for products by name or description.
        - name: limit
          in: query
          schema:
            type: integer
            default: 100
            example: 100
          description: Limit the number of results per page.
        - name: without_pagination
          in: query
          schema:
            type: boolean
            default: false
            example: true
          description: Get all products without pagination.
        - name: without_one_off
          in: query
          schema:
            type: boolean
            default: false
            example: true
          description: Get all recurring products.
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            example: application/json
          description: The response format must be JSON.
      responses:
        '200':
          description: A list of products retrieved successfully.
          content:
            application/json:
              example:
                status: success
                message: Products retrieved successfully!
                meta:
                  total: 5
                  per_page: 100
                  current_page: 1
                  last_page: 1
                  next_page_url: null
                  prev_page_url: null
                data:
                  - id: pro_UyyAB8bqhRaVhHqqtTgpukcX
                    name: Flying chicken
                    description: null
                    active: true
                    tax_info: null
                    created_at: '2025-02-27T07:55:26.000000Z'
                    updated_at: '2025-02-27T07:55:26.000000Z'
                  - id: pro_sc4Clg4N5H7N2IknF2dZ9dju
                    name: Fantastic Frozen Computer
                    description: http://elmo.name
                    active: true
                    tax_info: null
                    created_at: '2025-02-25T09:53:04.000000Z'
                    updated_at: '2025-02-25T09:53:04.000000Z'
                errors: []
                code: 200
                timestamp: '2025-02-27T11:20:47+00:00'
                version: 1.0.0
    post:
      tags:
        - Products
      summary: Create product
      description: Create a new product with a name, description, and pricing details.
      operationId: createProduct
      parameters:
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            example: application/json
          description: The response format must be JSON.
      requestBody:
        required: true
        content:
          application/json:
            example:
              name: Generic Granite Pizza
              description: https://bradley.net
              pricing_option:
                default: 1
                price: 10
                payment_type: one-off
                billing_interval_type: null
                billing_frequency: null
                tax_plan:
                  type: exclusive
                  amount: 5
                  amount_type: flat
      responses:
        '200':
          description: Product created successfully.
          content:
            application/json:
              example:
                status: success
                message: Product created successfully!
                meta: null
                data:
                  id: pro_EsrjpTa0yPenKvOq58wp5WKM
                  name: Generic Granite Pizza
                  description: https://bradley.net
                  active: true
                  tax_info: null
                  created_at: '2025-02-27T11:21:37.000000Z'
                  updated_at: '2025-02-27T11:21:37.000000Z'
                errors: []
                code: 200
                timestamp: '2025-02-27T11:21:37+00:00'
                version: 1.0.0
  /products/{id}:
    patch:
      tags:
        - Products
      summary: Update product
      description: Update details of a product.
      operationId: updateProduct
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            example: pro_EsrjpTa0yPenKvOq58wp5WKM
          description: Unique identifier of the product.
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            example: application/json
          description: The response format must be JSON.
      requestBody:
        required: false
        content:
          application/json:
            example:
              name: Updated name
              description: Updated description of the product.
      responses:
        '200':
          description: Product updated successfully!
          content:
            application/json:
              example:
                status: success
                message: Product updated successfully!
                meta: null
                data:
                  id: pro_EsrjpTa0yPenKvOq58wp5WKM
                  name: Generic Granite Pizza
                  description: https://bradley.net
                  active: true
                  tax_info: null
                  created_at: '2025-02-27T11:21:37.000000Z'
                  updated_at: '2025-02-27T11:21:37.000000Z'
                errors: []
                code: 200
                timestamp: '2025-02-27T12:45:15+00:00'
                version: 1.0.0
    get:
      tags:
        - Products
      summary: Product details
      description: Fetch detailed information about a product using its unique identifier.
      operationId: getProduct
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            example: pro_EsrjpTa0yPenKvOq58wp5WKM
          description: Unique identifier of the product.
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            example: application/json
          description: The response format must be JSON.
      responses:
        '200':
          description: Product details retrieved successfully.
          content:
            application/json:
              example:
                status: success
                message: resources/product.fetch_success
                meta: null
                data:
                  id: pro_EsrjpTa0yPenKvOq58wp5WKM
                  name: Generic Granite Pizza
                  description: https://bradley.net
                  active: true
                  tax_info: null
                  created_at: '2025-02-27T11:21:37.000000Z'
                  updated_at: '2025-02-27T11:21:37.000000Z'
                errors: []
                code: 200
                timestamp: '2025-02-27T12:45:15+00:00'
                version: 1.0.0
    delete:
      tags:
        - Products
      summary: Delete product
      description: Delete a product from the system
      operationId: deleteProduct
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            example: pro_EsrjpTa0yPenKvOq58wp5WKM
          description: Unique identifier of the product.
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            example: application/json
          description: The response format must be JSON.
      responses:
        '200':
          description: Product deleted successfully.
          content:
            application/json:
              example:
                status: success
                message: The product has been deleted successfully!
                meta: null
                data: null
                errors: []
                code: 200
                timestamp: '2025-02-27T12:45:15+00:00'
                version: 1.0.0
  /products/{productId}/pricing-options:
    get:
      tags:
        - PricingOptions
      summary: List pricing options
      description: List pricing options for a specific product.
      operationId: listPricingOptions
      parameters:
        - name: productId
          in: path
          required: true
          schema:
            type: string
            example: pro_1xUyaVQeGpQY0pyFHzXJxpZo
          description: Unique identifier of the product
        - name: limit
          in: query
          required: false
          description: Limit the number of results
          schema:
            type: integer
            example: 50
        - name: Accept
          in: header
          required: true
          description: Response format must be JSON
          schema:
            type: string
            example: application/json
      responses:
        '200':
          description: List pricing options retrieved successfully
          content:
            application/json:
              example:
                status: success
                message: List pricing options retrieved successfully
                data:
                  - id: price_nT5EUArglpqiY8D7TVyeWNmi
                    price: 15.7
                    default: true
                    payment_type: recurring
                    billing_frequency: 1
                    billing_interval_type: months
                code: 200
                timestamp: '2025-02-27T12:00:00+00:00'
                version: 1.0.0
    post:
      tags:
        - PricingOptions
      summary: Create pricing option
      description: Create a pricing option for a product.
      operationId: createPricingOption
      parameters:
        - name: productId
          in: path
          required: true
          description: Unique identifier of the product
          schema:
            type: string
            example: pro_1xUyaVQeGpQY0pyFHzXJxpZo
        - name: Accept
          in: header
          required: true
          description: Response format must be JSON
          schema:
            type: string
            example: application/json
      requestBody:
        required: true
        content:
          application/json:
            example:
              default: 1
              price: 15.7
              payment_type: recurring
              billing_frequency: 1
              billing_interval_type: months
      responses:
        '200':
          description: Pricing option created successfully
          content:
            application/json:
              example:
                status: success
                message: Pricing option created successfully
                data:
                  id: price_nT5EUArglpqiY8D7TVyeWNmi
                  default: 1
                  price: 15.7
                  payment_type: recurring
                  billing_frequency: 1
                  billing_interval_type: months
                code: 200
                timestamp: '2025-02-27T12:05:00+00:00'
                version: 1.0.0
  /products/{productId}/pricing-options/{pricingOptionId}:
    get:
      tags:
        - PricingOptions
      summary: Get pricing option
      description: Retrieve details of a pricing option.
      operationId: getPricingOption
      parameters:
        - name: productId
          in: path
          required: true
          description: Unique identifier of the pricing option
          schema:
            type: string
            example: pro_1xUyaVQeGpQY0pyFHzXJxpZo
        - name: pricingOptionId
          in: path
          required: true
          description: Unique identifier of the pricing option
          schema:
            type: string
            example: price_1xUyaVQeGpQY0pyFHzXJxpZo
        - name: Accept
          in: header
          required: true
          description: Response format must be JSON
          schema:
            type: string
            example: application/json
      responses:
        '200':
          description: Pricing option details retrieved successfully
          content:
            application/json:
              example:
                status: success
                message: Pricing option details retrieved successfully
                data:
                  id: price_nT5EUArglpqiY8D7TVyeWNmi
                  default: true
                  price: 15.7
                  payment_type: recurring
                  billing_frequency: 1
                  billing_interval_type: months
                code: 200
                timestamp: '2025-02-27T12:10:00+00:00'
                version: 1.0.0
    put:
      tags:
        - PricingOptions
      summary: Update pricing option
      description: Update an existing pricing option.
      operationId: updatePricingOption
      parameters:
        - name: productId
          in: path
          required: true
          description: Unique identifier of the pricing option
          schema:
            type: string
            example: pro_1xUyaVQeGpQY0pyFHzXJxpZo
        - name: pricingOptionId
          in: path
          required: true
          description: Unique identifier of the pricing option
          schema:
            type: string
            example: price_1xUyaVQeGpQY0pyFHzXJxpZo
        - name: Accept
          in: header
          required: true
          description: Response format must be JSON
          schema:
            type: string
            example: application/json
      requestBody:
        required: true
        content:
          application/json:
            example:
              default: 1
              price: 10.5
              payment_type: recurring
              billing_frequency: 3
              billing_interval_type: years
      responses:
        '200':
          description: Pricing option updated successfully
          content:
            application/json:
              example:
                status: success
                message: Pricing option updated successfully
                data:
                  id: price_nT5EUArglpqiY8D7TVyeWNmi
                  default: 1
                  price: 10.5
                  payment_type: recurring
                  billing_frequency: 3
                  billing_interval_type: years
                code: 200
                timestamp: '2025-02-27T12:15:00+00:00'
                version: 1.0.0
    delete:
      tags:
        - PricingOptions
      summary: Delete pricing option
      description: Delete a pricing option.
      operationId: deletePricingOption
      parameters:
        - name: productId
          in: path
          required: true
          description: Unique identifier of the pricing option
          schema:
            type: string
            example: pro_1xUyaVQeGpQY0pyFHzXJxpZo
        - name: pricingOptionId
          in: path
          required: true
          description: Unique identifier of the pricing option
          schema:
            type: string
            example: price_1xUyaVQeGpQY0pyFHzXJxpZo
        - name: Accept
          in: header
          required: true
          description: Response format must be JSON
          schema:
            type: string
            example: application/json
      responses:
        '200':
          description: Pricing option deleted successfully
          content:
            application/json:
              example:
                status: success
                message: Pricing option deleted successfully
                data: null
                code: 200
                timestamp: '2025-02-27T12:20:00+00:00'
                version: 1.0.0
  /customers:
    get:
      tags:
        - Customers
      summary: Customer listing
      description: >-
        Fetch a paginated list of customers with optional filters like date
        range, search query and limit.
      operationId: listCustomers
      parameters:
        - name: date
          in: query
          schema:
            type: string
            format: date
            example: '2024-12-06'
          description: Filter customers created on a specific date.
        - name: query
          in: query
          schema:
            type: string
            example: Christie
          description: Search for customers by name or description.
        - name: limit
          in: query
          schema:
            type: integer
            default: 100
            example: 100
          description: Limit the number of results per page.
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            example: application/json
          description: The response format must be JSON.
      responses:
        '200':
          description: A list of customers retrieved successfully.
          content:
            application/json:
              example:
                status: success
                message: Customers retrieved successfully!
                meta:
                  total: 5
                  per_page: 100
                  current_page: 1
                  last_page: 1
                  next_page_url: null
                  prev_page_url: null
                data:
                  - id: cus_UyiEZfu3EARYITXomdufempb
                    name: Beverly Olson
                    email: Beatrice56@hotmail.com
                    phone: '5321689543'
                    subscription_count: 0
                    created_at: '2025-02-25T10:14:20.000000Z'
                    updated_at: '2025-02-25T10:14:20.000000Z'
                  - id: cus_3UaLAQ5rw5gjT9l7sX0CbZMq
                    name: Lunea Fletcher
                    email: carihecyb@mailinator.com
                    phone: '19219626422'
                    subscription_count: 2
                    created_at: '2025-02-25T10:11:00.000000Z'
                    updated_at: '2025-02-25T10:11:00.000000Z'
                errors: []
                code: 200
                timestamp: '2025-02-27T11:20:47+00:00'
                version: 1.0.0
    post:
      tags:
        - Customers
      summary: Create customer
      description: >-
        Creates a new customer with an attached payment method (card). For more
        information about card handling, see [Card
        Handling](./pages/handling_cards.md).
      operationId: createCustomer
      parameters:
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            example: application/json
          description: The response format must be JSON.
      requestBody:
        required: true
        content:
          application/json:
            example:
              name: Christina James
              email: christinaJames@example.com
              description: A returnig customer.
              phone: '5321689543'
              payment_method:
                default: 1
                card:
                  token: supt_os8eyf8ewyro34jkmn
                  last_four: '1111'
                  exp_month: '12'
                  exp-year: '2030'
                address:
                  card_holder_name: Christine Yii
                  country: US
                  address_line_1: 6860 Dallas Pkwy
                  zip_code: '75024'
                  state: Michigan
                  city: Detroit
      responses:
        '200':
          description: Customer created successfully.
          content:
            application/json:
              example:
                status: success
                message: Customer created successfully!
                meta: null
                data:
                  id: cus_ol9lb3ffbefnPufmXgGxtF94
                  name: Beatrice Rogahn
                  email: Rusty.Willms@yahoo.com
                  description: Quam explicabo culpa labore nostrum.
                  phone: '5321689543'
                  payment_methods:
                    - id: pm_bxTuewKSrFUJ1ZhtAT3f58zY
                      default: 1
                      card_last_four: '0014'
                      type: MC
                      expiry_month: 12
                      expiry_year: 2031
                      created_at: '2025-02-28T05:07:02+00:00'
                      updated_at: '2025-02-28T05:07:02+00:00'
                  created_at: '2025-02-28T05:07:00.000000Z'
                  updated_at: '2025-02-28T05:07:00.000000Z'
                errors: []
                code: 201
                timestamp: '2025-02-28T05:07:02+00:00'
                version: 1.0.0
  /customers/{id}:
    patch:
      tags:
        - Customers
      summary: Update customer
      description: Update details of a customer.
      operationId: updateCustomer
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            example: cus_EsrjpTa0yPenKvOq58wp5WKM
          description: Unique identifier of the product.
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            example: application/json
          description: The response format must be JSON.
      requestBody:
        required: false
        content:
          application/json:
            example:
              name: New customer name
              email: updated.email@hotmail.com
              description: Updated description
              phone: '352164859653'
      responses:
        '200':
          description: Customer updated successfully!
          content:
            application/json:
              example:
                status: success
                message: Customer updated successfully!
                meta: null
                data:
                  id: cus_3UaLAQ5rw5gjT9l7sX0CbZMq
                  name: Updated name
                  email: updated.email@hotmail.com
                  description: aksgdkjhasjdhjhasjd
                  phone: '352164859653'
                  payment_methods:
                    - id: pm_SkUimw0YhTkgG5czJC8xGEJP
                      default: 1
                      card_last_four: '1111'
                      type: Visa
                      expiry_month: 8
                      expiry_year: 2027
                      created_at: '2025-02-25T10:11:03+00:00'
                      updated_at: '2025-02-25T10:11:03+00:00'
                  created_at: '2025-02-25T10:11:00.000000Z'
                  updated_at: '2025-02-28T05:16:50.000000Z'
                errors: []
                code: 200
                timestamp: '2025-02-28T05:16:50+00:00'
                version: 1.0.0
    get:
      tags:
        - Customers
      summary: Customer details
      description: Fetch detailed information about a customer using its unique identifier.
      operationId: getCustomer
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            example: cus_EsrjpTa0yPenKvOq58wp5WKM
          description: Unique identifier of the product.
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            example: application/json
          description: The response format must be JSON.
      responses:
        '200':
          description: Product details retrieved successfully.
          content:
            application/json:
              example:
                status: success
                message: Customer retrieved successfully!
                meta: null
                data:
                  id: cus_3UaLAQ5rw5gjT9l7sX0CbZMq
                  name: Chritina James
                  email: updated.email@hotmail.com
                  description: aksgdkjhasjdhjhasjd
                  phone: '352164859653'
                  payment_methods:
                    - id: pm_SkUimw0YhTkgG5czJC8xGEJP
                      default: 1
                      card_last_four: '1111'
                      type: Visa
                      expiry_month: 8
                      expiry_year: 2027
                      created_at: '2025-02-25T10:11:03+00:00'
                      updated_at: '2025-02-25T10:11:03+00:00'
                  created_at: '2025-02-25T10:11:00.000000Z'
                  updated_at: '2025-02-28T05:16:50.000000Z'
                errors: []
                code: 200
                timestamp: '2025-02-28T05:20:19+00:00'
                version: 1.0.0
    delete:
      tags:
        - Customers
      summary: Delete customer
      description: Delete a customer from the system
      operationId: deleteCustomer
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            example: cus_EsrjpTa0yPenKvOq58wp5WKM
          description: Unique identifier of the product.
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            example: application/json
          description: The response format must be JSON.
      responses:
        '200':
          description: Customer deleted successfully.
          content:
            application/json:
              example:
                status: success
                message: Customer(s) deleted successfully!
                meta: null
                data: null
                errors: []
                code: 200
                timestamp: '2025-02-28T05:21:47+00:00'
                version: 1.0.0
  /customers/{customer_id}/payment-methods:
    get:
      tags:
        - PaymentMethods
      summary: List customer payment methods
      description: Retrieve all payment methods for a specific customer.
      operationId: listCustomerPaymentMethods
      parameters:
        - name: customer_id
          in: path
          required: true
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            default: 250
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            example: application/json
      responses:
        '200':
          description: Payment methods retrieved successfully.
          content:
            application/json:
              example:
                status: success
                message: Operation successful.
                meta:
                  total: 7
                  per_page: 100
                  current_page: 1
                  last_page: 1
                  next_page_url: null
                  prev_page_url: null
                data:
                  - id: pm_D6Re4qnAXcEqpNNS77Zdn0MT
                    default: true
                    card_last_four: '1111'
                    type: MC
                    expiry_month: 12
                    expiry_year: 2030
                    created_at: '2025-05-22T06:34:16+00:00'
                    updated_at: '2025-05-22T06:34:16+00:00'
                  - id: pm_xRRV2xjXTxlb8FKqBazgyznD
                    default: false
                    card_last_four: '1111'
                    type: MC
                    expiry_month: 12
                    expiry_year: 2030
                    created_at: '2025-05-22T06:43:47+00:00'
                    updated_at: '2025-05-22T06:43:47+00:00'
                errors: null
                code: 200
                timestamp: '2025-05-22T06:44:17+00:00'
                version: 1.0.0
    post:
      tags:
        - PaymentMethods
      summary: Create customer payment method
      description: Add a new payment method for a customer.
      operationId: createCustomerPaymentMethod
      parameters:
        - name: customer_id
          in: path
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            example: application/json
      requestBody:
        required: true
        content:
          application/json:
            example:
              default: false
              card:
                token: supt_cn9r834cr9m83xjr34x
                last_four: '0032'
                exp_month: '12'
                exp_year: '2030'
              address:
                card_holder_name: Usman Zahid
                country: US
                address_line_1: 6860 Dallas Pkwy
                zip_code: '75024'
                state: New York
                city: New York
      responses:
        '200':
          description: Payment method created successfully.
          content:
            application/json:
              example:
                status: success
                message: Payment Method created successfully!
                meta: null
                data:
                  id: pm_PZJX52RIDP8lP4c8WVyz5H0E
                  default: false
                  card_last_four: '1111'
                  type: MC
                  expiry_month: '12'
                  expiry_year: '2030'
                  created_at: '2025-05-22T06:47:30+00:00'
                  updated_at: '2025-05-22T06:47:30+00:00'
                errors: null
                code: 200
                timestamp: '2025-05-22T06:47:30+00:00'
                version: 1.0.0
  /customers/{customer_id}/payment-methods/{id}:
    patch:
      tags:
        - PaymentMethods
      summary: Update a customer’s payment method
      description: Update a specific payment method.
      operationId: updateCustomerPaymentMethod
      parameters:
        - name: customer_id
          in: path
          required: true
          schema:
            type: string
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            example: application/json
      requestBody:
        required: true
        content:
          application/json:
            example:
              default: true
      responses:
        '200':
          description: Payment method updated successfully.
          content:
            application/json:
              example:
                status: success
                message: Payment Method updated successfully!
                meta: null
                data: null
                errors: null
                code: 200
                timestamp: '2025-05-22T06:32:24+00:00'
                version: 1.0.0
    delete:
      tags:
        - PaymentMethods
      summary: Delete a customer’s payment method
      description: Remove a specific payment method.
      operationId: deleteCustomerPaymentMethod
      parameters:
        - name: customer_id
          in: path
          required: true
          schema:
            type: string
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            example: application/json
      responses:
        '200':
          description: Payment method deleted successfully.
          content:
            application/json:
              example:
                status: success
                message: Payment Method deleted successfully!
                meta: null
                data: null
                errors: null
                code: 200
                timestamp: '2025-05-22T06:47:45+00:00'
                version: 1.0.0
  /subscriptions:
    get:
      tags:
        - Subscriptions
      summary: Subscription listing
      description: >-
        Fetch a paginated list of subscriptions with optional filters like date,
        email, search query and limit.
      operationId: listSubscriptions
      parameters:
        - name: date
          in: query
          schema:
            type: string
            format: date
            example: '2024-12-06'
          description: Filter subscriptions created on a specific date.
        - name: email
          in: query
          schema:
            type: string
            format: date
            example: '2024-12-06'
          description: Filter subscriptions based on customer email.
        - name: query
          in: query
          schema:
            type: string
            example: Christie
          description: >-
            Search for subscriptions by customer name or description, and
            products.
        - name: limit
          in: query
          schema:
            type: integer
            default: 100
            example: 100
          description: Limit the number of results per page.
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            example: application/json
          description: The response format must be JSON.
      responses:
        '200':
          description: A list of subscriptions retrieved successfully.
          content:
            application/json:
              example:
                status: success
                message: Products retrieved successfully!
                meta:
                  total: 5
                  per_page: 100
                  current_page: 1
                  last_page: 1
                  next_page_url: null
                  prev_page_url: null
                data:
                  - id: sub_s5ISgJAOWTIBi9Z6bdDnbma6
                    status: cancelled
                    total_value: 20
                    cycle_start_date: null
                    cancels_at: null
                    items:
                      - id: si_RDr27DHHrRmxa8jgmIwWEbhO
                        sub_total: 10
                        tax_amount: 5
                        total: 15
                        pricing_option_id: price_6MquxQnSHbP7myp37PPts1Dl
                        status: active
                        quantity: 1
                        product: Fantastic Frozen Computer
                        product_id: pro_sc4Clg4N5H7N2IknF2dZ9dju
                      - id: si_MDfmbvCm9CkNsct6ce9ZHZJK
                        sub_total: 10
                        tax_amount: 5
                        total: 15
                        pricing_option_id: pro_s09bvi87f8sdvo7fsd87fb
                        status: active
                        quantity: 1
                        product: Handmade Concrete Towels
                        product_id: pro_yCbghIN0NKoevGXwFlOdLQgU
                    created_at: '2025-02-25T10:11:47.000000Z'
                    updated_at: '2025-02-28T05:21:47.000000Z'
                errors: []
                code: 200
                timestamp: '2025-02-27T11:20:47+00:00'
                version: 1.0.0
    post:
      tags:
        - Subscriptions
      summary: Create subscription
      description: >-
        Create a new subscription with trial days, products, and start and end
        dates.


        **Note:**

        - Add a key named `collect_automated_tax` in your request body.
          - Set it to `true` if any product has automated tax.
          - Otherwise, set it to `false`.
        - Add a key named `automated_tax` inside each product object in your
        `products` array.
          - Set it to any value if the product has automated tax.
          - Otherwise, set it to `null`.
      operationId: createSubscription
      parameters:
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            example: application/json
          description: The response format must be JSON.
      requestBody:
        required: true
        content:
          application/json:
            example:
              customer_id: cus_kUdHjYwiUSXnbXfqTgKN0rh0
              trial_days: 10
              collect_automated_tax: true
              coupon_code: null
              products:
                - product_id: pro_mUMe9iAzjoEm5GgArWL3lIG0
                  pricing_option_id: price_ZGhjedgcbI0lE9B1nQH5k234
                  quantity: 5
                  automated_tax: 6
              starts_at: '2025-02-25'
              ends_at: '2025-12-30'
      responses:
        '200':
          description: Subscription created successfully.
          content:
            application/json:
              example:
                status: success
                message: Subscription created successfully!
                meta: null
                data:
                  id: sub_MezhDcoPLVAC8zjHMFhlB5mB
                  status: trialing
                  total_value: 234
                  cycle_start_date: null
                  cancels_at: null
                  items:
                    - id: si_ERer9e7glQbCnNTHOZjUIfPg
                      sub_total: 191.8
                      tax_amount: 42.2
                      total: 234
                      pricing_option_id: price_0ZyxqCcemqBvqNNqWZ3dMlBk
                      status: active
                      quantity: 1
                      product: gjghjghj
                      product_id: pro_j7sOyIGwbNWhOyoExaF3jdf8
                  created_at: '2025-02-28T06:11:46.000000Z'
                  updated_at: '2025-02-28T06:11:46.000000Z'
                errors: []
                code: 200
                timestamp: '2025-02-28T06:11:46+00:00'
                version: 1.0.0
  /subscriptions/{id}:
    patch:
      tags:
        - Subscriptions
      summary: Update subscription
      description: Update details of a subscription.
      operationId: updateSubscription
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            example: sub_EsrjpTa0yPenKvOq58wp5WKM
          description: Unique identifier of the subscription.
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            example: application/json
          description: The response format must be JSON.
      requestBody:
        required: false
        content:
          application/json:
            example:
              cancels_at: '2027-12-17'
      responses:
        '200':
          description: Subscription updated successfully!
          content:
            application/json:
              example:
                status: success
                message: Subscription updated successfully!
                meta: null
                data:
                  id: sub_MezhDcoPLVAC8zjHMFhlB5mB
                  status: trialing
                  total_value: 234
                  cycle_start_date: null
                  cancels_at: '2027-12-17'
                  items:
                    - id: si_ERer9e7glQbCnNTHOZjUIfPg
                      sub_total: 191.8
                      tax_amount: 42.2
                      total: 234
                      pricing_option_id: price_0ZyxqCcemqBvqNNqWZ3dMlBk
                      status: active
                      quantity: 1
                      product: gjghjghj
                      product_id: pro_j7sOyIGwbNWhOyoExaF3jdf8
                  created_at: '2025-02-28T06:11:46.000000Z'
                  updated_at: '2025-02-28T06:24:56.000000Z'
                errors: []
                code: 200
                timestamp: '2025-02-28T06:24:56+00:00'
                version: 1.0.0
    get:
      tags:
        - Subscriptions
      summary: Subscription details
      description: >-
        Fetch detailed information about a subscription using its unique
        identifier.
      operationId: getSubscription
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            example: sub_EsrjpTa0yPenKvOq58wp5WKM
          description: Unique identifier of the subscription.
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            example: application/json
          description: The response format must be JSON.
      responses:
        '200':
          description: Subscription details retrieved successfully.
          content:
            application/json:
              example:
                status: success
                message: Subscription details retrieved!
                meta: null
                data:
                  id: sub_MezhDcoPLVAC8zjHMFhlB5mB
                  status: trialing
                  total_value: 234
                  cycle_start_date: null
                  cancels_at: '2027-12-17'
                  items:
                    - id: si_ERer9e7glQbCnNTHOZjUIfPg
                      sub_total: 191.8
                      tax_amount: 42.2
                      total: 234
                      pricing_option_id: price_0ZyxqCcemqBvqNNqWZ3dMlBk
                      status: active
                      quantity: 1
                      product: gjghjghj
                      product_id: pro_j7sOyIGwbNWhOyoExaF3jdf8
                  created_at: '2025-02-28T06:11:46.000000Z'
                  updated_at: '2025-02-28T06:24:56.000000Z'
                errors: []
                code: 200
                timestamp: '2025-02-28T06:24:56+00:00'
                version: 1.0.0
    delete:
      tags:
        - Subscriptions
      summary: Cancel subscription
      description: Cancel a subscription
      operationId: cancelSubscription
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            example: sub_EsrjpTa0yPenKvOq58wp5WKM
          description: Unique identifier of the subscription.
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            example: application/json
          description: The response format must be JSON.
      responses:
        '200':
          description: Subscription cancelled successfully.
          content:
            application/json:
              example:
                status: success
                message: Subscription cancelled successfully!
                meta: null
                data: null
                errors: []
                code: 200
                timestamp: '2025-02-28T06:28:32+00:00'
                version: 1.0.0
  /subscriptions/{id}/without-one-off:
    get:
      tags:
        - Subscriptions
      summary: Subscription details excluding one-off products
      description: >-
        Fetch detailed information about a subscription using its unique
        identifier. This endpoint returns the subscription details **excluding
        any one-off products**.
      operationId: getSubscriptionWithoutOneOff
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            example: sub_EsrjpTa0yPenKvOq58wp5WKM
          description: Unique identifier of the subscription.
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            example: application/json
          description: The response format must be JSON.
      responses:
        '200':
          description: Subscription details retrieved successfully.
          content:
            application/json:
              example:
                status: success
                message: Subscription details retrieved!
                meta: null
                data:
                  id: sub_MezhDcoPLVAC8zjHMFhlB5mB
                  status: trialing
                  total_value: 234
                  cycle_start_date: null
                  cancels_at: '2027-12-17'
                  items:
                    - id: si_ERer9e7glQbCnNTHOZjUIfPg
                      sub_total: 191.8
                      tax_amount: 42.2
                      total: 234
                      pricing_option_id: price_0ZyxqCcemqBvqNNqWZ3dMlBk
                      status: active
                      quantity: 1
                      product: gjghjghj
                      product_id: pro_j7sOyIGwbNWhOyoExaF3jdf8
                  created_at: '2025-02-28T06:11:46.000000Z'
                  updated_at: '2025-02-28T06:24:56.000000Z'
                errors: []
                code: 200
                timestamp: '2025-02-28T06:24:56+00:00'
                version: 1.0.0
  /subscriptions/{subscriptionId}/items:
    get:
      tags:
        - SubscriptionItems
      summary: List subscription items
      description: List all items in a specific subscription.
      operationId: listSubscriptionItems
      parameters:
        - name: subscriptionId
          in: path
          required: true
          description: Unique identifier of the subscription
          schema:
            type: string
            example: sub_yizmQhbdxLKXnV1Y87S3Y0pp
        - name: Accept
          in: header
          required: true
          description: Response format must be json
          schema:
            type: string
            example: application/json
      responses:
        '200':
          description: Subscription items retrieved successfully
          content:
            application/json:
              schema:
                type: object
              example:
                status: success
                message: Subscription items retrieved successfully
                data:
                  - id: si-20n2vqQFWMhr4St7
                    product_id: 1
                    pricing_option_id: 1
                    quantity: 2
                code: 200
                timestamp: '2025-02-27T13:20:00+00:00'
                version: 1.0.0
    post:
      tags:
        - SubscriptionItems
      summary: Create subscription item
      description: Create a new item in a specific subscription.
      operationId: createSubscriptionItem
      parameters:
        - name: subscriptionId
          in: path
          required: true
          description: Unique identifier of the subscription
          schema:
            type: string
            example: sub_yizmQhbdxLKXnV1Y87S3Y0pp
        - name: Accept
          in: header
          required: true
          description: Response format must be json
          schema:
            type: string
            example: application/json
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
            example:
              product_id: 1
              pricing_option_id: 1
              quantity: 2
      responses:
        '200':
          description: Subscription item created successfully
          content:
            application/json:
              schema:
                type: object
              example:
                status: success
                message: Subscription item created successfully
                data:
                  id: si-20n2vqQFWMhr4St7
                  product_id: 1
                  pricing_option_id: 1
                  quantity: 2
                code: 200
                timestamp: '2025-02-27T13:25:00+00:00'
                version: 1.0.0
  /subscriptions/{subscriptionId}/items/{itemId}:
    get:
      tags:
        - SubscriptionItems
      summary: Get subscription item
      description: Retrieve details of a specific subscription item.
      operationId: getSubscriptionItem
      parameters:
        - name: subscriptionId
          in: path
          required: true
          description: Unique identifier of the subscription
          schema:
            type: string
            example: sub_yizmQhbdxLKXnV1Y87S3Y0pp
        - name: itemId
          in: path
          required: true
          description: Unique identifier of the subscription item
          schema:
            type: string
            example: si-20n2vqQFWMhr4St7
        - name: Accept
          in: header
          required: true
          description: Response format must be json
          schema:
            type: string
            example: application/json
      responses:
        '200':
          description: Subscription item details retrieved successfully
          content:
            application/json:
              schema:
                type: object
              example:
                status: success
                message: Subscription item details retrieved successfully
                data:
                  id: si-20n2vqQFWMhr4St7
                  product_id: 1
                  pricing_option_id: 1
                  quantity: 2
                code: 200
                timestamp: '2025-02-27T13:30:00+00:00'
                version: 1.0.0
    patch:
      tags:
        - SubscriptionItems
      summary: Update subscription item
      description: Update an existing subscription item.
      operationId: updateSubscriptionItem
      parameters:
        - name: subscriptionId
          in: path
          required: true
          description: Unique identifier of the subscription
          schema:
            type: string
            example: sub_yizmQhbdxLKXnV1Y87S3Y0pp
        - name: itemId
          in: path
          required: true
          description: Unique identifier of the subscription item
          schema:
            type: string
            example: si-20n2vqQFWMhr4St7
        - name: Accept
          in: header
          required: true
          description: Response format must be json
          schema:
            type: string
            example: application/json
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
            example:
              quantity: 1
      responses:
        '200':
          description: Subscription item updated successfully
          content:
            application/json:
              schema:
                type: object
              example:
                status: success
                message: Subscription item updated successfully
                data:
                  id: si-20n2vqQFWMhr4St7
                  quantity: 1
                code: 200
                timestamp: '2025-02-27T13:35:00+00:00'
                version: 1.0.0
    delete:
      tags:
        - SubscriptionItems
      summary: Delete subscription item
      description: Delete a subscription item.
      operationId: deleteSubscriptionItem
      parameters:
        - name: subscriptionId
          in: path
          required: true
          description: Unique identifier of the subscription
          schema:
            type: string
            example: sub_yizmQhbdxLKXnV1Y87S3Y0pp
        - name: itemId
          in: path
          required: true
          description: Unique identifier of the subscription item
          schema:
            type: string
            example: si-20n2vqQFWMhr4St7
        - name: Accept
          in: header
          required: true
          description: Response format must be json
          schema:
            type: string
            example: application/json
      responses:
        '200':
          description: Subscription item deleted successfully
          content:
            application/json:
              schema:
                type: object
              example:
                status: success
                message: Subscription item deleted successfully
                data: null
                code: 200
                timestamp: '2025-02-27T13:40:00+00:00'
                version: 1.0.0
  /payment-links:
    get:
      tags:
        - PaymentLinks
      summary: List payment links
      description: List payment links with optional limit.
      operationId: listPaymentLinks
      parameters:
        - name: limit
          in: query
          required: false
          description: Limit the number of results returned
          schema:
            type: integer
            example: 100
        - name: Accept
          in: header
          required: true
          description: Response format must be json
          schema:
            type: string
            example: application/json
      responses:
        '200':
          description: Payment links retrieved successfully
          content:
            application/json:
              schema:
                type: object
              example:
                status: success
                message: Payment links retrieved successfully
                data:
                  - id: pl_odninxMhEZ0CFSoOLOMfkx6i
                    name: Premium Membership Payment Link
                code: 200
                timestamp: '2025-02-27T12:30:00+00:00'
                version: 1.0.0
    post:
      tags:
        - PaymentLinks
      summary: Create payment link
      description: Create a new payment link.
      operationId: createPaymentLink
      parameters:
        - name: Accept
          in: header
          required: true
          description: Response format must be json
          schema:
            type: string
            example: application/json
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
            example:
              max_payments: null
              success_message: Thank you for your purchase!
              inactive_message: This donations link is closed please look for newer links.
              trial_days: 10
              redirect_url: null
              products:
                - product_id: pro_mUMe9iAzjoEm5GgArWL3lIG0
                  pricing_option_id: price_ZGhjedgcbI0lE9B1nQH5k234
                  quantity: 5
      responses:
        '200':
          description: Payment link created successfully
          content:
            application/json:
              schema:
                type: object
              example:
                status: success
                message: Payment link created successfully
                data:
                  id: pl_keImLPRRNAVFC4MxKi7xEZaD
                  name: Premium Membership Payment Link
                code: 200
                timestamp: '2025-02-27T12:35:00+00:00'
                version: 1.0.0
    delete:
      tags:
        - PaymentLinks
      summary: Delete payment link
      description: Delete one or more payment links.
      operationId: deletePaymentLink
      parameters:
        - name: Accept
          in: header
          required: true
          description: Response format must be json
          schema:
            type: string
            example: application/json
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
            example:
              ids:
                - pl_leDom1TwRazXqqNJF8WtspyR
      responses:
        '200':
          description: Payment link deleted successfully
          content:
            application/json:
              schema:
                type: object
              example:
                status: success
                message: Payment link deleted successfully
                data: null
                code: 200
                timestamp: '2025-02-27T12:40:00+00:00'
                version: 1.0.0
  /payment-links/{id}:
    get:
      tags:
        - PaymentLinks
      summary: Get payment link
      description: Retrieve details of a payment link.
      operationId: getPaymentLink
      parameters:
        - name: id
          in: path
          required: true
          description: Unique identifier of the payment link
          schema:
            type: string
            example: pl_keImLPRRNAVFC4MxKi7xEZaD
        - name: Accept
          in: header
          required: true
          description: Response format must be json
          schema:
            type: string
            example: application/json
      responses:
        '200':
          description: Payment link details retrieved successfully
          content:
            application/json:
              schema:
                type: object
              example:
                status: success
                message: Payment link details retrieved successfully
                data:
                  id: pl_keImLPRRNAVFC4MxKi7xEZaD
                  name: Premium Membership Payment Link
                code: 200
                timestamp: '2025-02-27T12:45:00+00:00'
                version: 1.0.0
    patch:
      tags:
        - PaymentLinks
      summary: Update payment link
      description: Update an existing payment link.
      operationId: updatePaymentLink
      parameters:
        - name: id
          in: path
          required: true
          description: Unique identifier of the payment link
          schema:
            type: string
            example: pl_keImLPRRNAVFC4MxKi7xEZaD
        - name: Accept
          in: header
          required: true
          description: Response format must be json
          schema:
            type: string
            example: application/json
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
            example:
              name: Premium Membership Payment Link
              max_payments: 100
              inactive_message: This link is no longer active
              success_message: Thank you for your purchase!
              trial_days: 14
      responses:
        '200':
          description: Payment link updated successfully
          content:
            application/json:
              schema:
                type: object
              example:
                status: success
                message: Payment link updated successfully
                data:
                  id: pl_keImLPRRNAVFC4MxKi7xEZaD
                  name: Premium Membership Payment Link
                code: 200
                timestamp: '2025-02-27T12:50:00+00:00'
                version: 1.0.0
  /payment-links/{linkId}/items:
    get:
      tags:
        - PaymentLinkItems
      summary: List payment link items
      description: List items for a specific payment link.
      operationId: listPaymentLinkItems
      parameters:
        - name: linkId
          in: path
          required: true
          description: Unique identifier of the payment link
          schema:
            type: string
            example: pl_odninxMhEZ0CFSoOLOMfkx6i
        - name: Accept
          in: header
          required: true
          description: Response format must be json
          schema:
            type: string
            example: application/json
      responses:
        '200':
          description: Payment link items retrieved successfully
          content:
            application/json:
              schema:
                type: object
              example:
                status: success
                message: Payment link items retrieved successfully
                data:
                  - id: pli_N9G4rdQYjltUeVyrHWf9Tn2s
                    product_id: pro_mUMe9iAzjoEm5GgArWL3lIG0
                code: 200
                timestamp: '2025-02-27T12:55:00+00:00'
                version: 1.0.0
    post:
      tags:
        - PaymentLinkItems
      summary: Create payment link item
      description: Create a new item for a payment link.
      operationId: createPaymentLinkItem
      parameters:
        - name: linkId
          in: path
          required: true
          description: Unique identifier of the payment link
          schema:
            type: string
            example: pl_odninxMhEZ0CFSoOLOMfkx6i
        - name: Accept
          in: header
          required: true
          description: Response format must be json
          schema:
            type: string
            example: application/json
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
            example:
              product_id: pro_mUMe9iAzjoEm5GgArWL3lIG0
              pricing_option_id: price_ZGhjedgcbI0lE9B1nQH5k234
              quantity: 2
      responses:
        '200':
          description: Payment link item created successfully
          content:
            application/json:
              schema:
                type: object
              example:
                status: success
                message: Payment link item created successfully
                data:
                  id: pli_N9G4rdQYjltUeVyrHWf9Tn2s
                code: 200
                timestamp: '2025-02-27T13:00:00+00:00'
                version: 1.0.0
  /payment-links/{linkId}/items/{itemId}:
    get:
      tags:
        - PaymentLinkItems
      summary: Get payment link item
      description: Retrieve details of a payment link item.
      operationId: getPaymentLinkItem
      parameters:
        - name: linkId
          in: path
          required: true
          description: Unique identifier of the payment link
          schema:
            type: string
            example: pl_odninxMhEZ0CFSoOLOMfkx6i
        - name: itemId
          in: path
          required: true
          description: Unique identifier of the payment link item
          schema:
            type: string
            example: pli_N9G4rdQYjltUeVyrHWf9Tn2s
        - name: Accept
          in: header
          required: true
          description: Response format must be json
          schema:
            type: string
            example: application/json
      responses:
        '200':
          description: Payment link item details retrieved successfully
          content:
            application/json:
              schema:
                type: object
              example:
                status: success
                message: Payment link item details retrieved successfully
                data:
                  id: pli_N9G4rdQYjltUeVyrHWf9Tn2s
                  product_id: pro_mUMe9iAzjoEm5GgArWL3lIG0
                code: 200
                timestamp: '2025-02-27T13:05:00+00:00'
                version: 1.0.0
    patch:
      tags:
        - PaymentLinkItems
      summary: Update payment link item
      description: Update an existing payment link item.
      operationId: updatePaymentLinkItem
      parameters:
        - name: linkId
          in: path
          required: true
          description: Unique identifier of the payment link
          schema:
            type: string
            example: pl_odninxMhEZ0CFSoOLOMfkx6i
        - name: itemId
          in: path
          required: true
          description: Unique identifier of the payment link item
          schema:
            type: string
            example: pli_N9G4rdQYjltUeVyrHWf9Tn2s
        - name: Accept
          in: header
          required: true
          description: Response format must be json
          schema:
            type: string
            example: application/json
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
            example:
              quantity: 3
      responses:
        '200':
          description: Payment link item updated successfully
          content:
            application/json:
              schema:
                type: object
              example:
                status: success
                message: Payment link item updated successfully
                data:
                  id: pli_N9G4rdQYjltUeVyrHWf9Tn2s
                  quantity: 3
                code: 200
                timestamp: '2025-02-27T13:10:00+00:00'
                version: 1.0.0
    delete:
      tags:
        - PaymentLinkItems
      summary: Delete payment link item
      description: Delete a payment link item.
      operationId: deletePaymentLinkItem
      parameters:
        - name: linkId
          in: path
          required: true
          description: Unique identifier of the payment link
          schema:
            type: string
            example: pl_odninxMhEZ0CFSoOLOMfkx6i
        - name: itemId
          in: path
          required: true
          description: Unique identifier of the payment link item
          schema:
            type: string
            example: pli_N9G4rdQYjltUeVyrHWf9Tn2s
        - name: Accept
          in: header
          required: true
          description: Response format must be json
          schema:
            type: string
            example: application/json
      responses:
        '200':
          description: Payment link item deleted successfully
          content:
            application/json:
              schema:
                type: object
              example:
                status: success
                message: Payment link item deleted successfully
                data: null
                code: 200
                timestamp: '2025-02-27T13:15:00+00:00'
                version: 1.0.0
  /taxes/codes:
    get:
      tags:
        - Calculate Taxes
      summary: Tax codes
      description: >-
        Retrieve a list of available tax codes, including their names and
        descriptions. These tax codes can be used to classify products or
        services for automated tax calculation.
      operationId: getTaxCodes
      parameters:
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            example: application/json
          description: The response format must be JSON.
      responses:
        '200':
          description: List of available tax codes retrieved successfully.
          content:
            application/json:
              example:
                status: success
                message: Operation successful.
                meta: null
                data:
                  - id: standard
                    description: >-
                      Any taxable good or service. For jurisdictions that impose
                      a tax, the standard rate is applied.
                    name: Generally taxable
                  - id: saas
                    description: >-
                      Cloud services software delivered over the internet. The
                      software is not customized for the specific buyer. Assumes
                      no software is downloaded by the buyer.
                    name: Software as a service (SaaS)
                errors: null
                code: 200
                timestamp: '2025-10-10T07:31:03+00:00'
                version: 1.0.0
  /taxes/calculate:
    post:
      tags:
        - Calculate Taxes
      summary: Calculate tax
      description: >-
        Calculate tax based on the provided location, product details, and
        amount.


        **Note:**

        - The `to_state` field is required for validating the postal code.

        - The tax is calculated using the provided `to_country`,
        `to_postal_code`, `to_state`, `to_city`, `tax_code`, `product_type`, and
        `amount` fields.

        - The response returns tax details such as rate, subtotal, tax amount,
        total amount, and applicable region information.
      operationId: calculateTax
      parameters:
        - name: tax_account_id
          in: query
          required: true
          schema:
            type: number
            example: 12345
          description: Your Tax Account ID.
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            example: application/json
          description: The response format must be JSON.
      requestBody:
        required: true
        content:
          application/json:
            example:
              to_country: US
              to_postal_code: '15006'
              to_state: PA
              to_city: Bairdford
              tax_code: standard
              product_type: service
              amount: '199.99'
      responses:
        '200':
          description: Tax calculated successfully.
          content:
            application/json:
              example:
                status: success
                message: Success
                meta: null
                data:
                  city: null
                  country: US
                  county: null
                  currency: USD
                  name: Sales tax
                  notes: null
                  notice: >-
                    Only state tax rates are returned in test mode. Local tax
                    rates will be returned only in live mode except for the
                    following test zip codes: 90049,10128,60611,33132,33206.
                  product_type: service
                  rate: 6
                  region: PA
                  tax_behavior: exclusive
                  tax_code: standard
                  taxable_part: 100
                  import: false
                  subtotal: 199.99
                  tax_amount: 12
                  total_amount: 211.99
                  status: taxable
                errors: null
                code: 200
                timestamp: '2025-10-10T07:14:52+00:00'
                version: 1.0.0
