Skip to main content

​
Simple tax calculation

Let’s take a simple item, let’s say a $150 gadget, sold to a customer in California. The seller wants to calculate the tax to be collected for the transaction. They can do this by sending a POST request to the /calculations endpoint with the following payload: 
{
    "line_items": [
        {
            "unit_price": "150",
            "quantity": "1",
            "id": "li_123",
            "customer": {
                "address": {
                    "line1": "747 Howard St",
                    "city": "San Francisco",
                    "country": "US",
                    "postal_code": "94103"
                }
            }
        }
    ],
    "transaction_date": "2024-07-01T00:00:00.000Z"
}
This would return the following response: 
{
    "currency": "USD",
    "tax_amount": "1293.750000",
    "items": [
        {
            "detail": "BAY AREA RAPID TRANSIT DISTRICT",
            "line_item_id": "li_123",
            "rule_name": null,
            "jurisdiction_name": "SAN FRANCISCO COUNTY",
            "jurisdiction_type": "county",
            "tax_amount": "0.75000",
            "tax_type": "CALIFORNIA DISTRICT USE TAX"
        },
        {
            "detail": "SAN FRANCISCO COUNTY TRANSPORTATION AUTHORITY",
            "line_item_id": "li_123",
            "rule_name": null,
            "jurisdiction_name": "SAN FRANCISCO COUNTY",
            "jurisdiction_type": "county",
            "tax_amount": "0.75000",
            "tax_type": "CALIFORNIA DISTRICT USE TAX"
        },
        {
            "detail": "SAN FRANCISCO COUNTY PUBLIC FINANCE AUTHORITY",
            "line_item_id": "li_123",
            "rule_name": null,
            "jurisdiction_name": "SAN FRANCISCO COUNTY",
            "jurisdiction_type": "county",
            "tax_amount": "0.375000",
            "tax_type": "CALIFORNIA DISTRICT USE TAX"
        },
        {
            "detail": "2020 PENINSULA CORRIDOR JOINT POWERS BOARD RETAIL",
            "line_item_id": "li_123",
            "rule_name": null,
            "jurisdiction_name": "SAN FRANCISCO COUNTY",
            "jurisdiction_type": "county",
            "tax_amount": "0.1875000",
            "tax_type": "CALIFORNIA DISTRICT USE TAX"
        },
        {
            "detail": "BRADLEY BURNS CITY & COUNTY OPERATIONS",
            "line_item_id": "li_123",
            "rule_name": null,
            "jurisdiction_name": "SAN FRANCISCO COUNTY",
            "jurisdiction_type": "county",
            "tax_amount": "1.5000",
            "tax_type": "CALIFORNIA RETAILER USE TAX"
        },
        {
            "detail": "COUNTY TRANSPORTATION FUND",
            "line_item_id": "li_123",
            "rule_name": null,
            "jurisdiction_name": "CALIFORNIA",
            "jurisdiction_type": "state",
            "tax_amount": "0.375000",
            "tax_type": "CALIFORNIA RETAILER USE TAX"
        },
        {
            "detail": "GENERAL FUND",
            "line_item_id": "li_123",
            "rule_name": null,
            "jurisdiction_name": "CALIFORNIA",
            "jurisdiction_type": "state",
            "tax_amount": "5.53125000",
            "tax_type": "CALIFORNIA RETAILER USE TAX"
        },
        {
            "detail": "GENERAL FUND",
            "line_item_id": "li_123",
            "rule_name": null,
            "jurisdiction_name": "CALIFORNIA",
            "jurisdiction_type": "state",
            "tax_amount": "0.375000",
            "tax_type": "CALIFORNIA RETAILER USE TAX"
        },
        {
            "detail": "LOCAL PUBLIC SAFETY FUND",
            "line_item_id": "li_123",
            "rule_name": null,
            "jurisdiction_name": "CALIFORNIA",
            "jurisdiction_type": "state",
            "tax_amount": "0.75000",
            "tax_type": "CALIFORNIA RETAILER USE TAX"
        },
        {
            "detail": "LOCAL REVENUE FUND",
            "line_item_id": "li_123",
            "rule_name": null,
            "jurisdiction_name": "CALIFORNIA",
            "jurisdiction_type": "state",
            "tax_amount": "0.75000",
            "tax_type": "CALIFORNIA RETAILER USE TAX"
        },
        {
            "detail": "LOCAL REVENUE FUND",
            "line_item_id": "li_123",
            "rule_name": null,
            "jurisdiction_name": "CALIFORNIA",
            "jurisdiction_type": "state",
            "tax_amount": "1.59375000",
            "tax_type": "CALIFORNIA RETAILER USE TAX"
        }
    ]
}
Note that the tax_due field is a string with a generous number of decimals to avoid precision issues.
This response contains the full breakdown of the tax calculations for the transaction with all relevant jurisdictions and tax types. There is also a total_tax_due field that contains the sum of all the taxes due for the transaction. The seller can then decide what to display to their customer and ensure they collect the correct amount ($12.94 in this case). After the seller’s customer pays, the seller can record the transaction with the /transactions endpoint. 
{
    "line_items": [
        {
            "unit_price": "15000",
            "quantity": "1",
            "id": "li_123",
            "customer": {
                "address": {
                    "line1": "747 Howard St",
                    "city": "San Francisco",
                    "country": "US",
                    "postal_code": "94103"
                }
            }
        }
    ],
    "transaction_date": "2024-07-01T02:00:00.000Z",
    "tax_amount": "1294",
    "reference_id": "tx_123"
}
When the seller gets a 200 response back, they can be confident that the transaction has been recorded correctly and they can use the transaction_reference to reconcile the transaction in their own systems.

​
Tax calculation with multiple jurisdictions

A more complex transaction might be a sale where a product is sent to a customer in California, while another product is sent to a customer in New York. This is a common scenario for B2B sales. For example, purchasing software for various locations of a franchise. 
{
    "line_items": [
        {
            "unit_price": "15000",
            "quantity": "1",
            "id": "li_123",
            "product": {
                "tax_attributes": [
                    "PRODUCT.DIGITAL_GOODS.SOFTWARE._DOWNLOADED"
                ]
            },
            "customer": {
                "address": {
                    "line1": "747 Howard St",
                    "city": "San Francisco",
                    "country": "US",
                    "postal_code": "94103"
                }
            }
        },
        {
            "unit_price": "1000",
            "quantity": "1",
            "id": "li_124",
            "product": {
                "tax_attributes": [
                    "PRODUCT.DIGITAL_GOODS.SOFTWARE._DOWNLOADED"
                ]
            },
            "customer": {
                "address": {
                    "line1": "261 11th Ave",
                    "city": "New York",
                    "country": "US",
                    "state": "NY",
                    "postal_code": "10001"
                }
            }
        }
    ],
    "transaction_date": "2024-07-01T00:00:00.000Z"
}
The response will contain the tax calculations for each jurisdiction and tax type. The total will be the sum of all the taxes due for the transaction, across all jurisdictions, including the tax due for the state of New York and California.

​
Discounts

Discounts can either be passed at the transaction-level (“10% off your entire cart”): 
{
    "discount_total": "15000",
    "line_items": [
        {
            "unit_price": "150000",
            "quantity": "1",
            "customer": {
                "address": {
                    "line1": "747 Howard St",
                    "city": "San Francisco",
                    "country": "US",
                    "postal_code": "94103"
                }
            }
        }
    ]
}
or passed at the line-item level (“10% off this item”): 
{
    "line_items": [
        {
            "unit_price": "150000",
            "quantity": "1",
            "discount_amount": "15000",
            "customer": {
                "address": {
                    "line1": "747 Howard St",
                    "city": "San Francisco",
                    "country": "US",
                    "postal_code": "94103"
                }
            }
        }
    ]
}

​
Bundled products

Some sellers bundle products together in a single package. This is common for physical products, but can also happen for digital products. In this example we sell a computer and a software product loaded on a DVD shipped with the computer. Using the product.tax_attributes field, we can specify that one of the line items is a bundle of both a tangible personal property (computer) and the other is a digital good (software loaded on a DVD). 
{
    "line_items": [
        {
            "unit_price": "150000",
            "quantity": "1",
            "id": "li_123",
            "customer":{
                "address": {
                    "line1": "747 Howard St",
                    "city": "San Francisco",
                    "country": "US",
                    "postal_code": "94103"
                }
            },
            "product": {
                // Multiple tax attributes creates a bundle
                // And the sale is treated as one or the other based on local rules
                "tax_attributes": [
                    "PRODUCT.TANGIBLE_PERSONAL_PROPERTY",
                    "PRODUCT.DIGITAL_GOODS.SOFTWARE._LOAD_AND_LEAVE"
                ]
            }
       }
    ],
    "transaction_date": "2024-07-01T00:00:00.000Z"
}

​
Marketplace tax calculation

Marketplaces are listing products for sale on behalf of third party sellers. This means that the seller location might vary within a single transaction. For example, a marketplace might sell a product to a customer in California with a seller location in California, while another product is sold with a seller in New York. 
{
    "line_items": [
        {
            "unit_price": "19999",
            "product": {
                "tax_attributes": [
                    "TANGIBLE_PERSONAL_PROPERTY.HUMAN_CLOTHING_AND_APPAREL"
                ]
            },
            "customer": {
                "address": { "state": "CA", "postal_code": "90210" }
            },
            "seller": {
                "address": { "state": "CA", "postal_code": "94104" }
            }
        },
        {
            "unit_price": "4999",
            "product": {
                "tax_attributes": [
                    "TANGIBLE_PERSONAL_PROPERTY.HOUSEHOLD_APPLIANCES"
                ]
            },
            // Same customer
            "customer": {
                "address": { "state": "CA", "postal_code": "90210" }
            },
            // Different seller
            "seller": {
                "address": { "state": "NY", "postal_code": "10011" }
            }
        }
    ]
}

​
Separate fulfillment address

Sellers may ship products from various locations. In this example, the seller is located in NY, but selling a good fulfilled from CA into another location in CA. So the California tax law activates their “roaming origin” rule, and it treats the sale as having happened at the fulfillment location, so the taxes should be calculated at that location. The logic is that the transfer of property happened at the moment that the fulfillment center transferred the property via (usually) a 3rd party logistic carrier to the customer, since at that point the good is no longer in the hands of the seller. If the fulfillment location were not provided, instead the tax would be calculated at the location of the customer which is less correct to the letter of the law. This primarily affects e-commerce sellers, and will create a more predictable tax liability, since the tax for CA intrastate sales would no longer change based on customer location. 
{
  "line_items": [
    {
        "unit_price": "19999",
        "quantity": "1",
        "product": {
            "tax_attributes": ["TANGIBLE_PERSONAL_PROPERTY"]
        },
        "customer": {
            "address": { "state": "CA", "postal_code": "90210" }
        },
        "seller": {
            "address": { "state": "NY", "postal_code": "10011" }
        },
        "fulfillment": {
            "address": { "state": "CA", "postal_code": "90210" }
        }
    }
  ]
}

​
Product location

Some scenarios require the location of the product to be specified. For example, for lodging services where the product is the lodging itself. This scenario shows a sale of 4 nights in a hotel in Hawaii. 
{
    "line_items": [
        {
            "unit_price": "19999",
            "quantity": "4",
            "product": {
                "tax_attributes": [
                    "GENERAL_SERVICES.LODGING_SERVICES"
                ],
                // Address here represents the location of the lodging in Hawaii
                "address": { "state": "HI", "postal_code": "96821" }
            },
            "customer": {
                // Customer is located in CA at the time of sale
                "address": { "state": "CA", "postal_code": "90210" }
            }
        }
    ]
}

​
Fractional quantities

In some cases sellers may need fractional quantities for their line items. This is common for fuel products for example. 
{
    "line_items": [
        {
            "unit_price": "310.5",
            // Fractional quantities for units of fuel
            "quantity": "15.35",
            "product": {
                "tax_attributes": ["TANGIBLE_PERSONAL_PROPERTY.FUEL_PRODUCTS"]
            }
        }
    ]
}