Tax rates API

Calculate tax for a basket delivered to a destination. Rates are advisory — the final tax is locked at order creation.

Base URL: https://developer.allthe.com/api/v1 Required scope: tax:read Status: request shape stable; live calculation coming soon (501 not_implemented today).

Not implemented yet. Every call returns 501 not_implemented. The request and response shapes below are settled and will not change, but nothing is wired behind them. To get real tax figures today, call POST /orders/estimate — it prices a full basket, charges nothing, and returns the same numbers the order would be charged.

Endpoint

POST /tax/rates
Content-Type: application/json

Request body

{
  "destination": {
    "country":  "US",
    "postcode": "10001",
    "state":    "NY"
  },
  "lines": [
    { "variant_id": "ckv1...", "qty": 2, "unit_price": 14.99 }
  ],
  "currency": "USD"
}

| Field | Type | Notes | | --------------------- | ------ | -------------------------------------------------- | | destination.country | string | ISO 3166-1 alpha-2. | | destination.postcode| string | Required. | | destination.state | string | Required where applicable (US, CA, AU, IN…). | | lines[].variant_id | string | Base product variant id. | | lines[].qty | int | 1–10 000. | | lines[].unit_price | number | Sale price per unit, in currency. | | currency | string | ISO 4217 currency code (required). |

Response (planned shape)

{
  "currency": "USD",
  "subtotal": 29.98,
  "tax_total": 2.66,
  "lines": [
    {
      "variant_id": "ckv1...",
      "tax_rate": 0.08875,
      "tax_amount": 2.66,
      "jurisdictions": [
        { "name": "New York State", "rate": 0.04,    "amount": 1.20 },
        { "name": "NYC",            "rate": 0.04875, "amount": 1.46 }
      ]
    }
  ]
}

Errors

422 validation_failed — field missing or malformed.
501 not_implemented — live calculation is not yet wired up.