Skip to main content

​
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 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 complete list of categories is available in Numeral’s docs.

​
Sample request and response payload

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.

​
Request (Orb → Numeral)

{
  "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)

{
  "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)

{
  "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)

{
  "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": []
}