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

# Numeral

# About

## **Geographic coverage**

US (all states) + 70-80+ countries for VAT/GST (Pro plan)

# Setup

## **Prerequisites**

1. A Numeral account with tax engine access.
2. A Numeral API key (test or production).
3. Your business configured in Numeral with the appropriate tax settings.

## **Connecting your account**

1. Create a Numeral account at [<u>dashboard.numeralhq.com/users/sign-up</u>](http://dashboard.numeralhq.com/users/sign-up) and check the box indicating interest in the tax engine.
2. In Numeral, go to **Developers > API keys > Create** a test API key, and save it.
3. In Orb, navigate to **Settings > Taxes** and select “Connect to Numeral.”
4. Enter your Numeral API key and click Save. Use a Numeral test mode key for Orb test mode, and a production key for Orb live mode.

## **Setting up tax codes**

The integration supports Numeral's product categorization system for tax classification. For each Item in Orb, select the appropriate Numeral product category. If none is specified, Orb defaults to GENERAL\_MERCHANDISE. Common categories. The [<u>complete list of categories is available in Numeral's docs</u>](https://docs.numeral.com/essentials/product-categories).

# **Sample request and response payload**

<Info>
  *The example below is illustrative of the shape Orb sends to and receives from Numeral today, based on Orb's tax provider processors and test fixtures. Exact field names and structure can change as Numeral versions its API — confirm against current behavior before relying on it for integration work.*
</Info>

### ***Request (Orb → Numeral)***

```text theme={null}
{
  "customer": {
    "address": {
      "address_line_1": "123 Test St",
      "address_city": "San Francisco",
      "address_province": "CA",
      "address_postal_code": "94105",
      "address_country": "US",
      "address_type": "billing"
    }
  },
  "order_details": {
    "customer_currency_code": "USD",
    "tax_included_in_amount": false,
    "line_items": [
      {
        "amount": 10000,
        "quantity": 1,
        "reference_line_item_id": "line-item-456",
        "reference_product_id": "product-123",
        "product_category": "SAAS_GENERAL"
      }
    ],
    "automatic_tax": "auto"
  },
  "origin_address": {
    "address_country": "US"
  },
  "metadata": {
    "orb_invoice_id": "<invoice_id>"
  }
}
```

### ***Response (Numeral → Orb)***

```text theme={null}
{
  "id": "calc-123",
  "testmode": true,
  "tax_included_in_amount": false,
  "total_tax_amount": 875,
  "total_amount_excluding_tax": 10000,
  "customer_currency_code": "USD",
  "line_items": [
    {
      "tax_amount": 875,
      "line_item_id": "line-item-456",
      "amount_excluding_tax": 10000,
      "amount_including_tax": 10875,
      "product": {
        "reference_line_item_id": "line-item-456"
      },
      "tax_jurisdictions": [
        {
          "jurisdiction_name": "California",
          "tax_rate": 0.0875
        }
      ]
    }
  ]
}
```

## **Reporting tax for filing**

After calculating tax, Orb separately reports the transaction to Numeral once the invoice is issued or finalized, via POST `/tax/transactions`. Orb stores the returned Numeral transaction ID for future reference.

### ***Request (Orb → Numeral, reporting)***

```text theme={null}
{
  "calculation_id": "calc-123",
  "reference_order_id": "<invoice_id>",
  "transaction_processed_at": 1661990400,
  "metadata": {
    "orb_invoice_id": "<invoice_id>",
    "orb_invoice_number": "<invoice_number>"
  }
}
```

### ***Response (Numeral → Orb, reporting)***

```text theme={null}
{
  "id": "tr_123456789",
  "object": "tax.transaction",
  "calculation_id": "calc-123",
  "reference_order_id": "<invoice_id>",
  "transaction_processed_at": 1661990400,
  "customer_currency_code": "USD",
  "filing_currency_code": "USD",
  "line_items": []
}
```