Sites & Organisation

Tax Configurations

A tax configuration is one or more 'sets' of taxes that should apply to a the sale of a single item.

get/shop/tax-configurations

Get revenue centres for a site

getTaxConfigurations

Use this endpoint to retrieve tax configurations.

Query parameters

country_codestringoptional
An optional country code to filter tax configurations

Responses

200
A list of tax configurations.
401
The user is unauthenticated
404
The resource couldn't be found

curl "https://api.playground.try.be/shop/tax-configurations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

const response = await fetch('https://api.playground.try.be/shop/tax-configurations', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    Accept: 'application/json',
  },
})

if (!response.ok) {
  throw new Error(`Trybe API ${response.status}: ${await response.text()}`)
}

const data = await response.json()

import httpx

response = httpx.get(
    "https://api.playground.try.be/shop/tax-configurations",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Accept": "application/json",
    },
)
response.raise_for_status()
data = response.json()

<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.playground.try.be/shop/tax-configurations', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_API_KEY',
        'Accept' => 'application/json',
    ],
]);

$data = json_decode($response->getBody(), true);

package main

import (
	"encoding/json"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.playground.try.be/shop/tax-configurations", nil)
	req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
	req.Header.Set("Accept", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	var data map[string]interface{}
	json.NewDecoder(resp.Body).Decode(&data)
}

A list of tax configurations.

{
  "data": [
    {
      "id": "64a9f3b2c3d8e1f4a5b6c7d8",
      "name": "UK VAT",
      "description": "Applies to most items sold in the UK",
      "rate_sets": [
        {
          "id": "00000000-0000-0000-0000-000000000000",
          "valid_from": "2026-01-15T09:30:00+00:00",
          "valid_to": "2026-01-15T09:30:00+00:00",
          "tax_rates": [
            {
              "id": "00000000-0000-0000-0000-000000000000"
            }
          ]
        }
      ]
    }
  ]
}

{
  "message": "Unauthenticated"
}

{
  "message": "The requested resource could not be found"
}

get/shop/tax-configurations/{taxConfigurationId}

Retrieve a tax configuration

getTaxConfiguration

Retrieve a single tax configuration by ID. The response includes the configuration's name, optional description, and the full set of rate sets that apply to it — useful for surfacing the active tax rules in a back-office editor, or for previewing what rates will be applied before testing a calculation against /calculate.

Path parameters

taxConfigurationIdstringrequired
The ID of the tax configuration

Responses

200
A single tax configuration.
401
The user is unauthenticated
404
The resource couldn't be found

curl "https://api.playground.try.be/shop/tax-configurations/abc123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

const response = await fetch('https://api.playground.try.be/shop/tax-configurations/abc123', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    Accept: 'application/json',
  },
})

if (!response.ok) {
  throw new Error(`Trybe API ${response.status}: ${await response.text()}`)
}

const data = await response.json()

import httpx

response = httpx.get(
    "https://api.playground.try.be/shop/tax-configurations/abc123",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Accept": "application/json",
    },
)
response.raise_for_status()
data = response.json()

<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.playground.try.be/shop/tax-configurations/abc123', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_API_KEY',
        'Accept' => 'application/json',
    ],
]);

$data = json_decode($response->getBody(), true);

package main

import (
	"encoding/json"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.playground.try.be/shop/tax-configurations/abc123", nil)
	req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
	req.Header.Set("Accept", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	var data map[string]interface{}
	json.NewDecoder(resp.Body).Decode(&data)
}

A single tax configuration.

{
  "data": {
    "id": "64a9f3b2c3d8e1f4a5b6c7d8",
    "name": "UK VAT",
    "description": "Applies to most items sold in the UK",
    "rate_sets": [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "valid_from": "2026-01-15T09:30:00+00:00",
        "valid_to": "2026-01-15T09:30:00+00:00",
        "tax_rates": [
          {
            "name": "VAT",
            "percentage": 17.5,
            "basis": "net",
            "inclusive": false
          }
        ]
      }
    ]
  }
}

{
  "message": "Unauthenticated"
}

{
  "message": "The requested resource could not be found"
}

post/shop/tax-configurations/{taxConfigurationId}/calculate

Test a tax calculation.

actionTestTaxConfiguration

Use this endpoint to test a tax calculation for the given tax configuration.

Path parameters

taxConfigurationIdstringrequired
The ID of the tax configuration

Request body

amountintegeroptional
Test the tax configuration with the given customer-facing amount.
datedate-timeoptionalnullable
Test the tax configuration as it would be applied on the given date.

Responses

200
The results of a tax calculation for a tax configuration.
401
The user is unauthenticated
403
The authenticated user does not have permission.
404
The resource couldn't be found
422
The request didn't pass validation

curl -X POST "https://api.playground.try.be/shop/tax-configurations/abc123/calculate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": "string",
  "date": "2026-01-15T09:30:00+00:00"
}'

const response = await fetch('https://api.playground.try.be/shop/tax-configurations/abc123/calculate', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
    Accept: 'application/json',
  },
  body: JSON.stringify({
    "amount": "string",
    "date": "2026-01-15T09:30:00+00:00"
  }),
})

if (!response.ok) {
  throw new Error(`Trybe API ${response.status}: ${await response.text()}`)
}

const data = await response.json()

import httpx

response = httpx.post(
    "https://api.playground.try.be/shop/tax-configurations/abc123/calculate",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Accept": "application/json",
        "Content-Type": "application/json",
    },
    json={
        "amount": "string",
        "date": "2026-01-15T09:30:00+00:00"
    },
)
response.raise_for_status()
data = response.json()

<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.playground.try.be/shop/tax-configurations/abc123/calculate', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_API_KEY',
        'Accept' => 'application/json',
        'Content-Type' => 'application/json',
    ],
    'json' => [
            'amount' => 'string',
            'date' => '2026-01-15T09:30:00+00:00'
        ],
]);

$data = json_decode($response->getBody(), true);

package main

import (
	"bytes"
	"encoding/json"
	"net/http"
)

func main() {
	payload, _ := json.Marshal(map[string]interface{}{
		"amount": "string",
		"date": "2026-01-15T09:30:00+00:00",
	})
	req, _ := http.NewRequest("POST", "https://api.playground.try.be/shop/tax-configurations/abc123/calculate", bytes.NewBuffer(payload))
	req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
	req.Header.Set("Accept", "application/json")
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	var data map[string]interface{}
	json.NewDecoder(resp.Body).Decode(&data)
}

The results of a tax calculation for a tax configuration.

{
  "data": {
    "net_amount": 1667,
    "gross_amount": 10000,
    "taxes": [
      {
        "name": "VAT",
        "inclusive": true,
        "basis": "net",
        "percentage": 20,
        "amount": 1667,
        "base_amount": 8333,
        "item_amount": 10000,
        "included_remainder": 1
      }
    ]
  }
}

{
  "message": "Unauthenticated"
}

{
  "message": "This action is unauthorized."
}

{
  "message": "The requested resource could not be found"
}

{
  "errors": {},
  "message": "The request didn't pass validation"
}