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
Read more about the Tax Category model in the component docs.
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 withcode = 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