Skip to main content

​
About

​
Geographic coverage

100+ countries; all US states.

​
Setup

​
Prerequisites

  1. An active Stripe connection: Stripe Tax requires an existing Stripe integration for payments or invoicing.
  2. Stripe Tax activated in your Stripe Dashboard.

​
Connecting your account

  1. Navigate to Settings > Taxes in the Orb dashboard.
  2. Select “Connect to Stripe Tax” (uses your existing Stripe connection).
  3. Configure your default tax code for items without specific mappings.
  4. Click Save. For Orb test mode, ensure Stripe Tax is activated in your Stripe test environment; for live mode, activate it in production.

​
Setting up tax codes

Orb supports tax code configuration per Item, used to map invoice line items to Stripe’s tax codes. Configure under Settings > Items > Item name > edit, filling the External item ID with the Stripe tax code (e.g. txcd_10000000 for general services). If no code is specified, Orb uses the default configured during setup (typically txcd_10000000).

​
Sample request and response payload

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

​
Request (Orb → Stripe Tax)

{
  "currency": "USD",
  "line_items": [
    {
      "amount": 10000,
      "quantity": 1,
      "reference": "<invoice_line_item_id>",
      "tax_code": "txcd_10000000"
    }
  ],
  "customer_details": {
    "address": {
      "line1": "<line1>",
      "line2": "<line2>",
      "city": "<city>",
      "state": "<state>",
      "postal_code": "<postal_code>",
      "country": "<country>"
    },
    "address_source": "billing",
    "tax_ids": []
  },
  "expand": [
    "line_items.data.tax_breakdown"
  ]
}

​
Response (Stripe Tax → Orb)

{
  "id": "calc_123456",
  "amount_total": 11000,
  "currency": "usd",
  "tax_amount_exclusive": 1000,
  "line_items": [
    {
      "reference": "<invoice_line_item_id>",
      "amount_tax": 1000,
      "amount": 10000,
      "tax_rate": 0.1
    }
  ],
  "tax_breakdown": [
    {
      "tax_rate_details": {
        "display_name": "Local Sales and Use Tax"
      }
    }
  ]
}

​
Reporting tax for filing

Once the invoice is issued or finalized, Orb creates a tax transaction from the prior calculation via stripe.tax.Transaction.create_from_calculation(...). Orb stores the returned transaction ID for future reversals (e.g. credit notes).

​
Request (Orb → Stripe Tax, reporting)

{
  "calculation": "calc_123456",
  "reference": "orb_invoice_inv_123"
}

​
Response (Stripe Tax → Orb, reporting)

{
  "id": "tax_transaction_123"
}