POS Taxes

Access tax configuration and rates from your POS system. Tax information ensures accurate pricing calculations and compliance.

Overview

The POS Tax API provides access to tax configurations in your POS system. Taxes can be applied at the item, modifier, or ticket level and may be percentage-based or flat fees.

Tax data is essential for:

• Pricing Calculations - Calculate accurate total prices including taxes
• Compliance - Ensure proper tax collection and reporting
• Display Requirements - Show tax-inclusive or tax-exclusive pricing as required
• Reporting - Generate tax reports for accounting and filing

API Endpoints

Retrieve Taxes

Returns all tax configurations for a specific location.

curl -X GET https://conecto-api.shift4payments.com/pos/v2/12345/taxes \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

{
  "results": [
    {
      "taxRef": "TAX-SALES",
      "name": "Sales Tax",
      "description": "State and local sales tax",
      "rate": 0.0825,
      "isFlat": false,
      "isActive": true,
      "isHidden": false,
      "isInclusive": false,
      "priority": 1,
      "locationId": 12345
    },
    {
      "taxRef": "TAX-SERVICE",
      "name": "Service Charge",
      "description": "Automatic service charge",
      "rate": 0.18,
      "isFlat": false,
      "isActive": true,
      "isHidden": false,
      "isInclusive": false,
      "applyToAlcohol": true,
      "priority": 2,
      "locationId": 12345
    },
    {
      "taxRef": "TAX-BOTTLE",
      "name": "Bottle Deposit",
      "description": "Bottle deposit fee",
      "flatAmount": 0.10,
      "isFlat": true,
      "isActive": true,
      "isHidden": false,
      "priority": 3,
      "locationId": 12345
    }
  ],
  "meta": {
    "page": 1,
    "pageSize": 50,
    "totalCount": 3
  }
}

Models

Tax

Represents a tax or fee configuration in the POS system.

Tax Calculations

Percentage-Based Taxes

For percentage-based taxes (isFlat: false):

Tax Amount = Item Price × Tax Rate

Example:

• Item Price: $10.00
• Sales Tax Rate: 8.25% (0.0825)
• Tax Amount: $10.00 × 0.0825 = $0.83
• Total: $10.83

Flat Taxes

For flat taxes (isFlat: true):

Tax Amount = Flat Amount × Quantity

Example:

• Item Price: $10.00
• Bottle Deposit: $0.10
• Quantity: 2
• Tax Amount: $0.10 × 2 = $0.20
• Total: $20.20 ($10.00 × 2 + $0.20)

Multiple Taxes

When multiple taxes apply, they are processed in priority order:

1. Sort taxes by priority (ascending)
2. For each tax:
   - Calculate tax on current subtotal
   - Add tax to running total
3. Return final total

Tax-Inclusive Pricing

For inclusive taxes (isInclusive: true), the tax is already included in the item price:

Item Price Without Tax = Item Price / (1 + Tax Rate)
Tax Amount = Item Price - Item Price Without Tax

Use Cases

Price Display

Display accurate prices including all applicable taxes:

• Show pre-tax and post-tax amounts separately
• Handle tax-inclusive pricing correctly
• Display hidden taxes only in reports (not to customers)

Order Processing

Calculate correct totals for orders:

• Apply taxes based on item categories
• Respect tax priorities for compound taxation
• Handle flat fees vs. percentage-based taxes

Tax Reporting

Generate tax reports for compliance:

• Break down taxes by type
• Calculate tax collected by period
• Separate visible vs. hidden taxes

Best Practices