Skip to main content

Taxes Integration API (1.0.0)

Download OpenAPI specification:Download

Use this API to create/retrieve tax transactions. This API uses OAuth 2.0 Client Credentials Grant, and your application must obtain an authorized access token before it can execute an endpoint call. For more details, please refer to the NewStore Public API Authorization guide.

Tax transactions

Calculate the total taxes for orders in your business and retrieve tax transactions.

Create a preview tax transaction by calculating the total amounts of cart items without storing the transaction.

Creates a preview tax transaction by calculating the total amounts of cart items using the configured tax strategy without storing the transaction. Intended to be used for testing and validation purposes.

Authorizations:
oauth2
header Parameters
x-request-id
string

Request identifier.

store-id
string

Store identifier.

x-newstore-tenant
string

Tenant identifier.

Request Body schema: application/json
tax_exempt
boolean
Default: false

Defines the tax exemption status of the transaction.

transaction_type
string
Enum: "SALE" "RETURN"

Type of the transaction.

order_id
string

The order ID that will be used as a reference to link the order to the created tax transaction in the tax provider records.

  • In case the order ID is not provided then a randomly generated identifier will be used instead.
  • The tax transaction will be stored by using the given value.
return_id
string

The return ID that will be used as a reference to link the order to the created tax transaction in the tax provider records.

  • The tax transaction for returns will be stored by using the given value.
  • If the value is not set, the return transaction will not be stored.
exemption_number
string

The number of the customer's exemption certificate.

  • The given value can be verified by the auditors in the event of a tax audit.
required
Array of objects

A list of the items sold/returned in the transaction.

exemption_class
string
Enum: "FEDERAL_GOVERNMENT" "STATE_GOVERNMENT" "TRIBAL_GOVERNMENT" "LOCAL_GOVERNMENT" "FOREIGN_DIPLOMAT" "CHARITY_ORGANIZATION" "RELIGIOUS_ORGANIZATION" "EDUCATIONAL_ORGANIZATION" "RESALE" "DIRECT_PAY_PERMIT" "OTHER" "NON_RESIDENT" "FIRST_NATION_CITIZEN" "CUSTOM_*"

The tax exemption class that identifies the customer's group/organization that accredited them with the tax exemption status.

  • For custom tax exemption classes, the CUSTOM_ prefix with a UPPER_SNAKE_CASE key can be used. Example: CUSTOM_CANADA
tax_date
string <date-time>

Date of the transaction (in UTC timezone) that'll be used in committing taxes.

Responses

Request samples

Content type
application/json
Example

Example transaction with tax inclusive items.

{
  • "tax_exempt": false,
  • "transaction_type": "SALE",
  • "order_id": "56bb9975-f43a-4eee-8fb2-200957eb0624",
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "document_id": "123",
  • "totals": {
    },
  • "tax_exempt": false,
  • "transaction_type": "SALE",
  • "order_id": "56bb9975-f43a-4eee-8fb2-200957eb0624",
  • "return_id": "4fbcc8b3-8511-4ad1-8c9f-96b7c08db664",
  • "exemption_number": "string",
  • "fallback_error": {
    },
  • "exemption_class": "CHARITY_ORGANIZATION"
}

Get tax transaction for an order

Get tax transaction for the given order identifier.

Authorizations:
oauth2
path Parameters
orderId
required
string

Order identifier.

header Parameters
x-request-id
string

Request identifier.

store-id
string

Store identifier.

x-newstore-tenant
string

Tenant identifier.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "document_id": "123",
  • "totals": {
    },
  • "tax_exempt": false,
  • "transaction_type": "SALE",
  • "order_id": "56bb9975-f43a-4eee-8fb2-200957eb0624",
  • "return_id": "4fbcc8b3-8511-4ad1-8c9f-96b7c08db664",
  • "exemption_number": "string",
  • "fallback_error": {
    },
  • "exemption_class": "CHARITY_ORGANIZATION"
}

Get tax transaction for a return

Get tax transaction for the given return and order identifiers.

Authorizations:
oauth2
path Parameters
orderId
required
string

Order identifier.

returnId
required
string

Return identifier.

header Parameters
x-request-id
string

Request identifier.

store-id
string

Store identifier.

x-newstore-tenant
string

Tenant identifier.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "document_id": "123",
  • "totals": {
    },
  • "tax_exempt": false,
  • "transaction_type": "SALE",
  • "order_id": "56bb9975-f43a-4eee-8fb2-200957eb0624",
  • "return_id": "4fbcc8b3-8511-4ad1-8c9f-96b7c08db664",
  • "exemption_number": "string",
  • "fallback_error": {
    },
  • "exemption_class": "CHARITY_ORGANIZATION"
}