Tax Categories API¶

These endpoints will allow you to easily manage tax categories. Base URI is /api/v1/tax-categories.

Tax Category structure¶

Tax Category API response structure¶

If you request a tax category via API, you will receive an object with the following fields:

Field	Description
id	Id of the tax category
code	Unique tax category identifier
name	Name of the tax category

If you request for more detailed data, you will receive an object with the following fields:

Field	Description
id	Id of the tax category
code	Unique tax category identifier
name	Name of the tax category
description	Description of the tax category
createdAt	Date of creation
updatedAt	Date of last update

Note

Creating a Tax Category¶

To create a new tax category you will need to call the /api/v1/tax-categories/ endpoint with the POST method.

Definition¶

POST /api/v1/tax-categories/

Parameter	Parameter type	Description
Authorization	header	Token received during authentication
code	request	(unique) Tax category identifier
name	request	Name of the tax category

Example¶

To create a new tax category use the below method:

$ curl http://demo.sylius.com/api/v1/tax-categories/ \
    -H "Authorization: Bearer SampleToken" \
    -H "Content-Type: application/json" \
    -X POST \
    --data '
        {
            "code": "food",
            "name": "Food"
        }
'

Exemplary Response¶

STATUS: 201 CREATED

{
    "id": 4,
    "code": "food",
    "name": "Food",
    "createdAt": "2017-02-21T12:49:48+0100",
    "updatedAt": "2017-02-21T12:49:50+0100",
    "_links": {
        "self": {
            "href": "\/api\/v1\/tax-categories\/food"
        }
    }
}

Warning

If you try to create a tax category without name or code you will receive a 400 Bad Request error, that will contain validation errors.

Example¶

$ curl http://demo.sylius.com/api/v1/tax-categories/ \
    -H "Authorization: Bearer SampleToken" \
    -H "Content-Type: application/json" \
    -X POST

Exemplary Response¶

STATUS: 400 Bad Request

{
    "code": 400,
    "message": "Validation Failed",
    "errors": {
        "children": {
            "name": {
                "errors": [
                    "Please enter tax category name."
                ]
            },
            "description": {},
            "code": {
                "errors": [
                    "Please enter tax category code."
                ]
            }
        }
    }
}

You can also create a tax category with additional (not required) fields:

Parameter	Parameter type	Description
description	request	Description of the tax category

Example¶

$ curl http://demo.sylius.com/api/v1/tax-categories/ \
    -H "Authorization: Bearer SampleToken" \
    -H "Content-Type: application/json" \
    -X POST \
    --data '
        {
            "code": "food",
            "name": "Food",
            "description": "The food category."
        }
     '

Exemplary Response¶

STATUS: 201 CREATED

{
    "id": 5,
    "code": "food",
    "name": "Food",
    "description": "The food category.",
    "createdAt": "2017-02-21T12:58:41+0100",
    "updatedAt": "2017-02-21T12:58:42+0100",
    "_links": {
        "self": {
            "href": "\/api\/v1\/tax-categories\/food"
        }
    }
}

Getting a Single Tax Category¶

To retrieve the details of a tax category you will need to call the /api/v1/tax-categories/{code} endpoint with the GET method.

Definition¶

GET /api/v1/tax-categories/{code}

Parameter	Parameter type	Description
Authorization	header	Token received during authentication
code	url attribute	Unique tax category identifier

Example¶

$ curl http://demo.sylius.com/api/v1/tax-categories/food \
    -H "Authorization: Bearer SampleToken" \
    -H "Accept: application/json"

Note

The food is an exemplary value. Your value can be different. Check in the list of all tax categories if you are not sure which code should be used.

Exemplary Response¶

STATUS: 200 OK

{
    "id": 5,
    "code": "food",
    "name": "Food",
    "description": "The food category.",
    "createdAt": "2017-02-21T12:58:41+0100",
    "updatedAt": "2017-02-21T12:58:42+0100",
    "_links": {
        "self": {
            "href": "\/api\/v1\/tax-categories\/food"
        }
    }
}

Collection of Tax Categories¶

To retrieve a paginated list of tax categories you will need to call the /api/v1/tax-categories/ endpoint with the GET method.

Definition¶

GET /api/v1/tax-categories/

Parameter	Parameter type	Description
Authorization	header	Token received during authentication
limit	query	(optional) Number of items to display per page, by default = 10
sorting[‘nameOfField’][‘direction’]	query	(optional) Field and direction of sorting, by default ‘desc’ and ‘createdAt’

To see the first page of all tax categories use the below method:

Example¶

$ curl http://demo.sylius.com/api/v1/tax-categories/ \
    -H "Authorization: Bearer SampleToken" \
    -H "Accept: application/json"

Exemplary Response¶

STATUS: 200 OK

{
    "page": 1,
    "limit": 10,
    "pages": 1,
    "total": 4,
    "_links": {
        "self": {
            "href": "\/api\/v1\/tax-categories\/?page=1&limit=10"
        },
        "first": {
            "href": "\/api\/v1\/tax-categories\/?page=1&limit=10"
        },
        "last": {
            "href": "\/api\/v1\/tax-categories\/?page=1&limit=10"
        }
    },
    "_embedded": {
        "items": [
            {
                "id": 1,
                "code": "clothing",
                "name": "Clothing",
                "_links": {
                    "self": {
                        "href": "\/api\/v1\/tax-categories\/clothing"
                    }
                }
            },
            {
                "id": 2,
                "code": "books",
                "name": "Books",
                "_links": {
                    "self": {
                        "href": "\/api\/v1\/tax-categories\/books"
                    }
                }
            },
            {
                "id": 3,
                "code": "other",
                "name": "Other",
                "_links": {
                    "self": {
                        "href": "\/api\/v1\/tax-categories\/other"
                    }
                }
            },
            {
                "id": 5,
                "code": "food",
                "name": "Food",
                "_links": {
                    "self": {
                        "href": "\/api\/v1\/tax-categories\/food"
                    }
                }
            }
        ]
    }
}

Updating a Tax Category¶

To fully update a tax category you will need to call the /api/v1/tax-categories/{code} endpoint with the PUT method.

Definition¶

PUT /api/v1/tax-categories/{code}

Parameter	Parameter type	Description
Authorization	header	Token received during authentication
code	url attribute	Unique tax category identifier
name	request	Name of the tax category
description	request	Description of the tax category

Example¶

To fully update the tax category with code = food use the below method:

$ curl http://demo.sylius.com/api/v1/tax-categories/food \
    -H "Authorization: Bearer SampleToken" \
    -H "Content-Type: application/json" \
    -X PUT \
    --data '
        {
            "name": "Vegetables",
            "description": "The category of food: vegetables"
        }
    '

Exemplary Response¶

STATUS: 204 No Content

If you try to perform a full tax category update without all the required fields specified, you will receive a 400 Bad Request error.

Example¶

$ curl http://demo.sylius.com/api/v1/tax-categories/food \
    -H "Authorization: Bearer SampleToken" \
    -H "Content-Type: application/json" \
    -X PUT

Exemplary Response¶

STATUS: 400 Bad Request

{
    "code": 400,
    "message": "Validation Failed",
    "errors": {
        "children": {
            "name": {
                "errors": [
                    "Please enter tax category name."
                ]
            },
            "description": {},
            "code": {}
        }
    }
}

To update a tax category partially you will need to call the /api/v1/tax-categories/{code} endpoint with the PATCH method.

Definition¶

PATCH /api/v1/tax-categories/{code}

Parameter	Parameter type	Description
Authorization	header	Token received during authentication
code	url attribute	Unique tax category identifier

Example¶

To partially update the tax category with code = food use the below method:

$ curl http://demo.sylius.com/api/v1/tax-categories/food \
    -H "Authorization: Bearer SampleToken" \
    -H "Content-Type: application/json" \
    -X PATCH \
    --data '
        {
            "description": "The category of food: vegetables"
        }
    '

Exemplary Response¶

STATUS: 204 No Content

Deleting a Tax Category¶

To delete a tax category you will need to call the /api/v1/tax-categories/{code} endpoint with the DELETE method.

Definition¶

DELETE /api/v1/tax-categories/{code}

Parameter	Parameter type	Description
Authorization	header	Token received during authentication
code	url attribute	Unique tax category identifier

Example¶

$ curl http://demo.sylius.com/api/v1/tax-categories/food \
    -H "Authorization: Bearer SampleToken" \
    -H "Accept: application/json" \
    -X DELETE

Exemplary Response¶

STATUS: 204 No Content