• Version: 1.2.0

Taxes

Taxes represent the default sales tax (or VAT in the EU) charged per product. This endpoint creates a Taxes object that you can attach to a product so that the correct price with taxes is returned whenever you return that product. We associate taxes with products and not customers to reflect the variable tax rates on various product categories such as food, liquor, and electronics.

Taxes are flows-based structures with the following data fields by default:

Key Type Required Unique Details
id Integer No Yes Automatically populated when you create the tax.
title String Yes No The display name for this tax.
description String No No You can enter HTML tags to format this description.
tax_rate Float* Yes No The percentage amount of tax added to the final price. This should be a number between 0 and 100.
currencies Array No No The transaction currencies that this tax applies to. If you do not pass currency information, the created tax will use the default that you have set. This field will not currently prevent a tax from being used with any currencies.

*All Float values are limited to two decimal places.

Before using taxes, you’ll need to create them with the https://api.molt.in/v1/taxes endpoint. Once created, taxes can be added to products.

This topic will cover the following processes:

Before you can use this (or any endpoint), you need to authenticate to get a bearer token.

Create a Tax

Every product in your catalogue must have a tax associated with it. You can use a single tax in multiple products. To create a tax, POST the tax data to the https://api.molt.in/v1/taxes endpoint. Taxes must have data for the title and rate fields. You can put data fields in any order. If you do not provide one or more of the required fields, the endpoint will return a message stating which fields are missing.

This functionality may be limited by access token scope. See Types of Tokens for more information.

curl -X POST https://api.molt.in/v1/taxes \
	-H "Authorization: Bearer XXXX" \
	-d "title=Electronics" \
	-d "rate=8.0"

On success, this call returns a 201 Created HTML status code and the tax information for the newly created object, including any default or generated values. The object it returns looks like this by default (the data will be different, of course):

{
	"status":true,
	"result":
	{
		"id":"1038552069344068212",
		"code":null,
		"title":"Electronics",
		"enabled":false,
		"tax_rate":0
	}
}

Retrieve Tax Information

Once you have created the taxes that affect your potential sales, you have two methods to retrieve that information. The first requires that you know the ID number of the tax that you want, and it returns solely the information for that one tax. The second returns an array of taxes that you can limit by field values, specify a maximum number to return, and offset the start of the array. Using the last two options, you can paginate results by increasing the offset of a search by the previous maximum.

Retrieve a Single Tax by ID

You can GET tax information by adding the specific ID number of the desired tax to the taxes endpoint. No additional data fields are required.

This functionality may be limited by access token scope. See Types of Tokens for more information.

curl -X GET https://api.molt.in/v1/taxes/:id \
	-H "Authorization: Bearer XXX"

This returns a 200 OK status code and the tax information for the selected ID number. The result information will look a little different from the information returned when the tax was created:

{
	"id":"1038552069344068212",
	"title":"Electronics",
	"description":null,
	"rate":8,
	"created_at":null,
	"updated_at":null,
	"currencies":
	[
		{
			"id":"1018614836801569432",
			"code":"GBP",
			"title":"British Pound",
			"enabled":true,
			"modifier":"+0",
			"exchange_rate":0,
			"format":"\u00a3{price}",
			"decimal_point":".",
			"thousand_point":",",
			"rounding":null,
			"default":false,
			"created_at":null,
			"updated_at":null,
			"rate":8
		}
	]
}

The difference between the information returned here and when it is created is that it contains an array of Currency objects that have a rate field. Using this rate field, you can customize the tax rate by individual currencies.

Retrieve a List of All Taxes

Using the https://api.molt.in/v1/taxes endpoint, you can return an array that contains all of the taxes that you have created.

This functionality may be limited by access token scope. See Types of Tokens for more information.

curl -X GET https://api.molt.in/v1/taxes \
-H "Authorization: Bearer XXXX"

This returns 200 OK and an array of tax information, as shown in the Retrieve a Single Tax by ID section.

If you want to otherwise limit or affect the list of results, you can use the following options:

Key Type Details
limit Integer The maximum number of taxes to return.
offset Integer The number of taxes to skip from the beginning of the list.

Edit a Tax

To change one or more values in a single tax, use a PUT call with the tax/{tax ID} endpoint. You can change most field values through this method, including changing rates, updating the title, or adding a description.

This functionality may be limited by access token scope. See Types of Tokens for more information.

curl -X PUT https://api.molt.in/v1/taxes/:id \
	-H "Authorization: Bearer XXXX" \
	-d "rate=12"

This returns 200 OK and the updated tax information.

Delete a Single Tax

To remove a tax, you use the same taxes/{ID number} endpoint we used to retrieve a single tax, except we use the DELETE request method.

This functionality may be limited by access token scope. See Types of Tokens for more information.

curl -X DELETE https://api.molt.in/v1/taxes/:id \
	-H "Authorization: Bearer XXXX"

If successful, this call returns 200 OK and the following:

{
	"status":true,
	"message":"Tax removed successfully"
}