POST
/
quickbooks-desktop
/
sales-tax-items
import Conductor from 'conductor-node';

const client = new Conductor({
  apiKey: process.env['CONDUCTOR_SECRET_KEY'], // This is the default and can be omitted
});

async function main() {
  const salesTaxItem = await client.qbd.salesTaxItems.create({
    name: 'Standard Tax',
    conductorEndUserId: 'end_usr_1234567abcdefg',
  });

  console.log(salesTaxItem.id);
}

main();
{
  "id": "80000001-1234567890",
  "objectType": "qbd_sales_tax_item",
  "createdAt": "2021-10-01T17:34:56.000Z",
  "updatedAt": "2021-10-01T20:45:30.000Z",
  "revisionNumber": "1721172183",
  "name": "Standard Tax",
  "barcode": "012345678905",
  "isActive": true,
  "class": {
    "id": "80000001-1234567890",
    "fullName": "State-Sales-Tax"
  },
  "description": "Standard rate sales tax for California",
  "taxRate": "7.5",
  "taxVendor": {
    "id": "80000001-1234567890",
    "fullName": "State Tax Agency"
  },
  "salesTaxReturnLine": {
    "id": "80000001-1234567890",
    "fullName": "Line 1: State Sales Tax"
  },
  "externalId": "12345678-abcd-1234-abcd-1234567890ab",
  "customFields": [
    {
      "ownerId": "0",
      "name": "Customer Rating",
      "type": "string_1024_type",
      "value": "Premium"
    }
  ]
}

Authorizations

​
Authorization
string
header
required

Your Conductor secret key using Bearer auth (e.g., "Authorization: Bearer {{YOUR_SECRET_KEY}}").

Headers

​
Conductor-End-User-Id
string
required

The ID of the EndUser to receive this request (e.g., "Conductor-End-User-Id: {{END_USER_ID}}").

Example:

"end_usr_1234567abcdefg"

Body

application/json
​
name
string
required

The case-insensitive unique name of this sales-tax item, unique across all sales-tax items.

NOTE: Sales-tax items do not have a fullName field because they are not hierarchical objects, which is why name is unique for them but not for objects that have parents.

Maximum length: 31 characters.

Maximum length: 31
Example:

"Standard Tax"

​
barcode
object

The sales-tax item's barcode.

​
isActive
boolean
default:true

Indicates whether this sales-tax item is active. Inactive objects are typically hidden from views and reports in QuickBooks. Defaults to true.

Example:

true

​
classId
string

The sales-tax item's class. Classes can be used to categorize objects into meaningful segments, such as department, location, or type of work. In QuickBooks, class tracking is off by default.

Example:

"80000001-1234567890"

​
description
string

The sales-tax item's description that will appear on sales forms that include this item.

Example:

"Standard rate sales tax for California"

​
taxRate
string

The tax rate defined by this sales-tax item, represented as a decimal string. For example, "7.5" represents a 7.5% tax rate. This rate determines the amount of sales tax applied when this item is used in transactions. If a non-zero taxRate is specified, then the taxVendor field is required.

Example:

"7.5"

​
taxVendorId
string

The tax agency (vendor) to whom collected sales taxes are owed for this sales-tax item. This field refers to a vendor in QuickBooks that represents the tax authority. If a non-zero taxRate is specified, then taxVendor is required.

Example:

"80000001-1234567890"

​
salesTaxReturnLineId
string

The specific line on the sales tax return form where the tax collected using this sales-tax item should be reported.

Example:

"80000001-1234567890"

​
externalId
string

A globally unique identifier (GUID) you, the developer, can provide for tracking this object in your external system. This field is immutable and can only be set during object creation.

IMPORTANT: This field must be formatted as a valid GUID; otherwise, QuickBooks will return an error.

Example:

"12345678-abcd-1234-abcd-1234567890ab"

Response

200 - application/json
Returns the newly created sales-tax item.
​
id
string
required

The unique identifier assigned by QuickBooks to this sales-tax item. This ID is unique across all sales-tax items but not across different QuickBooks object types.

Example:

"80000001-1234567890"

​
objectType
string
required

The type of object. This value is always "qbd_sales_tax_item".

Allowed value: "qbd_sales_tax_item"
Example:

"qbd_sales_tax_item"

​
createdAt
string
required

The date and time when this sales-tax item was created, in ISO 8601 format (YYYY-MM-DDThh:mm:ss±hh:mm). The time zone is the same as the user's time zone in QuickBooks.

Example:

"2021-10-01T17:34:56.000Z"

​
updatedAt
string
required

The date and time when this sales-tax item was last updated, in ISO 8601 format (YYYY-MM-DDThh:mm:ss±hh:mm). The time zone is the same as the user's time zone in QuickBooks.

Example:

"2021-10-01T20:45:30.000Z"

​
revisionNumber
string
required

The current QuickBooks-assigned revision number of this sales-tax item object, which changes each time the object is modified. When updating this object, you must provide the most recent revisionNumber to ensure you're working with the latest data; otherwise, the update will return an error.

Example:

"1721172183"

​
name
string
required

The case-insensitive unique name of this sales-tax item, unique across all sales-tax items.

NOTE: Sales-tax items do not have a fullName field because they are not hierarchical objects, which is why name is unique for them but not for objects that have parents.

Example:

"Standard Tax"

​
barcode
string | null
required

The sales-tax item's barcode.

Example:

"012345678905"

​
isActive
boolean
required

Indicates whether this sales-tax item is active. Inactive objects are typically hidden from views and reports in QuickBooks. Defaults to true.

Example:

true

​
class
object | null
required

The sales-tax item's class. Classes can be used to categorize objects into meaningful segments, such as department, location, or type of work. In QuickBooks, class tracking is off by default.

Example:
{
  "id": "80000001-1234567890",
  "fullName": "State-Sales-Tax"
}
​
description
string | null
required

The sales-tax item's description that will appear on sales forms that include this item.

Example:

"Standard rate sales tax for California"

​
taxRate
string | null
required

The tax rate defined by this sales-tax item, represented as a decimal string. For example, "7.5" represents a 7.5% tax rate. This rate determines the amount of sales tax applied when this item is used in transactions. If a non-zero taxRate is specified, then the taxVendor field is required.

Example:

"7.5"

​
taxVendor
object | null
required

The tax agency (vendor) to whom collected sales taxes are owed for this sales-tax item. This field refers to a vendor in QuickBooks that represents the tax authority. If a non-zero taxRate is specified, then taxVendor is required.

Example:
{
  "id": "80000001-1234567890",
  "fullName": "State Tax Agency"
}
​
salesTaxReturnLine
object | null
required

The specific line on the sales tax return form where the tax collected using this sales-tax item should be reported.

Example:
{
  "id": "80000001-1234567890",
  "fullName": "Line 1: State Sales Tax"
}
​
externalId
string | null
required

A globally unique identifier (GUID) you, the developer, can provide for tracking this object in your external system. This field is immutable and can only be set during object creation.

Example:

"12345678-abcd-1234-abcd-1234567890ab"

​
customFields
object[]
required

The custom fields for the sales-tax item object, added as user-defined data extensions, not included in the standard QuickBooks object.