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

# Changelog

> What's new in API version 2026-01-01

# API Changelog

## Version 2026-01-01

> [!NOTE]
>
> **Release Date:** January 1, 2026
>
> This version introduces Merchant Management and Platform Calculations for marketplace and payment processor scenarios.

### New Endpoints

> **Merchant CRUD**
>
> Full create, read, update, and delete operations for merchants (sellers) on your platform.
>
> * `POST /tax/merchants` - Create merchant
> * `GET /tax/merchants` - List merchants
> * `GET /tax/merchants/:id` - Get merchant
> * `POST /tax/merchants/:id` - Update merchant
> * `DELETE /tax/merchants/:id` - Delete merchant

> **Platform Calculations**
>
> Tax calculations for marketplace transactions with merchant context.
>
> * `POST /tax/platform/calculations`

> **Platform Transactions**
>
> Convert platform calculations into recorded transactions for tax reporting.
>
> * `POST /tax/platform/transactions`

***

### Breaking Changes

> [!WARNING]
>
> **Amount is Per-Unit in Platform Calculations**
>
> The most significant change in this version is how `amount` is interpreted in the `/platform/calculations` endpoint.
>
> | Endpoint | Amount Behavior |
> | - | - |
> | `/tax/calculations` | Total line item value |
> | `/tax/platform/calculations` | **Per-unit price** |
>
> **Example:**
>
> ```json theme={null}
> // For 3 items at $25.00 each
>
> // Standard calculations (amount = total)
> {
>   "amount": 7500,  // $75.00 total
>   "quantity": 3
> }
>
> // Platform calculations (amount = per-unit)
> {
>   "amount": 2500,  // $25.00 per unit
>   "quantity": 3    // taxable base = $75.00
> }
> ```

***

### New Features

#### Merchant Management

Create and manage merchants (sellers) on your platform:

```bash theme={null}
curl -X POST https://api.numeralhq.com/tax/merchants \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "X-API-Version: 2026-01-01" \
  -H "Content-Type: application/json" \
  -d '{
    "reference_merchant_id": "seller-123",
    "name": "Acme Seller",
    "default_address": {
      "address_line_1": "123 Main St",
      "address_city": "San Francisco",
      "address_province": "CA",
      "address_postal_code": "94105",
      "address_country": "US"
    }
  }'
```

Key features:

* Use your own IDs via `reference_merchant_id`
* Store merchant tax IDs for B2B transactions
* Default addresses used as origin in calculations
* Testmode isolation (test merchants separate from live)

#### Platform Calculations

Calculate taxes for marketplace/platform transactions:

```bash theme={null}
curl -X POST https://api.numeralhq.com/tax/platform/calculations \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "X-API-Version: 2026-01-01" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "address": { ... }
    },
    "merchant": {
      "merchant_id": "seller-123"
    },
    "order_details": {
      "customer_currency_code": "USD",
      "tax_included_in_amount": false,
      "line_items": [
        { "amount": 2500, "quantity": 3, "product_category": "GENERAL_MERCHANDISE" }
      ]
    },
    "roles": ["marketplace_provider"]
  }'
```

Key features:

* **Per-unit pricing** - `amount × quantity = taxable base`
* **Merchant context** - Link calculations to specific sellers
* **Platform roles** - Specify your role (marketplace, payment processor, merchant of record)
* **Fee calculations** - Separate tax calculation for platform fees
* **Enhanced response** - Includes `tax_authority_name`, `tax_authority_type`, `tax_type`

#### Platform Roles

Specify your role in the transaction:

| Role | Description |
| - | - |
| `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 |

#### Platform Transactions

Convert platform calculations into recorded transactions for tax reporting and filing:

```bash theme={null}
curl -X POST https://api.numeralhq.com/tax/platform/transactions \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "X-API-Version: 2026-01-01" \
  -H "Content-Type: application/json" \
  -d '{
    "platform_calculation_id": "plat_calc_abc123",
    "reference_order_id": "order_12345",
    "reference_payment_id": "pay_67890",
    "transaction_processed_at": 1736300000
  }'
```

Key features:

* **Returns a list** - May return one or two transactions depending on your platform role
* **Payment processors** - Receive separate `order` and `fee` transactions
* **Marketplace providers / Merchants of record** - Receive a single `order` transaction
* **Transaction types** - `type: "order"` for sales, `type: "fee"` for platform fees

| Platform Role | Transactions Created |
| - | - |
| `payment_processor` | 2 (order + fee) |
| `marketplace_provider` | 1 (order only) |
| `merchant_of_record` | 1 (order only) |

#### Fee Calculations

Calculate taxes on platform fees separately from order items:

```json theme={null}
{
  "order_details": { ... },
  "fee_details": {
    "line_items": [
      { "amount": 299, "quantity": 1, "product_category": "ELECTRONIC_GOODS" }
    ]
  }
}
```

The response includes separate totals:

```json theme={null}
{
  "totals": {
    "order": { "tax_amount": 875 },
    "fees": { "tax_amount": 26 }
  }
}
```

***

### Enhanced Tax Response

Platform calculations include additional jurisdiction details:

```json theme={null}
{
  "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"
    }
  ]
}
```

| Field | Description |
| - | - |
| `tax_authority_name` | Human-readable authority name |
| `tax_authority_type` | `STATE`, `COUNTY`, `CITY`, or `DISTRICT` |
| `tax_type` | `SALES`, `USE`, `VAT`, or `GST` |

***

### New Error Format

> [!WARNING]
>
> **Breaking Change: Simplified Error Response**
>
> Error responses now use a flattened structure instead of the nested `error` object from previous versions.

**Previous format (2025-05-12 and earlier):**

```json theme={null}
{
  "error": {
    "code": "product_not_found",
    "message": "Product not found"
  }
}
```

**New format (2026-01-01):**

```json theme={null}
{
  "code": 400,
  "type": "PRODUCT_NOT_FOUND",
  "message": "Product not found"
}
```

Key changes:

* **Flattened structure** - No more nested `error` object
* **HTTP status in response** - `code` field contains the HTTP status code
* **Uppercase error types** - Error types are now SCREAMING\_SNAKE\_CASE
* **Consistent typing** - Use the `type` field for programmatic error handling

> **[Error Codes Reference](https://docs.numeral.com/api-reference/v2026-01-01/error-codes.md)**
>
> See the complete list of error types and their meanings.

***

### Migration Guide

#### From 2025-05-12 to 2026-01-01

1. **Update error handling** - Error responses use a new flattened format with `code`, `type`, and `message` fields
2. **New endpoints require** `X-API-Version: 2026-01-01` header
3. **Platform calculations** use per-unit amounts (important!)

#### Adopting Platform Calculations

1. Create merchants for your sellers
2. Use `/tax/platform/calculations` instead of `/tax/calculations`
3. Remember: `amount` is per-unit, taxable base = `amount × quantity`
4. Specify your `roles` in each request

***

### Previous Versions

| Version | Key Features |
| - | - |
| 2025-05-12 | Customer types (B2B/B2C), tax IDs, 32 currencies, automatic\_tax |
| 2024-09-01 | Base version with core tax calculation features |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.