Customers

Customers

Store customer information and manage tax exemptions for B2B transactions.

Create Customer

POST /v1/customers

curl -X POST https://api.shipvat.com/v1/customers \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "cust_12345",
    "email": "billing@acme.com",
    "name": "Acme Corporation",
    "address": {
      "country": "DE",
      "city": "Berlin",
      "postal_code": "10115",
      "line1": "Friedrichstraße 123"
    },
    "vat_id": "DE123456789",
    "metadata": {
      "stripe_customer_id": "cus_xyz"
    }
  }'

Response

{
  "id": "cust_abc123",
  "external_id": "cust_12345",
  "email": "billing@acme.com",
  "name": "Acme Corporation",
  "address": {
    "country": "DE",
    "region": null,
    "city": "Berlin",
    "postal_code": "10115",
    "line1": "Friedrichstraße 123",
    "line2": null
  },
  "vat_id": "DE123456789",
  "vat_id_validated": true,
  "vat_id_validated_at": "2024-01-15T10:30:00Z",
  "vat_id_company_name": "Acme Corporation GmbH",
  "metadata": {
    "stripe_customer_id": "cus_xyz"
  },
  "exemptions": [],
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

List Customers

GET /v1/customers

Query Parameters

Parameter	Type	Description
limit	number	Results per page (default: 50)
offset	number	Pagination offset
email	string	Filter by email

curl "https://api.shipvat.com/v1/customers?email=billing@acme.com" \
  -H "Authorization: Bearer sk_live_..."

Get Customer

GET /v1/customers/:id

curl https://api.shipvat.com/v1/customers/cust_abc123 \
  -H "Authorization: Bearer sk_live_..."

Get Customer by External ID

Retrieve a customer using your external reference ID (e.g., your CRM customer ID).

GET /v1/customers/external/:externalId

curl https://api.shipvat.com/v1/customers/external/cust_12345 \
  -H "Authorization: Bearer sk_live_..."

Update Customer

PUT /v1/customers/:id

curl -X PUT https://api.shipvat.com/v1/customers/cust_abc123 \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp International",
    "vat_id": "DE987654321"
  }'

Delete Customer

DELETE /v1/customers/:id

---

Tax Exemptions

Manage tax exemptions for customers (resale certificates, nonprofit status, etc.).

Add Exemption

POST /v1/customers/:id/exemptions

curl -X POST https://api.shipvat.com/v1/customers/cust_abc123/exemptions \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "jurisdiction_id": "US-CA",
    "exemption_type": "resale",
    "certificate_number": "SR-12345678",
    "valid_from": "2024-01-01",
    "valid_to": "2025-12-31"
  }'

Response

{
  "id": "exm_xyz789",
  "jurisdiction_id": "US-CA",
  "exemption_type": "resale",
  "certificate_number": "SR-12345678",
  "certificate_url": null,
  "valid_from": "2024-01-01",
  "valid_to": "2025-12-31",
  "status": "pending",
  "verification_notes": null,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Update Exemption

PUT /v1/customers/:id/exemptions/:exemptionId

curl -X PUT https://api.shipvat.com/v1/customers/cust_abc123/exemptions/exm_xyz789 \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "status": "verified",
    "verification_notes": "Certificate verified via state portal"
  }'

Delete Exemption

DELETE /v1/customers/:id/exemptions/:exemptionId

Check Exemption

Check if a customer has a valid exemption for a jurisdiction.

GET /v1/customers/:id/exemptions/check

Query Parameters

Parameter	Type	Description
jurisdiction_id	string	Jurisdiction to check
date	string	Date to check (default: today)

curl "https://api.shipvat.com/v1/customers/cust_abc123/exemptions/check?jurisdiction_id=US-CA" \
  -H "Authorization: Bearer sk_live_..."

Response

{
  "customer_id": "cust_abc123",
  "jurisdiction_id": "US-CA",
  "is_exempt": true,
  "exemption": {
    "id": "exm_xyz789",
    "exemption_type": "resale",
    "status": "verified",
    "valid_from": "2024-01-01",
    "valid_to": "2025-12-31"
  },
  "checked_at": "2024-01-15T10:30:00Z"
}

Exemption Types

Type	Description
resale	Resale certificate (B2B)
nonprofit	501(c)(3) or equivalent
government	Government entity
other	Other exemption type

Exemption Status

Status	Description
pending	Awaiting verification
verified	Certificate verified
rejected	Certificate invalid
expired	Certificate expired