Extension Tax Flows

This document provides a detailed explanation of the tax calculation flow, including the purpose of the flow, the service involved, and the description of each field in the request and response.

Example configuration (Dynamic Settings):

Key	Type	Default	Description
TAX_CLIENT_CONF	Object	See below	Connection settings for the external tax microservice.

{
  "TAX_CLIENT_CONF": {
    "enabled": true,
    "base_url": "https://tax-service.example.com/",
    "auth": {
      "username": "xxx",
      "password": "xxx"
    }
  }
}

Purpose of the Flow

The Tax Calculation Flow is designed to integrate with an external tax microservice to calculate destination-based sales tax for each basket item during checkout. This flow is triggered whenever the customer selects or changes their shipping address or shipping option. This flow is particularly useful for:

• Destination-Based Tax: Calculating sales tax based on the shipping address jurisdiction (e.g. US state tax).

• Per-Item Tax Breakdown: Providing granular tax amounts and rates per basket item for accurate order pricing and reporting.

• Non-Blocking Integration: Tax calculation errors never block checkout — if the microservice is unavailable or returns an unexpected response, checkout proceeds without tax.

This part of the document contains the service that can be integrated in the flow above. 2 configuration parameters will be shared during integration:

Field	Description
username	Username for basic authentication
password	Password for basic authentication

tax-calculate (POST)

This service is used to calculate tax amounts for each basket item. It is called during checkout after offer/discount calculation, when the shipping address or basket contents change.

URL:

^^/tax-calculate

Request Headers

Header	Description	Requirement
x-akinon-request-id	Unique ID for problem solving & tracing.	Mandatory
Content-Type	application/json	Mandatory
Authorization	Basic [BASE64_encoded(username:password)]	Mandatory

Request Body Structure

Field	Type	Description
basket	Object	Container for basket information
basket.basketItems	Array	List of items in the basket
basket.basketItems[].id	Number	Unique identifier for the basket item
basket.basketItems[].quantity	Number	Quantity of the item
basket.basketItems[].unitPrice	String	Unit price before discount (decimal value as string)
basket.basketItems[].unitDiscountedPrice	String	Unit price after discount (decimal value as string)
basket.basketItems[].currencyType	String	Currency code (ISO 4217)
basket.basketItems[].taxRate	String	VAT/KDV rate of the product (0–100 scale, decimal value as string)
basket.basketItems[].product	Object	Product information
basket.basketItems[].product.sku	String	SKU of the product
basket.basketItems[].product.name	String	Name of the product
basket.basketItems[].product.attributes	Object	Additional attributes of the product
address	Object	Shipping address used to determine the tax jurisdiction
address.country	String	Country code (ISO 3166-1 alpha-2)
address.city	String/Null	City name
address.township	String/Null	Township name
address.district	String/Null	District name
address.postcode	String/Null	Postal code
address.line	String	Address line
address.taxOffice	String/Null	Tax office (for corporate invoices)
address.taxNo	String/Null	Tax number (for corporate invoices)
shippingOption	Object/Null	Selected shipping option
shippingOption.slug	String	Unique slug of the shipping option
shippingOption.name	String	Display name of the shipping option

Request Body Example

{
  "basket": {
    "basketItems": [
      {
        "id": 1,
        "quantity": 2,
        "unitPrice": "49.99",
        "unitDiscountedPrice": "44.99",
        "currencyType": "USD",
        "taxRate": "0.00",
        "product": {
          "sku": "SKU-001",
          "name": "Classic T-Shirt",
          "attributes": {
            "color": "black",
            "size": "M"
          }
        }
      },
      {
        "id": 2,
        "quantity": 1,
        "unitPrice": "89.99",
        "unitDiscountedPrice": "89.99",
        "currencyType": "USD",
        "taxRate": "0.00",
        "product": {
          "sku": "SKU-002",
          "name": "Denim Jacket",
          "attributes": {
            "color": "blue",
            "size": "L"
          }
        }
      }
    ]
  },
  "address": {
    "country": "US",
    "city": "New York",
    "township": null,
    "district": null,
    "postcode": "10001",
    "line": "123 Main St",
    "taxOffice": null,
    "taxNo": null
  },
  "shippingOption": {
    "slug": "standard-shipping",
    "name": "Standard Shipping"
  }
}

Request Body (typescript interface)

interface TaxCalculateRequest {
  basket: TaxBasket;
  address: TaxAddress;
  shippingOption: TaxShippingOption | null;
}

interface TaxBasket {
  basketItems: TaxBasketItem[];
}

interface TaxBasketItem {
  id: number;
  quantity: number;
  unitPrice: string;
  unitDiscountedPrice: string;
  currencyType: string;
  taxRate: string;
  product: TaxProduct;
}

interface TaxProduct {
  sku: string;
  name: string;
  attributes: Record<string, any>;
}

interface TaxAddress {
  country: string;
  city: string | null;
  township: string | null;
  district: string | null;
  postcode: string | null;
  line: string;
  taxOffice: string | null;
  taxNo: string | null;
}

interface TaxShippingOption {
  slug: string;
  name: string;
}

Response Body Structure

Field	Type	Description
[]	Array	List of tax calculations, one entry per basket item
[].basketItemId	Number	ID of the basket item this tax applies to
[].total	String	Total tax amount for this line (quantity already factored in, decimal value as string)
[].breakdown	Array	List of individual tax entries (e.g. state tax, county tax)
[].breakdown[].label	String	Human-readable label for this tax entry (e.g. "CA State Tax")
[].breakdown[].rate	String	Tax rate for this tax entry (0–1 scale, decimal value as string)
[].breakdown[].amount	String	Tax amount for this tax entry (decimal value as string)

Response Body Example

[
  {
    "basketItemId": 1,
    "total": "4.43",
    "breakdown": [
      {"label": "CA State Tax", "rate": "0.0725", "amount": "3.62"},
      {"label": "SF County Tax", "rate": "0.0100", "amount": "0.50"},
      {"label": "District Tax",  "rate": "0.0025", "amount": "0.31"}
    ]
  },
  {
    "basketItemId": 2,
    "total": "7.99",
    "breakdown": [
      {"label": "CA State Tax", "rate": "0.0725", "amount": "6.52"},
      {"label": "SF County Tax", "rate": "0.0100", "amount": "0.90"},
      {"label": "District Tax",  "rate": "0.0025", "amount": "0.57"}
    ]
  }
]

Response Body (typescript interface)

type TaxCalculateResponse = TaxCalculateItem[];

interface TaxCalculateItem {
  basketItemId: number;
  total: string;
  breakdown: TaxBreakdownItem[];
}

interface TaxBreakdownItem {
  label: string;
  rate: string;
  amount: string;
}

Response Body For Errors (ALL)

If any errors are encountered, these errors should be reported in the format below, and the list of error codes should be shared with Akinon. Commerce will log the error and continue checkout without applying tax.

• Response Body (raw 4xx/5xx json)

{
  "errors": [
    {
      "code": "",
      "field": "",
      "message": ""
    }
  ]
}

• Response Body (raw 4xx/5xx typescript interface)

interface ErrorResponse {
  errors: ErrorItem[];
}

interface ErrorItem {
  code: string;
  field: string;
  message: string;
}

Changelog

Version 1.0.0

Added

• Initial implementation of the Tax Calculation Flow

• tax-calculate endpoint for per-item sales tax calculation

• HTTP Basic Auth support

• x-akinon-request-id header on all requests

• Dirty-check mechanism to avoid redundant microservice calls