Tax Settings API

Accounts can have one or more tax IDs. Tax IDs are displayed on invoices and receipts.

It is not possible to update a tax ID. If you need to update a tax ID, you must delete the existing tax ID and create a new one.

All the endpoints in this section, except for Retrieve Tax ID Types, require the user to have a billing account. If the user does not have a billing account, a no account error will be returned.

The Tax ID Object

Name
id
Type
string
Description
Unique identifier for the tax ID object.
Name
value
Type
string
Description
Value of the tax ID. Maximum length of 50 characters.
Name
type
Type
enum
Description
Type of the tax ID, one of the supported tax ID types.
Note that some legacy tax IDs have type unknown.
Name
country
Type
string
Description
Two-letter country code (ISO 3166-1 alpha-2). This is inferred from the tax ID type.
Name
verification.status
Type
enum
Description
Verification status, one of pending, verified, unverified, or unavailable.
Name
verification.verified_address
Type
string
Description
Verified address.
Name
verification.verified_name
Type
string
Description
Verified name.
Name
created_at
Type
datetime
Description
Time at which the object was created. Returns a datetime string in the format YYYY-MM-DD HH:MM:SS using the timezone claim of the JWT access token. Defaults to UTC.

The Tax ID Object

{
    "id": "txi_1Nq73vCVnXOZCtu9lxat3OvS",
    "value": "4123456789",
    "type": "za_vat",
    "country": "ZA",
    "verification": {
        "status": "unavailable",
        "verified_address": null,
        "verified_name": null
    },
    "created_at": "2023-09-14 04:21:55"
}

GET/v1/account/tax/types

Retrieve Tax ID Types

Requires no scope.

This is a collection of supported tax ID types. This endpoint is useful for UIs that relate to tax IDs.

Parameters

No parameters are required for this endpoint.

Example request

curl -G https://api.mikrocloud.com/v1/account/tax/types \
-H "Authorization: Bearer {token}"

Example response

[
    {
        "type": "za_vat",
        "flag": "🇿🇦",
        "name": "VAT",
        "description": "South African VAT number",
        "country": "South Africa",
        "iso2": "ZA",
        "example": "4123456789"
    }
    //...
]

GET/v1/account/tax

Retrieve Tax IDs

Requires the account:read scope.

Parameters

No parameters are required for this endpoint.

Example request

curl -G https://api.mikrocloud.com/v1/account/tax \
-H "Authorization: Bearer {token}"

Example response

[
    {
        "id": "txi_1Nq73vCVnXOZCtu9lxat3OvS",
        "value": "4123456789",
        "type": "za_vat",
        "country": "ZA",
        "verification": {
            "status": "unavailable",
            "verified_address": null,
            "verified_name": null
        },
        "created_at": "2023-09-14 04:21:55"
    }
]

POST/v1/account/tax

Create a Tax ID

Requires the account:write scope.

Parameters

Name
value
Type
string
Required
Required
Description
Value of the tax ID. Maximum length of 50 characters.
Name
type
Type
enum
Required
Required
Description
Type of the tax ID, one of the supported tax ID types.

Example request

curl -X POST https://api.mikrocloud.com/v1/account/tax \
-H "Authorization: Bearer {token}" \
-d '{
    "value": "4123456789",
    "type": "za_vat"
}'

Example response

{
    "id": "txi_1Nq73vCVnXOZCtu9lxat3OvS",
    "value": "4123456789",
    "type": "za_vat",
    "country": "ZA",
    "verification": {
        "status": "unavailable",
        "verified_address": null,
        "verified_name": null
    },
    "created_at": "2023-09-14 04:21:55"
}

DELETE/v1/account/tax/{id}

Delete a Tax ID

Requires the account:write scope.

Parameters

Name
id
Type
string
Required
Required
Description
Unique identifier for the tax ID object.

Example request

curl -X DELETE https://api.mikrocloud.com/v1/account/tax/{id} \
-H "Authorization: Bearer {token}"