Taxes

Configure tax rates for invoices and quotes

Overview

Taxes define the tax rates applied to invoices and quotes. You can create multiple tax configurations for different jurisdictions and set a default tax rate. Taxes can sync with QuickBooks for proper accounting.

List Taxes

Retrieve all tax configurations for the organization.

query InfiniteTaxes($first: Int!, $after: String, $filter: TaxFilter) {
  infiniteTaxes(first: $first, after: $after, filter: $filter) {
    edges {
      node {
        id
        name
        rate
        isDefault
        isActive
      }
      cursor
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

# Variables
{
  "first": 20,
  "filter": {
    "isActive": true
  }
}

Response:

{
  "data": {
    "infiniteTaxes": {
      "edges": [
        {
          "node": {
            "id": "tax_001",
            "name": "Texas Sales Tax",
            "rate": 0.0825,
            "isDefault": true,
            "isActive": true
          },
          "cursor": "eyJpZCI6InRheF8wMDEifQ=="
        },
        {
          "node": {
            "id": "tax_002",
            "name": "Austin City Tax",
            "rate": 0.02,
            "isDefault": false,
            "isActive": true
          },
          "cursor": "eyJpZCI6InRheF8wMDIifQ=="
        }
      ],
      "pageInfo": {
        "hasNextPage": false,
        "endCursor": "eyJpZCI6InRheF8wMDIifQ=="
      }
    }
  }
}

Get Single Tax

Retrieve a single tax configuration.

query Tax($selector: TaxSelector!) {
  tax(selector: $selector) {
    id
    name
    rate
    description
    isDefault
    isActive
    quickbooksId
    createdAt
    updatedAt
  }
}

# Variables
{
  "selector": {
    "id": "tax_001"
  }
}

Response:

{
  "data": {
    "tax": {
      "id": "tax_001",
      "name": "Texas Sales Tax",
      "rate": 0.0825,
      "description": "Standard Texas state sales tax",
      "isDefault": true,
      "isActive": true,
      "quickbooksId": "QB-TAX-001",
      "createdAt": "2023-01-15T10:00:00Z",
      "updatedAt": "2024-01-10T14:00:00Z"
    }
  }
}

Create Tax

Create a new tax configuration.

mutation CreateTax($input: CreateTaxInput!) {
  createTax(input: $input) {
    id
    name
    rate
    isDefault
    isActive
    createdAt
  }
}

# Variables
{
  "input": {
    "name": "County Tax",
    "rate": 0.01,
    "description": "Travis County tax",
    "isDefault": false
  }
}

Response:

{
  "data": {
    "createTax": {
      "id": "tax_003",
      "name": "County Tax",
      "rate": 0.01,
      "isDefault": false,
      "isActive": true,
      "createdAt": "2024-01-20T09:00:00Z"
    }
  }
}

Update Tax

Update an existing tax configuration.

mutation UpdateTax($id: ID!, $input: UpdateTaxInput!) {
  updateTax(id: $id, input: $input) {
    id
    name
    rate
    isDefault
    updatedAt
  }
}

# Variables
{
  "id": "tax_001",
  "input": {
    "rate": 0.0850,
    "description": "Updated Texas state sales tax"
  }
}

Response:

{
  "data": {
    "updateTax": {
      "id": "tax_001",
      "name": "Texas Sales Tax",
      "rate": 0.0850,
      "isDefault": true,
      "updatedAt": "2024-01-20T10:00:00Z"
    }
  }
}

Delete Tax

Deactivate a tax configuration.

mutation DeleteTax($id: ID!) {
  deleteTax(id: $id) {
    success
    message
  }
}

# Variables
{
  "id": "tax_003"
}

Response:

{
  "data": {
    "deleteTax": {
      "success": true,
      "message": "Tax deactivated successfully"
    }
  }
}

Applying Taxes

Taxes are applied to invoices and quotes by specifying the tax ID:

mutation CreateInvoiceWithTax($input: CreateInvoiceInput!) {
  createInvoice(input: $input) {
    id
    subtotal
    tax
    total
  }
}

# Variables
{
  "input": {
    "customerId": "cust_456",
    "taxId": "tax_001",
    "lineItems": [
      {
        "description": "Pool Cleaning",
        "quantity": 1,
        "unitPrice": 100.00
      }
    ]
  }
}

# The tax will be calculated automatically:
# subtotal: 100.00
# tax: 8.25 (100.00 * 0.0825)
# total: 108.25

Response:

{
  "data": {
    "createInvoice": {
      "id": "inv_003",
      "subtotal": 100.00,
      "tax": 8.25,
      "total": 108.25
    }
  }
}

Field Reference

Field	Type	Description
`id`	`ID!`	Unique identifier
`name`	`String!`	Tax name (e.g., 'Sales Tax')
`rate`	`Float!`	Tax rate as decimal (e.g., 0.0825 for 8.25%)
`description`	`String`(nullable)	Tax description
`isDefault`	`Boolean!`	Whether this is the default tax
`isActive`	`Boolean!`	Whether tax is active
`quickbooksId`	`String`(nullable)	QuickBooks tax code ID
`createdAt`	`DateTime!`	Creation timestamp
`updatedAt`	`DateTime!`	Last update timestamp