Actions

The ballerinax/hubspot.crm.commerce.taxes package exposes the following clients:

Client	Purpose
Client	Manage HubSpot commerce tax objects: CRUD, search, and batch operations.

---

Client

Manage HubSpot commerce tax objects: CRUD, search, and batch operations.

Configuration

Field	Type	Default	Description
auth	http:BearerTokenConfig|OAuth2RefreshTokenGrantConfig|ApiKeysConfig	Required	Authentication configuration: OAuth 2.0 refresh token, bearer token, or API keys.
httpVersion	HttpVersion	HTTP_2_0	HTTP protocol version.
timeout	decimal	30	Request timeout in seconds.
retryConfig	RetryConfig	()	Retry configuration for failed requests.
secureSocket	ClientSecureSocket	()	SSL/TLS configuration.
proxy	ProxyConfig	()	Proxy server configuration.
compression	http:Compression	COMPRESSION_AUTO	HTTP compression setting.
validation	boolean	true	Enable/disable payload validation.
laxDataBinding	boolean	true	Allow lax data binding for response payloads.

Initializing the client

import ballerinax/hubspot.crm.commerce.taxes;
import ballerina/oauth2;

configurable string clientId = ?;
configurable string clientSecret = ?;
configurable string refreshToken = ?;

taxes:Client taxesClient = check new ({
    auth: {
        clientId: clientId,
        clientSecret: clientSecret,
        refreshToken: refreshToken,
        credentialBearer: oauth2:POST_BODY_BEARER
    }
});

Operations

Single record operations

List taxes

Signature: get /

Retrieves a paginated list of tax objects, with optional filtering by properties, associations, and archived status.

Parameters:

Name	Type	Required	Description
properties	string[]?	No	Properties to include in the response.
associations	string[]?	No	Object types to retrieve associated IDs for.
'limit	int:Signed32	No	Maximum number of results per page (default 10).
after	string?	No	Paging cursor token for the next page of results.
archived	boolean	No	Whether to return only archived results (default false).
propertiesWithHistory	string[]?	No	Properties to return with their history of previous values.

Returns: CollectionResponseSimplePublicObjectWithAssociationsForwardPaging|error

Sample code:

CollectionResponseSimplePublicObjectWithAssociationsForwardPaging response =
    check taxesClient->/.get(
        properties = ["hs_label", "hs_value", "hs_type"],
        'limit = 10
    );

Sample response:

{
  "results": [
    {
      "id": "123456789",
      "properties": {
        "hs_label": "Sales Tax 8.5%",
        "hs_value": "8.5000",
        "hs_type": "PERCENT",
        "hs_createdate": "2025-01-15T10:30:00.000Z",
        "hs_lastmodifieddate": "2025-01-15T10:30:00.000Z"
      },
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:30:00.000Z",
      "archived": false
    }
  ],
  "paging": {
    "next": {
      "after": "NTI1Cg%3D%3D",
      "link": "?after=NTI1Cg%3D%3D"
    }
  }
}

Create a tax

Signature: post /

Creates a new tax object with the specified properties and optional associations.

Parameters:

Name	Type	Required	Description
payload	SimplePublicObjectInputForCreate	Yes	Tax record data including properties (e.g., hs_label, hs_value, hs_type) and optional associations.

Returns: SimplePublicObject|error

Sample code:

SimplePublicObject response = check taxesClient->/.post({
    properties: {
        "hs_label": "A percentage-based tax of 8.5%",
        "hs_value": "8.5000",
        "hs_type": "PERCENT"
    },
    associations: []
});

Sample response:

{
  "id": "123456789",
  "properties": {
    "hs_label": "A percentage-based tax of 8.5%",
    "hs_value": "8.5000",
    "hs_type": "PERCENT",
    "hs_createdate": "2025-01-15T10:30:00.000Z",
    "hs_lastmodifieddate": "2025-01-15T10:30:00.000Z"
  },
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z",
  "archived": false
}

Read a tax by ID

Signature: get /[taxId]

Retrieves a single tax object by its ID, with optional properties and associations.

Parameters:

Name	Type	Required	Description
taxId	string	Yes	The ID of the tax object to retrieve.
properties	string[]?	No	Properties to include in the response.
associations	string[]?	No	Object types to retrieve associated IDs for.
archived	boolean	No	Whether to return archived results (default false).
idProperty	string?	No	The name of a property whose values are unique for this object type.
propertiesWithHistory	string[]?	No	Properties to return with their history of previous values.

Returns: SimplePublicObjectWithAssociations|error

Sample code:

SimplePublicObjectWithAssociations response =
    check taxesClient->/[taxId].get(
        properties = ["hs_label", "hs_value", "hs_type"]
    );

Sample response:

{
  "id": "123456789",
  "properties": {
    "hs_label": "A percentage-based tax of 8.5%",
    "hs_value": "8.5000",
    "hs_type": "PERCENT",
    "hs_createdate": "2025-01-15T10:30:00.000Z",
    "hs_lastmodifieddate": "2025-01-15T10:30:00.000Z"
  },
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z",
  "archived": false
}

Update a tax

Signature: patch /[taxId]

Updates the properties of an existing tax object identified by its ID.

Parameters:

Name	Type	Required	Description
taxId	string	Yes	The ID of the tax object to update.
payload	SimplePublicObjectInput	Yes	Updated properties for the tax record.
idProperty	string?	No	The name of a property whose values are unique for this object type.

Returns: SimplePublicObject|error

Sample code:

SimplePublicObject response = check taxesClient->/[taxId].patch({
    properties: {
        "hs_label": "Updated tax at 7.5%",
        "hs_value": "7.5000"
    }
});

Sample response:

{
  "id": "123456789",
  "properties": {
    "hs_label": "Updated tax at 7.5%",
    "hs_value": "7.5000",
    "hs_type": "PERCENT",
    "hs_createdate": "2025-01-15T10:30:00.000Z",
    "hs_lastmodifieddate": "2025-01-16T08:00:00.000Z"
  },
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-16T08:00:00.000Z",
  "archived": false
}

Archive a tax

Signature: delete /[taxId]

Archives (soft-deletes) a tax object by its ID.

Parameters:

Name	Type	Required	Description
taxId	string	Yes	The ID of the tax object to archive.

Returns: error?

Sample code:

check taxesClient->/[taxId].delete();

Search

Search taxes

Signature: post /search

Searches for tax objects using filters, query text, sorting, and pagination.

Parameters:

Name	Type	Required	Description
payload	PublicObjectSearchRequest	Yes	Search request with optional query string, filter groups, sorts, properties, limit, and paging cursor.

Returns: CollectionResponseWithTotalSimplePublicObjectForwardPaging|error

Sample code:

CollectionResponseWithTotalSimplePublicObjectForwardPaging response =
    check taxesClient->/search.post({
        query: "tax",
        properties: ["hs_label", "hs_value", "hs_type"],
        sorts: ["hs_value"],
        'limit: 10
    });

Sample response:

{
  "total": 2,
  "results": [
    {
      "id": "123456789",
      "properties": {
        "hs_label": "Sales Tax 5%",
        "hs_value": "5.0000",
        "hs_type": "PERCENT"
      },
      "createdAt": "2025-01-10T09:00:00.000Z",
      "updatedAt": "2025-01-10T09:00:00.000Z",
      "archived": false
    },
    {
      "id": "987654321",
      "properties": {
        "hs_label": "Sales Tax 8.5%",
        "hs_value": "8.5000",
        "hs_type": "PERCENT"
      },
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:30:00.000Z",
      "archived": false
    }
  ]
}

Batch operations

Batch create taxes

Signature: post /batch/create

Creates multiple tax objects in a single request.

Parameters:

Name	Type	Required	Description
payload	BatchInputSimplePublicObjectInputForCreate	Yes	Batch input containing an array of tax records to create.

Returns: BatchResponseSimplePublicObject|BatchResponseSimplePublicObjectWithErrors|error

Sample code:

BatchResponseSimplePublicObject|BatchResponseSimplePublicObjectWithErrors response =
    check taxesClient->/batch/create.post({
        inputs: [
            {
                properties: {
                    "hs_label": "State Tax 6%",
                    "hs_value": "6.0000",
                    "hs_type": "PERCENT"
                },
                associations: []
            },
            {
                properties: {
                    "hs_label": "Fixed Fee $2.50",
                    "hs_value": "2.5000",
                    "hs_type": "FIXED"
                },
                associations: []
            }
        ]
    });

Sample response:

{
  "status": "COMPLETE",
  "results": [
    {
      "id": "111111111",
      "properties": {
        "hs_label": "State Tax 6%",
        "hs_value": "6.0000",
        "hs_type": "PERCENT",
        "hs_createdate": "2025-01-20T12:00:00.000Z",
        "hs_lastmodifieddate": "2025-01-20T12:00:00.000Z"
      },
      "createdAt": "2025-01-20T12:00:00.000Z",
      "updatedAt": "2025-01-20T12:00:00.000Z",
      "archived": false
    },
    {
      "id": "222222222",
      "properties": {
        "hs_label": "Fixed Fee $2.50",
        "hs_value": "2.5000",
        "hs_type": "FIXED",
        "hs_createdate": "2025-01-20T12:00:00.000Z",
        "hs_lastmodifieddate": "2025-01-20T12:00:00.000Z"
      },
      "createdAt": "2025-01-20T12:00:00.000Z",
      "updatedAt": "2025-01-20T12:00:00.000Z",
      "archived": false
    }
  ],
  "startedAt": "2025-01-20T12:00:00.000Z",
  "completedAt": "2025-01-20T12:00:01.000Z"
}

Batch read taxes

Signature: post /batch/read

Reads a batch of tax objects by their IDs or unique property values.

Parameters:

Name	Type	Required	Description
payload	BatchReadInputSimplePublicObjectId	Yes	Batch read input with IDs, properties to return, and optional ID property name.
archived	boolean	No	Whether to return archived results (default false).

Returns: BatchResponseSimplePublicObject|BatchResponseSimplePublicObjectWithErrors|error

Sample code:

BatchResponseSimplePublicObject|BatchResponseSimplePublicObjectWithErrors response =
    check taxesClient->/batch/read.post({
        inputs: [{id: "123456789"}, {id: "987654321"}],
        properties: ["hs_label", "hs_value", "hs_type"],
        propertiesWithHistory: []
    });

Sample response:

{
  "status": "COMPLETE",
  "results": [
    {
      "id": "123456789",
      "properties": {
        "hs_label": "Sales Tax 8.5%",
        "hs_value": "8.5000",
        "hs_type": "PERCENT"
      },
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:30:00.000Z",
      "archived": false
    },
    {
      "id": "987654321",
      "properties": {
        "hs_label": "Sales Tax 5%",
        "hs_value": "5.0000",
        "hs_type": "PERCENT"
      },
      "createdAt": "2025-01-10T09:00:00.000Z",
      "updatedAt": "2025-01-10T09:00:00.000Z",
      "archived": false
    }
  ],
  "startedAt": "2025-01-20T12:00:00.000Z",
  "completedAt": "2025-01-20T12:00:01.000Z"
}

Batch update taxes

Signature: post /batch/update

Updates multiple tax objects in a single request by their IDs or unique property values.

Parameters:

Name	Type	Required	Description
payload	BatchInputSimplePublicObjectBatchInput	Yes	Batch input containing an array of tax records with IDs and updated properties.

Returns: BatchResponseSimplePublicObject|BatchResponseSimplePublicObjectWithErrors|error

Sample code:

BatchResponseSimplePublicObject|BatchResponseSimplePublicObjectWithErrors response =
    check taxesClient->/batch/update.post({
        inputs: [
            {
                id: "123456789",
                properties: {
                    "hs_value": "9.0000"
                }
            },
            {
                id: "987654321",
                properties: {
                    "hs_value": "5.5000"
                }
            }
        ]
    });

Sample response:

{
  "status": "COMPLETE",
  "results": [
    {
      "id": "123456789",
      "properties": {
        "hs_label": "Sales Tax 8.5%",
        "hs_value": "9.0000",
        "hs_type": "PERCENT",
        "hs_lastmodifieddate": "2025-01-21T14:00:00.000Z"
      },
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-21T14:00:00.000Z",
      "archived": false
    },
    {
      "id": "987654321",
      "properties": {
        "hs_label": "Sales Tax 5%",
        "hs_value": "5.5000",
        "hs_type": "PERCENT",
        "hs_lastmodifieddate": "2025-01-21T14:00:00.000Z"
      },
      "createdAt": "2025-01-10T09:00:00.000Z",
      "updatedAt": "2025-01-21T14:00:00.000Z",
      "archived": false
    }
  ],
  "startedAt": "2025-01-21T14:00:00.000Z",
  "completedAt": "2025-01-21T14:00:01.000Z"
}

Batch upsert taxes

Signature: post /batch/upsert

Creates or updates a batch of tax objects by unique property values. If a record with the given ID property exists it is updated; otherwise a new record is created.

Parameters:

Name	Type	Required	Description
payload	BatchInputSimplePublicObjectBatchInputUpsert	Yes	Batch upsert input containing an array of tax records with IDs and properties.

Returns: BatchResponseSimplePublicUpsertObject|BatchResponseSimplePublicUpsertObjectWithErrors|error

Sample code:

BatchResponseSimplePublicUpsertObject|BatchResponseSimplePublicUpsertObjectWithErrors response =
    check taxesClient->/batch/upsert.post({
        inputs: [
            {
                id: "123456789",
                properties: {
                    "hs_label": "Upserted Tax 10%",
                    "hs_value": "10.0000",
                    "hs_type": "PERCENT"
                }
            }
        ]
    });

Sample response:

{
  "status": "COMPLETE",
  "results": [
    {
      "id": "123456789",
      "properties": {
        "hs_label": "Upserted Tax 10%",
        "hs_value": "10.0000",
        "hs_type": "PERCENT",
        "hs_lastmodifieddate": "2025-01-22T09:00:00.000Z"
      },
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-22T09:00:00.000Z",
      "archived": false,
      "new": false
    }
  ],
  "startedAt": "2025-01-22T09:00:00.000Z",
  "completedAt": "2025-01-22T09:00:01.000Z"
}

Batch archive taxes

Signature: post /batch/archive

Archives multiple tax objects in a single request by their IDs.

Parameters:

Name	Type	Required	Description
payload	BatchInputSimplePublicObjectId	Yes	Batch input containing an array of tax object IDs to archive.

Returns: error?

Sample code:

check taxesClient->/batch/archive.post({
    inputs: [{id: "123456789"}, {id: "987654321"}]
});