Tax classes, tax products, and the rates in your tax zones have Console screens for day-to-day setup. This reference covers the changes you can make only by calling the API directly. Through the API, you can update one field at a time, change many records in one request, record a tax product for one class within a rate, turn off a rate without deleting it, and save your own custom field values. For the Console screens, see the tax configuration topics for Orders & Inventory.
Changing One Field at a Time with a Patch
When you only need to change part of a tax class or tax product, send a patch instead of the full record. The same rules apply to tax classes and tax products:
| Situation | Result |
|---|---|
| The record does not exist | The request is refused as not found, because a patch never creates a record |
| An instruction tries to change the record's own identifier | The request is refused |
| A tax product's patch tries to change which business unit it belongs to | The request is refused |
| An instruction is malformed | The request is refused |
| Another write saves the same record between when your patch reads it and when it saves | The request is refused, so you can retry with the current version |
Changing Many Tax Classes or Products in One Request
You can create, change, or delete several tax classes in one batch request. You can also do the same for several tax products. The route is described as accepting up to 100 operations, but Rhythm does not enforce that limit today, so a request with more operations is not refused for that reason alone.
Warning
If two operations in the same batch use the same record identifier, the whole batch is refused. Batch operations run in parallel, so they do not always run in the order shown in the request. Do not put two operations for the same record in one batch when one depends on the other.
Recording Tax on One Class Within a Rate
Within a rate, each class of goods can use its own tax product instead of the rate's default. You can set this per-class product only through a direct API write; the Console does not show a field for it or let you set it. If a value is already saved there, the Console's zone editor preserves it when you save other changes.
After a class within a rate names a tax product this way, Rhythm treats that product as in use. You cannot delete the product while the class entry still names it.
Turning a Rate Off Without Deleting It
Every rate has an enabled value, and Rhythm refuses a rate saved without one. The Console gives every new rate enabled: true and has no control for changing it. If you disable a rate through the API, it still looks normal in the Console, with nothing on screen to show that it is off.
Custom Fields on Tax Classes and Products
Tax classes and tax products can store your account's own custom field values. Rhythm saves and cleans up those values the same way it handles custom fields elsewhere. For what a custom field is and how your organization adds one, see Custom Fields Explained. Rhythm drops empty custom field values before the record saves. No tax screen in the Console shows these values, so you must use the API to set or read them.
Deriving Tax on Changed Orders in a Query
Rhythm does not expose a direct tax-amount field you can add to a query for an order that was later changed, such as by a partial refund. As a workaround, include both the Amount Paid field and the Order Amount Paid field in your query. The difference between those two values represents the tax amount.
Your Account's Tax Setup Only
Every request to a tax operation, including the ones in this reference, is limited to your own Rhythm account's tax setup. This is true whether the request comes through the Console or directly through the API. A request that identifies with a different account is refused. This account check is the only access requirement the tax services apply to these operations; there is no separate tax-specific permission beyond it.