Tax API reference

The checkout module provides REST and GraphQL APIs to configure out-of-process tax integrations.

REST

The REST API schema is available here.

Route URL	Method	Description
`/V1/oope_tax_management/tax_integration/:code`	GET	Retrieve an OOPE tax integration info by its code.
`/V1/oope_tax_management/tax_integration`	GET	List all available tax integration info.
`/V1/oope_tax_management/tax_integration`	POST	Create or update an OOPE tax integration.

Create or modify a new OOPE tax integration

The POST /V1/oope_tax_management/tax_integration/:code endpoint creates an out-of-process tax integration in the Adobe Commerce instance.

Only one tax integration can be active at a time. If you want to change the active tax integration, you must first deactivate the current one.

Payload parameters:

Parameter	Type	Required	Description
`code`	String	Yes	Unique identifier for the tax integration.
`title`	String	Yes	Display name of the tax integration.
`active`	Boolean	No	Status indicating if the tax integration is active.
`stores`	Array	No	List of store codes where the tax integration is available.

Example request

Example response

curl --request POST \
--url <ADOBE_COMMERCE_API_URL>/V1/oope_tax_management/tax_integration \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
"tax_integration": {
    "code": "tax-1",
    "title": "Tax Integration 1",
    "active": true,
    "stores": ["store-1", "store-2"]
}
}'
Copied to your clipboard
curl --request POST \
--url <ADOBE_COMMERCE_API_URL>/V1/oope_tax_management/tax_integration \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
"tax_integration": {
    "code": "tax-1",
    "title": "Tax Integration 1",
    "active": true,
    "stores": ["store-1", "store-2"]
}
}'

{
  "success": true,
  "message": {
    "id": 1,
    "code": "tax-1",
    "title": "Tax Integration 1",
    "active": true,
    "stores": ["store-1", "store-2"]
  }
}
Copied to your clipboard
{
  "success": true,
  "message": {
    "id": 1,
    "code": "tax-1",
    "title": "Tax Integration 1",
    "active": true,
    "stores": ["store-1", "store-2"]
  }
}

Get an OOPE tax integration by code

The GET /V1/oope_tax_management/tax_integration/:code retrieves one out-of-process tax integration by code from the Adobe Commerce instance.

Payload parameters:

Parameter	Type	Description
`code`	String	Unique identifier for the tax integration.

Example request

Example response

curl --request GET \
--url <ADOBE_COMMERCE_API_URL>/V1/oope_tax_management/tax_integration/:code' \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/json'
Copied to your clipboard
curl --request GET \
--url <ADOBE_COMMERCE_API_URL>/V1/oope_tax_management/tax_integration/:code' \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/json'

{
  "success": true,
  "message": {
    "id": 1,
    "code": "tax-1",
    "title": "Tax Integration 1",
    "active": true,
    "stores": ["store-1", "store-2"]
  }
}
Copied to your clipboard
{
  "success": true,
  "message": {
    "id": 1,
    "code": "tax-1",
    "title": "Tax Integration 1",
    "active": true,
    "stores": ["store-1", "store-2"]
  }
}

List all OOPE tax integrations

The GET /V1/oope_tax_management/tax_integration retrieves a list of all out-of-process tax integrations from the Adobe Commerce instance.

Example request

Example response

curl --request GET \
--url <ADOBE_COMMERCE_API_URL>/V1/oope_tax_management/tax_integration' \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/json'
Copied to your clipboard
curl --request GET \
--url <ADOBE_COMMERCE_API_URL>/V1/oope_tax_management/tax_integration' \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/json'

{
  "success": true,
  "message": [
    {
      "id": 1,
      "code": "tax-1",
      "title": "Tax Integration 1",
      "active": true,
      "stores": ["store-1", "store-2"]
    }
  ]
}
Copied to your clipboard
{
  "success": true,
  "message": [
    {
      "id": 1,
      "code": "tax-1",
      "title": "Tax Integration 1",
      "active": true,
      "stores": ["store-1", "store-2"]
    }
  ]
}

Create a tax class with custom attributes

The out-of-process tax module extends the POST /V1/taxClasses endpoint to allow creating tax classes with custom attributes.

Example request

Example response

curl --request POST \
--url <ADOBE_COMMERCE_API_URL>/V1/taxClasses \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
  "class_name": "Test Tax Class",
  "class_type": "PRODUCT",
  "custom_attributes": [
    {
      "attribute_code": "tax_code",
      "value": "005"
    }
  ]
}'
Copied to your clipboard
curl --request POST \
--url <ADOBE_COMMERCE_API_URL>/V1/taxClasses \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
  "class_name": "Test Tax Class",
  "class_type": "PRODUCT",
  "custom_attributes": [
    {
      "attribute_code": "tax_code",
      "value": "005"
    }
  ]
}'

"3"
Copied to your clipboard
"3"

Update a tax class with custom attributes

The out-of-process tax module extends the PUT /V1/taxClasses/:classId endpoint to update an existing tax class with custom attributes.

Example request

Example response

curl --request POST \
--url <ADOBE_COMMERCE_API_URL>/V1/taxClasses/4 \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
  "class_id": 4,
  "class_name": "Updated Tax Class",
  "class_type": "PRODUCT",
  "custom_attributes": [
    {
      "attribute_code": "tax_code",
      "value": "005"
    }
  ]
}'
Copied to your clipboard
curl --request POST \
--url <ADOBE_COMMERCE_API_URL>/V1/taxClasses/4 \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
  "class_id": 4,
  "class_name": "Updated Tax Class",
  "class_type": "PRODUCT",
  "custom_attributes": [
    {
      "attribute_code": "tax_code",
      "value": "005"
    }
  ]
}'

"4"
Copied to your clipboard
"4"

List all tax classes with custom attributes

The out-of-process tax module extends the GET /V1/taxClasses/search endpoint to include custom attributes in the response when available.

Example request

Example response

curl --request GET \
--url '<ADOBE_COMMERCE_API_URL>/V1/taxClasses/search?searchCriteria[pageSize]=100' \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/json'
Copied to your clipboard
curl --request GET \
--url '<ADOBE_COMMERCE_API_URL>/V1/taxClasses/search?searchCriteria[pageSize]=100' \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/json'

{
  "items": [
    {
      "class_id": 1,
      "class_name": "Retail Tax Class",
      "class_type": "CUSTOMER",
      "extension_attributes": {},
      "custom_attributes": [
        {
          "attribute_code": "tax_code",
          "value": "005"
        },
        {
          "attribute_code": "tax_label",
          "value": "Retail"
        }
      ]
    }
  ],
  "search_criteria": {
    "filter_groups": [],
    "sort_orders": [],
    "page_size": 100,
    "current_page": 1
  },
  "total_count": 1
}
Copied to your clipboard
{
  "items": [
    {
      "class_id": 1,
      "class_name": "Retail Tax Class",
      "class_type": "CUSTOMER",
      "extension_attributes": {},
      "custom_attributes": [
        {
          "attribute_code": "tax_code",
          "value": "005"
        },
        {
          "attribute_code": "tax_label",
          "value": "Retail"
        }
      ]
    }
  ],
  "search_criteria": {
    "filter_groups": [],
    "sort_orders": [],
    "page_size": 100,
    "current_page": 1
  },
  "total_count": 1
}

GraphQL

There are two GraphQL queries to check taxes applied by the tax integration, cart.

Cart taxes

To check the taxes applied to the cart, you can use the getCart query to retrieve the cart/prices/applied_taxes field. This field contains information about the taxes applied to the cart.

To enable full tax breakdown, which displays each tax separately instead of combining them, set Stores > Settings > Configuration > Sales > Tax > Shopping Cart Display Settings > Display Full Tax Summary to Yes

Tax API Javascript usage

Overview