API Overview

API Overview

The ShipVAT API provides RESTful endpoints for tax calculation, transaction recording, customer management, and compliance reporting.

Base URL

https://api.shipvat.com

Core Endpoints

Endpoint	Method	Description
/health	GET	Health check (no auth required)
/v1/calculate	POST	Calculate tax for transactions
/v1/calculate/batch	POST	Batch calculate multiple transactions
/v1/rates	GET	Get tax rates for a jurisdiction
/v1/thresholds	GET	Get nexus thresholds
/v1/decision/collect	POST	Tax collection decision

Transaction Recording

Endpoint	Method	Description
/v1/transactions	POST	Create a transaction
/v1/transactions	GET	List transactions
/v1/transactions/:id	GET	Get transaction details
/v1/transactions/external/:externalId	GET	Get transaction by external ID
/v1/transactions/:id/refund	POST	Refund a transaction
/v1/transactions/:id/void	POST	Void a pending transaction
/v1/transactions/batch	POST	Create multiple transactions (max 50)

Customer Management

Endpoint	Method	Description
/v1/customers	POST	Create a customer
/v1/customers	GET	List customers
/v1/customers/:id	GET	Get customer details
/v1/customers/external/:externalId	GET	Get customer by external ID
/v1/customers/:id	PUT	Update a customer
/v1/customers/:id	DELETE	Delete a customer
/v1/customers/:id/exemptions	POST	Add tax exemption
/v1/customers/:id/exemptions/:exemptionId	PUT	Update exemption
/v1/customers/:id/exemptions/:exemptionId	DELETE	Remove exemption
/v1/customers/:id/exemptions/check	GET	Check exemption status

VAT Validation

Endpoint	Method	Description
/v1/vat/validate	POST	Validate VAT ID (EU VIES)
/v1/vat/format-check	GET	Check VAT format only
/v1/vat/validate-customer/:customerId	POST	Validate and update customer VAT
/v1/vat/countries	GET	List supported VAT countries

Compliance Reports

Endpoint	Method	Description
/v1/reports/summary	GET	Tax summary by jurisdiction
/v1/reports/transactions	GET	Transaction report for period
/v1/reports/filing	GET	Filing report (EU OSS, etc.)
/v1/reports/export	GET	Export report as CSV

Webhooks

Endpoint	Method	Description
/v1/webhooks	POST	Create webhook endpoint
/v1/webhooks	GET	List webhooks
/v1/webhooks/:id	GET	Get webhook details
/v1/webhooks/:id	PUT	Update webhook
/v1/webhooks/:id	DELETE	Delete webhook
/v1/webhooks/:id/rotate-secret	POST	Rotate webhook secret
/v1/webhooks/events/list	GET	List available event types

Address Validation

Endpoint	Method	Description
/v1/addresses/validate	POST	Validate and normalize address
/v1/addresses/countries	GET	List supported countries
/v1/addresses/regions/:country	GET	Get regions for country

Metadata

Endpoint	Method	Description
/v1/metadata/jurisdictions	GET	List all jurisdictions
/v1/metadata/jurisdictions/:id	GET	Get jurisdiction details
/v1/metadata/sync-status	GET	Data sync status
/v1/export/snapshot	GET	Export full data snapshot

Authentication

All /v1/* endpoints require a Bearer token:

curl https://api.shipvat.com/v1/rates?jurisdiction=DE \
  -H "Authorization: Bearer sk_live_your_api_key"

Response Format

All successful responses are JSON with a queried_at timestamp:

{
  "jurisdiction": "DE",
  "rates": [...],
  "queried_at": "2024-01-15T10:30:00Z"
}

Error Format

{
  "error_code": "VALIDATION_ERROR",
  "message": "Human readable message",
  "details": {
    "field": "jurisdiction",
    "reason": "Invalid jurisdiction code"
  }
}

Error Codes

Code	HTTP Status	Description
UNAUTHORIZED	401	Invalid or missing API key
FORBIDDEN	403	Insufficient permissions
NOT_FOUND	404	Resource not found
VALIDATION_ERROR	400	Invalid request parameters
RATE_LIMIT_EXCEEDED	429	Too many requests
INTERNAL_ERROR	500	Server error

Rate Limits

Tier	Limit
Free	10 requests/minute
Pro	1,000 requests/minute
Enterprise	10,000 requests/minute