Decision API

Decision API

Determine if you must collect tax based on your sales data.

Endpoint

POST /v1/decision/collect

Request Body

{
  "destination": {
    "country": "US",
    "region": "CA"
  },
  "seller_sales": {
    "amount_minor": 60000000,
    "transactions": 150,
    "currency": "USD",
    "period": "previous_calendar_year"
  }
}

Example

curl -X POST "https://api.shipvat.com/v1/decision/collect" \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": {"country": "US", "region": "CA"},
    "seller_sales": {
      "amount_minor": 60000000,
      "transactions": 150,
      "currency": "USD",
      "period": "previous_calendar_year"
    }
  }'

Response

{
  "must_collect": true,
  "explanation": "Sales of USD 600,000.00 meet or exceed threshold of USD 500,000.00.",
  "threshold_applied": {
    "type": "REMOTE_SELLER_NEXUS",
    "amount_minor": 50000000,
    "currency": "USD",
    "condition": "AMOUNT_ONLY"
  },
  "confidence": "HIGH",
  "queried_at": "2024-01-15T10:30:00Z"
}

amount_minor is a non-negative safe integer in the minor unit of the adjacent ISO currency (60000000 means USD 600,000.00). ShipVAT does not compare unlike currencies; convert explicitly before calling this endpoint.

Decision Logic

The API evaluates:

1. AMOUNT_ONLY: Sales amount vs threshold
2. TX_ONLY: Transaction count vs threshold
3. OR: Either condition triggers nexus
4. AND: Both conditions required for nexus