To accurately calculate sales tax, we need to know the category of the product you’re selling. We offer two ways to share this information, and you can select the approach that fits best with your business and integration needs.

Early in your integration, you should make a decision to either

  1. Categorize and register your products with Numeral
  2. Manage your product categories on your own

We generally recommend that users choose option (1), as it leads to the tightest compliance, least amount of information that you need to store, and strongest reporting and reconciliation. However, many clients prefer option (2), often if they just sell one thing or have products with all the same categories.

Depending on which option you choose, you’ll use the calculation endpoint differently.

If you categorize and register your products with Numeral, the line items you pass in will include a reference_product_id. We’ll use this product’s pre-registered category to ensure we return the correct amount of tax.

 "line_items": [
      {
        "reference_product_id": "p-1233543",
        "amount": 200,
        "quantity": 2
      }
    ]

If you manage product categories on your own, you are more likely to pass in a product_category with each line item. If you use this approach, we’ll use the category you give us to calculate the correct tax amount.

"line_items": [
      {
        "product_category": "GENERAL_MERCHANDISE",
        "amount": 200,
        "quantity": 2
      }
    ]

​
Option 1: Categorize and register your products with Numeral

If you take this approach, you’ll need to pre-register your products before you begin calculating tax on your sales. You’ll upload and categorize each of your products using the products endpoint.

Taking this approach ensures that each product you sell has the correct category assigned to it, and that you don’t need to store tax categories in your system. You can just pass the same identifier you use in your existing system to each calculation API call as a reference_product_id.

Additionally, we’ll include the product’s details (like the product name, category and ID) on your filing reports, so you can more easily tie back these line items to the sales in your system.

When you introduce a new product, you’ll need to remember to upload it to Numeral before you begin selling it. If you pass in a reference_product_id we don’t recognize to the calculations endpoint, we will throw an error.

​
Option 2: Manage product categories on your own

If you take this approach, you can pass in a product category to the calculations endpoint without registering the product with Numeral ahead of time.

This does mean that you’ll want to store the Numeral tax category with each product in your system so you can pass in the correct category. However, if you only sell one product or one category of product, you can just pass this category in with every calculation.

This approach also means you won’t need to register new products with Numeral before beginning sales, but you’ll need to ensure you categorize them appropriately in your system.

​
Learn more

You can read more about the product and calculation objects and investigate their respective API endpoints.

Create Products

Create Calculations

View the Product Categories

Reference ObjectsExemptions Behavior