SalesOS

Tax Rates

Tax rate configuration

List tax rates

GET
/v1/tax-rates

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

curl -X GET "https://api.salesos.org/v1/tax-rates" \
  -H "Authorization: Bearer <token>"

Create a tax rate

POST
/v1/tax-rates

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Request Body

application/jsonRequired
nameRequiredstring
descriptionstring
taxTypeRequiredstring
Value in: "CUSTOM" | "SALES" | "VAT" | "GST" | "HST" | "PST"
rateRequirednumber
Minimum: 0
countryRequiredstring
regionstring
citystring
postalCodestring
isDefaultboolean
isCompoundboolean
isActiveboolean
effectiveFromstring
effectiveTostring

Header Parameters

Idempotency-Keystring

Unique key (a UUID is ideal) that makes this write safe to retry for 24 hours: a retry with the same body replays the original response (Idempotent-Replayed: true); the same key with a different body is a 409.

Maximum length: 255
curl -X POST "https://api.salesos.org/v1/tax-rates" \
  -H "Idempotency-Key: <string>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "description": "string",
    "taxType": "CUSTOM",
    "rate": 0,
    "country": "string",
    "region": "string",
    "city": "string",
    "postalCode": "string",
    "isDefault": true,
    "isCompound": true,
    "isActive": true,
    "effectiveFrom": "string",
    "effectiveTo": "string"
  }'

Get tax rate statistics

GET
/v1/tax-rates/stats

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

curl -X GET "https://api.salesos.org/v1/tax-rates/stats" \
  -H "Authorization: Bearer <token>"

Get the default tax rate for a location

GET
/v1/tax-rates/default

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Query Parameters

countryRequiredstring
regionRequiredstring
curl -X GET "https://api.salesos.org/v1/tax-rates/default?country=%3Cstring%3E&region=%3Cstring%3E" \
  -H "Authorization: Bearer <token>"

{}

List tax rates for a country

GET
/v1/tax-rates/country/{country}

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Path Parameters

countryRequiredstring
curl -X GET "https://api.salesos.org/v1/tax-rates/country/<string>" \
  -H "Authorization: Bearer <token>"

Get a tax rate

GET
/v1/tax-rates/{id}

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Path Parameters

idRequiredstring
curl -X GET "https://api.salesos.org/v1/tax-rates/<string>" \
  -H "Authorization: Bearer <token>"

Update a tax rate

PATCH
/v1/tax-rates/{id}

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Request Body

application/jsonRequired
namestring
descriptionstring
taxTypestring
Value in: "CUSTOM" | "SALES" | "VAT" | "GST" | "HST" | "PST"
ratenumber
Minimum: 0
countrystring
regionstring
citystring
postalCodestring
isDefaultboolean
isCompoundboolean
isActiveboolean
effectiveFromstring
effectiveTostring

Path Parameters

idRequiredstring

Header Parameters

Idempotency-Keystring

Unique key (a UUID is ideal) that makes this write safe to retry for 24 hours: a retry with the same body replays the original response (Idempotent-Replayed: true); the same key with a different body is a 409.

Maximum length: 255
curl -X PATCH "https://api.salesos.org/v1/tax-rates/<string>" \
  -H "Idempotency-Key: <string>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "description": "string",
    "taxType": "CUSTOM",
    "rate": 0,
    "country": "string",
    "region": "string",
    "city": "string",
    "postalCode": "string",
    "isDefault": true,
    "isCompound": true,
    "isActive": true,
    "effectiveFrom": "string",
    "effectiveTo": "string"
  }'

Delete a tax rate

DELETE
/v1/tax-rates/{id}

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Path Parameters

idRequiredstring
curl -X DELETE "https://api.salesos.org/v1/tax-rates/<string>" \
  -H "Authorization: Bearer <token>"

Set a tax rate as default for its location

POST
/v1/tax-rates/{id}/set-default

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Path Parameters

idRequiredstring

Header Parameters

Idempotency-Keystring

Unique key (a UUID is ideal) that makes this write safe to retry for 24 hours: a retry with the same body replays the original response (Idempotent-Replayed: true); the same key with a different body is a 409.

Maximum length: 255
curl -X POST "https://api.salesos.org/v1/tax-rates/<string>/set-default" \
  -H "Idempotency-Key: <string>" \
  -H "Authorization: Bearer <token>"

Toggle a tax rate active/inactive

POST
/v1/tax-rates/{id}/toggle-active

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Path Parameters

idRequiredstring

Header Parameters

Idempotency-Keystring

Unique key (a UUID is ideal) that makes this write safe to retry for 24 hours: a retry with the same body replays the original response (Idempotent-Replayed: true); the same key with a different body is a 409.

Maximum length: 255
curl -X POST "https://api.salesos.org/v1/tax-rates/<string>/toggle-active" \
  -H "Idempotency-Key: <string>" \
  -H "Authorization: Bearer <token>"

Calculate tax for a location and subtotal

POST
/v1/tax-rates/calculate

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Request Body

application/jsonRequired
countryRequiredstring
regionstring
citystring
postalCodestring
subtotalRequirednumber
Minimum: 0

Header Parameters

Idempotency-Keystring

Unique key (a UUID is ideal) that makes this write safe to retry for 24 hours: a retry with the same body replays the original response (Idempotent-Replayed: true); the same key with a different body is a 409.

Maximum length: 255
curl -X POST "https://api.salesos.org/v1/tax-rates/calculate" \
  -H "Idempotency-Key: <string>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "string",
    "region": "string",
    "city": "string",
    "postalCode": "string",
    "subtotal": 0
  }'

Bulk import tax rates (upsert by name+location)

POST
/v1/tax-rates/bulk-import

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Request Body

application/jsonRequired
ratesRequiredarray<object>

Header Parameters

Idempotency-Keystring

Unique key (a UUID is ideal) that makes this write safe to retry for 24 hours: a retry with the same body replays the original response (Idempotent-Replayed: true); the same key with a different body is a 409.

Maximum length: 255
curl -X POST "https://api.salesos.org/v1/tax-rates/bulk-import" \
  -H "Idempotency-Key: <string>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "rates": [
      {
        "name": "string",
        "description": "string",
        "taxType": "CUSTOM",
        "rate": 0,
        "country": "string",
        "region": "string",
        "city": "string",
        "postalCode": "string",
        "isDefault": true,
        "isCompound": true,
        "isActive": true,
        "effectiveFrom": "string",
        "effectiveTo": "string"
      }
    ]
  }'

Discount Rules

Discount approval rules and thresholds

Approval Workflows

Multi-step approval processes