> ## Documentation Index
> Fetch the complete documentation index at: https://docs.numeral.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Platform Calculations

> Calculate taxes for marketplace and platform transactions

Calculate taxes for marketplace/platform transactions where a merchant (seller) is involved. This endpoint is designed for marketplaces, payment processors, and other platforms that facilitate transactions between buyers and sellers.

## Headers

<ParamField header="Authorization" type="string" required>
  Bearer token authentication.
</ParamField>

<ParamField header="X-API-Version" type="string" required>
  Must be `2026-03-01` for platform calculations.
</ParamField>

## Request Body

<ParamField body="customer" type="object" required>
  The customer (buyer) information.

  <Expandable title="Customer Properties">
    <ParamField body="type" type="string" default="CONSUMER">
      Either `CONSUMER` or `BUSINESS`.
    </ParamField>

    <ParamField body="tax_ids" type="array">
      Array of customer tax IDs (for B2B transactions).
    </ParamField>

    <ParamField body="address" type="object">
      Customer's address including `address_type` (shipping or billing). At least one of `address` or `ip` must be provided.
    </ParamField>

    <ParamField body="ip" type="object">
      Customer IP address for geo-based tax resolution. At least one of `address` or `ip` must be provided.

      <Expandable title="IP Properties">
        <ParamField body="value" type="string" required>
          A valid IPv4 or IPv6 address.
        </ParamField>

        <ParamField body="resolution" type="string" default="strict">
          Resolution strategy: `strict`, `zero`, `approximate`, or `best_effort`. Numeral strongly recommends `strict` mode to stay as compliant as possible.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="merchant" type="object" required>
  The merchant (seller) involved in this transaction.

  <Expandable title="Merchant Properties">
    <ParamField body="merchant_id" type="string" required>
      The merchant ID (`merch_xxx`) or your `reference_merchant_id`.
    </ParamField>

    <ParamField body="type" type="string" default="BUSINESS">
      Either `BUSINESS` or `INDIVIDUAL`.
    </ParamField>

    <ParamField body="tax_ids" type="array">
      Override merchant's stored tax IDs for this calculation.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="order_details" type="object" required>
  Order details including line items.

  <Expandable title="Order Details Properties">
    <ParamField body="customer_currency_code" type="string" required>
      ISO 4217 currency code (e.g., `USD`, `EUR`).
    </ParamField>

    <ParamField body="tax_included_in_amount" type="boolean" required>
      Whether the amount includes tax.
    </ParamField>

    <ParamField body="automatic_tax" type="string" required>
      One of `auto`, `disabled`, or `forced`. **Required from API version 2025-05-12+**.

      * `auto` - Return real rates only in jurisdictions where you have an active tax registration. Returns 0 elsewhere.
      * `disabled` - Always return 0 tax rates regardless of registration status.
      * `forced` - Return real destination-based rates regardless of your own nexus/registration status. Useful for payment processors that need to surface the rates a merchant would owe without their own collection configuration gating the response. Only valid when `roles` is exactly `["payment_processor"]`. Customer-level rules (exemptions, reverse-charge, B2B logic) still apply.

      <Note>
        For US customer addresses, `automatic_tax` must be `auto` or `forced` — `disabled` is rejected because US addresses must always compute tax.
      </Note>
    </ParamField>

    <ParamField body="line_items" type="array" required>
      Array of line items. **Remember: amount is per-unit!**
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="roles" type="array" required>
  Your role(s) in this transaction. One or more of:

  * `marketplace_provider` - You operate a marketplace connecting buyers and sellers
  * `payment_processor` - You process payments for the transaction
  * `merchant_of_record` - You are the legal seller of record
</ParamField>

<ParamField body="fee_details" type="object">
  Optional: Details for platform fees to be taxed separately. Same structure as `order_details`, except `automatic_tax` only accepts `auto` or `disabled` — fees represent the platform's own tax event toward the merchant and must honor the platform's own nexus configuration.
</ParamField>

<ParamField body="transacted_at" type="integer">
  Optional. The time the transaction occurred, as a Unix timestamp in **seconds**. Used to determine which tax rates and rules apply at the time of the transaction (for example, during a sales tax holiday). If omitted, the calculation uses the current time.
</ParamField>

## Line Item Properties

<ParamField body="amount" type="integer" required>
  **Per-unit price** in the smallest currency unit (e.g., cents for USD).

  For a \$25.00 item: `amount: 2500`
</ParamField>

<ParamField body="quantity" type="integer" required>
  Number of units. The taxable base = `amount × quantity`.
</ParamField>

<ParamField body="product_category" type="string">
  Tax category code (e.g., `GENERAL_MERCHANDISE`, `SAAS_GENERAL`).
</ParamField>

<ParamField body="reference_product_id" type="string">
  Reference to a pre-created product.
</ParamField>

<ParamField body="reference_line_item_id" type="string">
  Your ID for this line item.
</ParamField>

## Response

<ResponseField name="id" type="string">
  The calculation ID.
</ResponseField>

<ResponseField name="object" type="string">
  Always `tax.calculation`.
</ResponseField>

<ResponseField name="line_items" type="array">
  Tax calculations for order line items.
</ResponseField>

<ResponseField name="fee_line_items" type="array">
  Tax calculations for fee line items (only present when `fee_details` provided).
</ResponseField>

<ResponseField name="totals" type="object">
  Summary totals for order and fees.

  <Expandable title="Totals Properties">
    <ResponseField name="order" type="object">
      Order totals: `tax_amount`, `amount_excluding_tax`, `amount_including_tax`.
    </ResponseField>

    <ResponseField name="fees" type="object">
      Fee totals (only present when `fee_details` provided).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="merchant" type="object">
  The merchant used in this calculation.
</ResponseField>

<ResponseField name="roles" type="array">
  The roles you specified.
</ResponseField>

### Enhanced Response Fields

Platform calculations include additional tax jurisdiction details:

<ResponseField name="tax_authority_name" type="string">
  Name of the tax authority (e.g., "California State").
</ResponseField>

<ResponseField name="tax_authority_type" type="string">
  Type of authority: `STATE`, `COUNTY`, `CITY`, or `DISTRICT`.
</ResponseField>

<ResponseField name="tax_type" type="string">
  Type of tax: `SALES`, `USE`, `VAT`, or `GST`.
</ResponseField>

### IP Resolution Response Fields

<ResponseField name="location_source" type="string">
  `"address"` or `"ip"` -- indicates which input was used for tax determination.
</ResponseField>

<ResponseField name="resolution_precision" type="string">
  Precision of the resolved location: `STREET`, `POSTAL_PLUS`, `POSTAL`, `PROVINCE`, `COUNTRY`, or `APPROXIMATED`.
</ResponseField>

<ResponseField name="address_used" type="object">
  The address actually used for tax calculation, populated even when using IP-based resolution.
</ResponseField>

<RequestExample>
  ```bash Basic Marketplace theme={null}
  curl -X POST https://api.numeralhq.com/tax/platform/calculations \
    -H "Authorization: Bearer sk_test_xxx" \
    -H "X-API-Version: 2026-03-01" \
    -H "Content-Type: application/json" \
    -d '{
      "customer": {
        "address": {
          "address_line_1": "100 Market St",
          "address_city": "San Francisco",
          "address_province": "CA",
          "address_postal_code": "94105",
          "address_country": "US"
        }
      },
      "merchant": {
        "merchant_id": "my-seller-123"
      },
      "order_details": {
        "customer_currency_code": "USD",
        "tax_included_in_amount": false,
        "automatic_tax": "auto",
        "line_items": [
          {
            "amount": 2500,
            "quantity": 3,
            "product_category": "GENERAL_MERCHANDISE"
          }
        ]
      },
      "roles": ["marketplace_provider"]
    }'
  ```

  ```bash IP-Based Resolution theme={null}
  curl -X POST https://api.numeralhq.com/tax/platform/calculations \
    -H "Authorization: Bearer sk_test_xxx" \
    -H "X-API-Version: 2026-03-01" \
    -H "Content-Type: application/json" \
    -d '{
      "customer": {
        "type": "CONSUMER",
        "ip": {
          "value": "217.217.113.167",
          "resolution": "strict"
        }
      },
      "merchant": {
        "merchant_id": "my-seller-123"
      },
      "order_details": {
        "customer_currency_code": "USD",
        "tax_included_in_amount": false,
        "automatic_tax": "auto",
        "line_items": [
          {
            "amount": 2500,
            "quantity": 3,
            "product_category": "GENERAL_MERCHANDISE"
          }
        ]
      },
      "roles": ["marketplace_provider"]
    }'
  ```

  ```bash With Platform Fees theme={null}
  curl -X POST https://api.numeralhq.com/tax/platform/calculations \
    -H "Authorization: Bearer sk_test_xxx" \
    -H "X-API-Version: 2026-03-01" \
    -H "Content-Type: application/json" \
    -d '{
      "customer": {
        "address": {
          "address_line_1": "100 Market St",
          "address_city": "San Francisco",
          "address_province": "CA",
          "address_postal_code": "94105",
          "address_country": "US"
        }
      },
      "merchant": {
        "merchant_id": "my-seller-123"
      },
      "order_details": {
        "customer_currency_code": "USD",
        "tax_included_in_amount": false,
        "automatic_tax": "auto",
        "line_items": [
          {
            "amount": 5000,
            "quantity": 2,
            "product_category": "GENERAL_MERCHANDISE"
          }
        ]
      },
      "roles": ["payment_processor"],
      "fee_details": {
        "customer_currency_code": "USD",
        "tax_included_in_amount": false,
        "automatic_tax": "auto",
        "line_items": [
          {
            "amount": 299,
            "quantity": 1,
            "product_category": "ELECTRONIC_GOODS"
          }
        ]
      }
    }'
  ```

  ```bash Payment Processor — Forced Rates theme={null}
  # Returns destination-based rates regardless of the caller's own nexus.
  # Use this when you (the payment processor) need to surface the rates the
  # merchant would owe, without your own registration footprint gating the response.
  curl -X POST https://api.numeralhq.com/tax/platform/calculations \
    -H "Authorization: Bearer sk_test_xxx" \
    -H "X-API-Version: 2026-03-01" \
    -H "Content-Type: application/json" \
    -d '{
      "customer": {
        "address": {
          "address_line_1": "100 Market St",
          "address_city": "San Francisco",
          "address_province": "CA",
          "address_postal_code": "94105",
          "address_country": "US"
        }
      },
      "merchant": {
        "merchant_id": "my-seller-123"
      },
      "order_details": {
        "customer_currency_code": "USD",
        "tax_included_in_amount": false,
        "automatic_tax": "forced",
        "line_items": [
          {
            "amount": 2500,
            "quantity": 3,
            "product_category": "GENERAL_MERCHANDISE"
          }
        ]
      },
      "roles": ["payment_processor"]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Basic Response theme={null}
  {
    "id": "calc_platform_123456789",
    "object": "tax.calculation",
    "testmode": true,
    "customer_currency_code": "USD",
    "line_items": [
      {
        "product": {
          "product_tax_code": "GENERAL_MERCHANDISE"
        },
        "tax_jurisdictions": [
          {
            "tax_rate": 0.0875,
            "rate_type": "SALES TAX",
            "jurisdiction_name": "California",
            "tax_authority_name": "California State",
            "tax_authority_type": "STATE",
            "tax_type": "SALES",
            "fee_amount": 0
          }
        ],
        "quantity": 3,
        "tax_amount": 656,
        "amount_excluding_tax": 7500,
        "amount_including_tax": 8156
      }
    ],
    "totals": {
      "order": {
        "tax_amount": 656,
        "amount_excluding_tax": 7500,
        "amount_including_tax": 8156
      }
    },
    "merchant": {
      "id": "merch_abc123",
      "reference_merchant_id": "my-seller-123"
    },
    "roles": ["marketplace_provider"],
    "expires_at": 1735690200
  }
  ```

  ```json 200 - With Fees theme={null}
  {
    "id": "calc_platform_987654321",
    "object": "tax.calculation",
    "testmode": true,
    "customer_currency_code": "USD",
    "line_items": [
      {
        "product": {
          "product_tax_code": "GENERAL_MERCHANDISE"
        },
        "tax_jurisdictions": [
          {
            "tax_rate": 0.0875,
            "rate_type": "SALES TAX",
            "jurisdiction_name": "California",
            "tax_authority_name": "California State",
            "tax_authority_type": "STATE",
            "tax_type": "SALES",
            "fee_amount": 0
          }
        ],
        "quantity": 2,
        "tax_amount": 875,
        "amount_excluding_tax": 10000,
        "amount_including_tax": 10875
      }
    ],
    "fee_line_items": [
      {
        "product": {
          "product_tax_code": "ELECTRONIC_GOODS"
        },
        "tax_jurisdictions": [
          {
            "tax_rate": 0.0875,
            "rate_type": "SALES TAX",
            "jurisdiction_name": "California",
            "tax_authority_name": "California State",
            "tax_authority_type": "STATE",
            "tax_type": "SALES",
            "fee_amount": 0
          }
        ],
        "quantity": 1,
        "tax_amount": 26,
        "amount_excluding_tax": 299,
        "amount_including_tax": 325
      }
    ],
    "totals": {
      "order": {
        "tax_amount": 875,
        "amount_excluding_tax": 10000,
        "amount_including_tax": 10875
      },
      "fees": {
        "tax_amount": 26,
        "amount_excluding_tax": 299,
        "amount_including_tax": 325
      }
    },
    "merchant": {
      "id": "merch_abc123",
      "reference_merchant_id": "my-seller-123"
    },
    "roles": ["payment_processor"],
    "expires_at": 1735690200
  }
  ```

  ```json 404 - Merchant Not Found theme={null}
  {
    "error": {
      "error_code": "merchant_not_found",
      "error_message": "Merchant not found or belongs to different testmode"
    }
  }
  ```
</ResponseExample>


## OpenAPI

````yaml POST /tax/platform/calculations
openapi: 3.0.1
info:
  title: Numeral API
  description: >-
    API for sales tax calculations - Version 2026-01-01. This version introduces
    Merchant management and Platform Calculations for marketplace and payment
    processor scenarios.
  license:
    name: MIT
  version: '2026-01-01'
servers:
  - url: https://api.numeralhq.com/
security:
  - bearerAuth: []
paths:
  /tax/platform/calculations:
    post:
      summary: Platform Calculation
      description: >-
        Calculate taxes for marketplace/platform transactions where a merchant
        is involved. **Important: In this endpoint, `amount` is per-unit. The
        taxable base is calculated as `amount × quantity`.**
      operationId: platformCalculation_v20260101
      parameters:
        - name: X-API-Version
          in: header
          required: true
          schema:
            type: string
            enum:
              - '2026-01-01'
          description: API version. Must be 2026-01-01 for platform calculations.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlatformCalculationRequest'
            examples:
              marketplace_basic:
                summary: Basic marketplace calculation
                description: >-
                  A marketplace facilitating a sale. Note: amount (2500) ×
                  quantity (3) = $75.00 taxable base
                value:
                  customer:
                    address:
                      address_line_1: 100 Market St
                      address_city: San Francisco
                      address_province: CA
                      address_postal_code: '94105'
                      address_country: US
                  merchant:
                    merchant_id: my-seller-123
                  order_details:
                    customer_currency_code: USD
                    tax_included_in_amount: false
                    automatic_tax: auto
                    line_items:
                      - amount: 2500
                        quantity: 3
                        product_category: GENERAL_MERCHANDISE
                  roles:
                    - marketplace_provider
              with_fees:
                summary: Platform with fee calculation
                description: >-
                  Payment processor collecting both order tax and platform fee
                  tax
                value:
                  customer:
                    address:
                      address_line_1: 100 Market St
                      address_city: San Francisco
                      address_province: CA
                      address_postal_code: '94105'
                      address_country: US
                  merchant:
                    merchant_id: my-seller-123
                  order_details:
                    customer_currency_code: USD
                    tax_included_in_amount: false
                    automatic_tax: auto
                    line_items:
                      - amount: 5000
                        quantity: 2
                        product_category: GENERAL_MERCHANDISE
                  roles:
                    - payment_processor
                  fee_details:
                    customer_currency_code: USD
                    tax_included_in_amount: false
                    automatic_tax: auto
                    line_items:
                      - amount: 299
                        quantity: 1
                        product_category: ELECTRONIC_GOODS
              business_customer:
                summary: B2B platform transaction
                value:
                  customer:
                    type: BUSINESS
                    tax_ids:
                      - type: gb_vat
                        value: GB123456789
                    address:
                      address_line_1: 10 Business Park
                      address_city: London
                      address_province: LND
                      address_postal_code: EC1A 1BB
                      address_country: GB
                      address_type: billing
                  merchant:
                    merchant_id: eu-seller-456
                    type: BUSINESS
                    tax_ids:
                      - type: de_vat
                        value: DE987654321
                  order_details:
                    customer_currency_code: EUR
                    tax_included_in_amount: false
                    automatic_tax: auto
                    line_items:
                      - amount: 10000
                        quantity: 5
                        product_category: SAAS_GENERAL
                  roles:
                    - marketplace_provider
        required: true
      responses:
        '200':
          description: Platform calculation response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformCalculationResponse'
              examples:
                basic_response:
                  summary: Basic platform calculation response
                  value:
                    id: calc_platform_123456789
                    object: tax.calculation
                    testmode: true
                    customer_currency_code: USD
                    line_items:
                      - product:
                          product_tax_code: GENERAL_MERCHANDISE
                        tax_jurisdictions:
                          - tax_rate: 0.0875
                            rate_type: SALES TAX
                            jurisdiction_name: California
                            tax_authority_name: California State
                            tax_authority_type: STATE
                            tax_type: SALES
                            fee_amount: 0
                        quantity: 3
                        tax_amount: 656
                        amount_excluding_tax: 7500
                        amount_including_tax: 8156
                    totals:
                      order:
                        tax_amount: 656
                        amount_excluding_tax: 7500
                        amount_including_tax: 8156
                    merchant:
                      id: merch_abc123
                      reference_merchant_id: my-seller-123
                    roles:
                      - marketplace_provider
                with_fees_response:
                  summary: Response with fee calculations
                  value:
                    id: calc_platform_987654321
                    object: tax.calculation
                    testmode: true
                    customer_currency_code: USD
                    line_items:
                      - product:
                          product_tax_code: GENERAL_MERCHANDISE
                        tax_jurisdictions:
                          - tax_rate: 0.0875
                            rate_type: SALES TAX
                            jurisdiction_name: California
                            tax_authority_name: California State
                            tax_authority_type: STATE
                            tax_type: SALES
                            fee_amount: 0
                        quantity: 2
                        tax_amount: 875
                        amount_excluding_tax: 10000
                        amount_including_tax: 10875
                    fee_line_items:
                      - product:
                          product_tax_code: ELECTRONIC_GOODS
                        tax_jurisdictions:
                          - tax_rate: 0.0875
                            rate_type: SALES TAX
                            jurisdiction_name: California
                            tax_authority_name: California State
                            tax_authority_type: STATE
                            tax_type: SALES
                            fee_amount: 0
                        quantity: 1
                        tax_amount: 26
                        amount_excluding_tax: 299
                        amount_including_tax: 325
                    totals:
                      order:
                        tax_amount: 875
                        amount_excluding_tax: 10000
                        amount_including_tax: 10875
                      fees:
                        tax_amount: 26
                        amount_excluding_tax: 299
                        amount_including_tax: 325
                    merchant:
                      id: merch_abc123
                      reference_merchant_id: my-seller-123
                    roles:
                      - payment_processor
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Merchant not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MerchantNotFoundError'
components:
  schemas:
    PlatformCalculationRequest:
      type: object
      description: Request body for platform/marketplace tax calculations
      properties:
        customer:
          $ref: '#/components/schemas/PlatformCustomer'
        merchant:
          $ref: '#/components/schemas/PlatformMerchant'
        order_details:
          $ref: '#/components/schemas/PlatformOrderDetails'
        roles:
          type: array
          description: Your role(s) in this transaction
          items:
            type: string
            enum:
              - marketplace_provider
              - payment_processor
              - merchant_of_record
          example:
            - marketplace_provider
        fee_details:
          $ref: '#/components/schemas/PlatformFeeDetails'
          description: 'Optional: Details for platform fees to be taxed separately'
      required:
        - customer
        - merchant
        - order_details
        - roles
    PlatformCalculationResponse:
      type: object
      properties:
        id:
          type: string
          example: calc_platform_123456789
        object:
          type: string
          example: tax.calculation
        testmode:
          type: boolean
        customer_currency_code:
          type: string
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/PlatformCalculationLineItem'
        fee_line_items:
          type: array
          description: >-
            Tax calculations for platform fees (only present when fee_details
            provided)
          items:
            $ref: '#/components/schemas/PlatformCalculationLineItem'
        totals:
          type: object
          properties:
            order:
              $ref: '#/components/schemas/TotalsSummary'
            fees:
              $ref: '#/components/schemas/TotalsSummary'
              description: Only present when fee_details provided
        merchant:
          type: object
          properties:
            id:
              type: string
            reference_merchant_id:
              type: string
        roles:
          type: array
          items:
            type: string
        expires_at:
          type: number
    Error:
      type: object
      description: Standard error response format for API version 2026-01-01
      properties:
        code:
          type: integer
          description: HTTP status code
          example: 400
        type:
          type: string
          description: Machine-readable error type
          example: MISSING_FIELD
        message:
          type: string
          description: Human-readable error message
          example: Required field 'address_country' is missing
      required:
        - code
        - type
        - message
    MerchantNotFoundError:
      type: object
      properties:
        code:
          type: integer
          example: 404
        type:
          type: string
          example: MERCHANT_NOT_FOUND
        message:
          type: string
          example: Merchant not found or belongs to different testmode
    PlatformCustomer:
      type: object
      properties:
        type:
          type: string
          enum:
            - CONSUMER
            - BUSINESS
          description: The type of customer
          default: CONSUMER
        tax_ids:
          type: array
          items:
            $ref: '#/components/schemas/TaxId'
        address:
          allOf:
            - $ref: '#/components/schemas/Address'
            - type: object
              properties:
                address_type:
                  type: string
                  enum:
                    - shipping
                    - billing
      required:
        - address
    PlatformMerchant:
      type: object
      description: The merchant (seller) involved in this platform transaction
      properties:
        merchant_id:
          type: string
          description: The merchant ID (merch_xxx) or your reference_merchant_id
          example: my-seller-123
        type:
          type: string
          enum:
            - BUSINESS
            - INDIVIDUAL
          description: The merchant's business type
          default: BUSINESS
        tax_ids:
          type: array
          description: Override merchant's stored tax IDs for this calculation
          items:
            $ref: '#/components/schemas/TaxId'
      required:
        - merchant_id
    PlatformOrderDetails:
      type: object
      properties:
        customer_currency_code:
          type: string
          example: USD
        tax_included_in_amount:
          type: boolean
          default: false
        automatic_tax:
          type: string
          enum:
            - auto
            - disabled
            - forced
          default: auto
          description: >-
            Controls automatic tax behavior for order line items. `auto`: return
            real rates only in jurisdictions where you have an active tax
            registration. `disabled`: always return 0 tax rates regardless of
            registration status. `forced`: return real destination-based rates
            regardless of your own nexus/registration status — for use by
            payment processors that need to surface merchant-applicable rates
            without their own collection configuration gating the response.
            `forced` is only valid when `roles` is exactly
            `["payment_processor"]`.
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/PlatformLineItem'
      required:
        - customer_currency_code
        - tax_included_in_amount
        - line_items
    PlatformFeeDetails:
      type: object
      description: >-
        Details for platform fees to be taxed separately. Same shape as
        `order_details`, but `automatic_tax` cannot be `forced` — fees represent
        the platform's own tax event toward the merchant and must honor the
        platform's own nexus configuration.
      properties:
        customer_currency_code:
          type: string
          example: USD
        tax_included_in_amount:
          type: boolean
          default: false
        automatic_tax:
          type: string
          enum:
            - auto
            - disabled
          default: auto
          description: >-
            Controls automatic tax behavior for fee line items. `auto`: return
            real rates only in jurisdictions where you have an active tax
            registration. `disabled`: always return 0 tax rates regardless of
            registration status.
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/PlatformLineItem'
      required:
        - customer_currency_code
        - tax_included_in_amount
        - line_items
    PlatformCalculationLineItem:
      type: object
      properties:
        product:
          type: object
          properties:
            reference_product_id:
              type: string
            reference_line_item_id:
              type: string
            product_tax_code:
              type: string
        tax_jurisdictions:
          type: array
          items:
            type: object
            properties:
              tax_rate:
                type: number
              rate_type:
                type: string
              jurisdiction_name:
                type: string
              tax_authority_name:
                type: string
                description: Name of the tax authority
              tax_authority_type:
                type: string
                description: Type of authority (STATE, COUNTY, CITY, DISTRICT)
              tax_type:
                type: string
                description: Type of tax (SALES, USE, VAT, GST)
              fee_amount:
                type: number
        quantity:
          type: integer
        tax_amount:
          type: integer
        amount_excluding_tax:
          type: integer
        amount_including_tax:
          type: integer
    TotalsSummary:
      type: object
      properties:
        tax_amount:
          type: integer
          description: Total tax in smallest currency unit
        amount_excluding_tax:
          type: integer
          description: Total before tax
        amount_including_tax:
          type: integer
          description: Total including tax
    TaxId:
      type: object
      properties:
        type:
          type: string
          description: >-
            Stripe-style tax ID type. See [Tax IDs](/essentials/tax-ids) for the
            full list of supported types.
          example: us_ein
        value:
          type: string
          description: The tax ID value
          example: 12-3456789
      required:
        - type
        - value
    Address:
      type: object
      properties:
        address_line_1:
          type: string
          example: 3990 N County Rd 300 E
        address_line_2:
          type: string
          example: Unit 2
        address_city:
          type: string
          example: Danville
        address_province:
          type: string
          description: >-
            The state, province, or region of the transaction. Must be a valid 2
            digit ISO 3166-2 subdivision code.
          example: IN
        address_postal_code:
          type: string
          example: '46122'
        address_country:
          type: string
          description: >-
            The country code of the transaction. Must be a valid ISO 3166-1
            alpha-2 country code.
          example: US
      required:
        - address_line_1
        - address_city
        - address_province
        - address_postal_code
        - address_country
    PlatformLineItem:
      type: object
      description: >-
        Line item for platform calculations. **Important: amount is PER-UNIT.
        Total = amount × quantity.**
      properties:
        reference_line_item_id:
          type: string
          description: Your ID for this line item
        reference_product_id:
          type: string
          description: Reference to a pre-created product
        product_category:
          type: string
          description: Tax category code
          example: GENERAL_MERCHANDISE
        amount:
          type: integer
          description: >-
            **PER-UNIT price** in smallest currency unit. For $25.00 items, use
            2500. Total taxable = amount × quantity.
          example: 2500
        quantity:
          type: integer
          description: Number of units. Taxable base = amount × quantity.
          example: 3
          minimum: 0
      required:
        - amount
        - quantity
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````