> ## 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.

# Create Platform Transactions

> Record completed sales from a platform calculation. For payment processors, this creates two transactions: one for the order and one for the fee. For marketplace providers or merchants of record, only the order transaction is created.

## Platform Transactions Endpoint (2026-03-01)

Convert a platform calculation into recorded transactions for tax reporting and filing purposes.

<Note>
  Remember to include the `X-API-Version: 2026-03-01` header in your request to use this API version.
</Note>

## How Platform Transactions Work

When you create a platform transaction from a platform calculation, the number of transactions created depends on your platform role:

| Platform Role          | Order Transaction                                    | Fee Transaction                           |
| ---------------------- | ---------------------------------------------------- | ----------------------------------------- |
| `payment_processor`    | Created with `client_role: ["payment_processor"]`    | Created separately with `client_role: []` |
| `marketplace_provider` | Created with `client_role: ["marketplace_provider"]` | No separate fee transaction               |
| `merchant_of_record`   | Created with `client_role: ["merchant_of_record"]`   | No separate fee transaction               |

### Payment Processor Behavior

Payment processors (like Stripe) receive **two separate transactions**:

1. **Order Transaction** - Records the merchant's sale with taxes calculated on the order items
2. **Fee Transaction** - Records the platform fee with applicable taxes

This separation allows for proper tax reporting where the platform fee tax liability may differ from the order tax liability.

### Marketplace Provider / Merchant of Record Behavior

Marketplace providers and merchants of record receive a **single transaction** that includes all order items. Fee taxes (if calculated) are included in the same transaction.

## Transaction Types

The `type` field in each transaction indicates what it represents:

* `order` - A transaction for the actual sale/order
* `fee` - A transaction specifically for platform fees (payment processors only)

## Example Workflow

```bash theme={null}
# Step 1: Create a platform calculation
curl -X POST https://api.numeralhq.com/tax/platform/calculations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-API-Version: 2026-03-01" \
  -d '{
    "merchant_id": "merch_abc123",
    "line_items": [...],
    "fee_details": {...}
  }'

# Step 2: Convert to transactions when payment is complete
curl -X POST https://api.numeralhq.com/tax/platform/transactions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-API-Version: 2026-03-01" \
  -d '{
    "platform_calculation_id": "plat_calc_abc123",
    "reference_order_id": "order_12345",
    "reference_payment_id": "pay_67890",
    "transaction_processed_at": 1736300000
  }'
```

## Response Structure

The response is always a list containing one or more transactions:

```json theme={null}
{
  "object": "list",
  "transactions": [
    {
      "id": "tr_abc123",
      "object": "tax.transaction",
      "type": "order",
      "client_role": ["payment_processor"],
      "merchant": {
        "id": "merch_abc123",
        "reference_merchant_id": "my-seller-123"
      }
      // ... additional fields
    },
    {
      "id": "tr_def456",
      "object": "tax.transaction",
      "type": "fee",
      "client_role": [],
      "merchant": {
        "id": "merch_abc123",
        "reference_merchant_id": "my-seller-123"
      }
      // ... additional fields (payment_processor only)
    }
  ]
}
```


## OpenAPI

````yaml POST /tax/platform/transactions
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/transactions:
    post:
      summary: Create Platform Transaction
      description: >-
        Record completed sales from a platform calculation. For payment
        processors, this creates two transactions: one for the order and one for
        the fee. For marketplace providers or merchants of record, only the
        order transaction is created.
      operationId: createPlatformTransaction_v20260101
      parameters:
        - name: X-API-Version
          in: header
          required: true
          schema:
            type: string
            enum:
              - '2026-01-01'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlatformTransactionRequest'
            example:
              platform_calculation_id: plat_calc_abc123
              reference_order_id: order_12345
              reference_payment_id: pay_67890
              transaction_processed_at: 1736300000
        required: true
      responses:
        '200':
          description: Platform transaction list response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformTransactionListResponse'
              examples:
                payment_processor:
                  summary: Payment Processor (creates order + fee transactions)
                  value:
                    object: list
                    transactions:
                      - id: tr_abc123
                        object: tax.transaction
                        calculation_id: plat_calc_abc123
                        reference_order_id: order_12345
                        type: order
                        client_role:
                          - payment_processor
                        merchant:
                          id: merch_abc123
                          reference_merchant_id: my-seller-123
                        testmode: false
                      - id: tr_def456
                        object: tax.transaction
                        calculation_id: plat_calc_abc123
                        reference_order_id: order_12345
                        type: fee
                        client_role: []
                        merchant:
                          id: merch_abc123
                          reference_merchant_id: my-seller-123
                        testmode: false
                marketplace_provider:
                  summary: Marketplace Provider (creates order transaction only)
                  value:
                    object: list
                    transactions:
                      - id: tr_abc123
                        object: tax.transaction
                        calculation_id: plat_calc_abc123
                        reference_order_id: order_12345
                        type: order
                        client_role:
                          - marketplace_provider
                        merchant:
                          id: merch_abc123
                          reference_merchant_id: my-seller-123
                        testmode: false
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Platform calculation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformCalculationNotFoundError'
components:
  schemas:
    PlatformTransactionRequest:
      type: object
      description: Request body for creating transactions from a platform calculation
      properties:
        platform_calculation_id:
          type: string
          description: The ID of the platform calculation to convert to transactions
        reference_order_id:
          type: string
          description: Your unique identifier for this order
        reference_payment_id:
          type: string
          description: Your unique identifier for the payment (optional)
        transaction_processed_at:
          type: number
          description: Unix timestamp when the transaction was processed
      required:
        - platform_calculation_id
        - reference_order_id
    PlatformTransactionListResponse:
      type: object
      description: >-
        Response containing the list of created transactions. Payment processors
        receive two transactions (order + fee), while marketplace providers and
        merchants of record receive one.
      properties:
        object:
          type: string
          example: list
        transactions:
          type: array
          items:
            $ref: '#/components/schemas/PlatformTransactionItem'
    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
    PlatformCalculationNotFoundError:
      type: object
      properties:
        code:
          type: integer
          example: 404
        type:
          type: string
          example: CALCULATION_NOT_FOUND
        message:
          type: string
          example: Platform calculation not found
    PlatformTransactionItem:
      type: object
      description: A transaction created from a platform calculation
      properties:
        id:
          type: string
          description: Unique identifier for the transaction
        object:
          type: string
          example: tax.transaction
        calculation_id:
          type: string
          description: The platform calculation ID this transaction was created from
        reference_order_id:
          type: string
          description: Your reference order ID
        reference_payment_id:
          type: string
          description: Your reference payment ID (if provided)
        type:
          type: string
          enum:
            - order
            - fee
          description: Whether this is an order transaction or a fee transaction
        client_role:
          type: array
          items:
            type: string
            enum:
              - payment_processor
              - marketplace_provider
              - merchant_of_record
          description: >-
            The platform role(s) for this transaction. Fee transactions have an
            empty array.
        merchant:
          type: object
          properties:
            id:
              type: string
              description: The merchant ID
            reference_merchant_id:
              type: string
              description: Your reference merchant ID
        customer_currency_code:
          type: string
        filing_currency_code:
          type: string
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/TransactionLineItem'
        testmode:
          type: boolean
        transaction_processed_at:
          type: number
    TransactionLineItem:
      type: object
      properties:
        line_item_id:
          type: string
          description: Numeral-generated ID for this line item.
          example: li_17833696955814e3b8c1c-7ca2-42d0-9f71-1fb8e7c19cd7
        product:
          type: object
          description: Product information for this line item.
          properties:
            reference_product_name:
              type: string
              description: The name of the product.
              example: Red Shoes
            reference_line_item_id:
              type: string
              description: The ID of the line item from your system.
              example: line_123456789
            reference_product_id:
              type: string
              description: The product ID in your system.
              example: p-1233543
            product_tax_code:
              type: string
              description: The tax code applied to this product.
              example: GENERAL_MERCHANDISE
        tax_jurisdictions:
          type: array
          description: Array of tax jurisdictions that apply to this line item.
          items:
            type: object
            properties:
              tax_rate:
                type: number
                description: >-
                  The tax rate for this jurisdiction, rounded to 6 decimal
                  places. This is the statutory rate for the jurisdiction and
                  may apply to only part of the line item amount (for example,
                  Tennessee single article rules). Do not sum rates across
                  jurisdictions to derive an effective rate; use `tax_amount /
                  amount_excluding_tax` instead.
                example: 0.07
              tax_due_decimal:
                type: number
                description: >-
                  The unrounded tax due for this jurisdiction, in the currency's
                  smallest unit. May be fractional (it is not rounded to an
                  integer). `0` for flat-fee jurisdictions — see `fee_amount`
                  instead.
                example: 724.9275
              fee_amount:
                type: number
                description: Any fixed fee amount for this jurisdiction.
                example: 0
              rate_type:
                type: string
                description: Descriptive rate classification for this jurisdiction.
                example: GENERAL STATE SALES TAX
              tax_authority_name:
                type: string
                description: Name of the tax authority.
                example: Tennessee
              tax_authority_type:
                type: string
                description: Type of tax authority (e.g., STATE, COUNTY, CITY, DISTRICT).
                example: ''
              tax_type:
                type: string
                description: 'Type of tax: SALES, USE, VAT, or GST.'
                example: SALES
        quantity:
          type: number
          description: The quantity of this product.
          example: 2
        tax_amount:
          type: number
          description: The tax amount for this line item.
          example: 14
        amount_excluding_tax:
          type: number
          description: The line item amount excluding tax.
          example: 200
        amount_including_tax:
          type: number
          description: The line item amount including tax.
          example: 214
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````