> ## 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-01-01)

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

<Note>
  Remember to include the `X-API-Version: 2026-01-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-01-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-01-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:
        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.
                example: 0.07
              tax_due_decimal:
                type: number
                description: >-
                  Tax amount due for this jurisdiction in the currency's
                  smallest unit.
                example: 70000
              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

````