Customers

Use the customers object are to manage your customers and exemptions

The customers object is used to represent one of your customers.

When to create Customers

You can create customers when you want to keep track of repeat purchases and traffic.

Additionally, you’ll need to create a customer when you want to indicate their purchases as tax exempt. Most often, this comes up if you’re selling to wholesalers, religious groups, or educational institutions.

How to create Customers

To create a customer, the minimum you’ll need is an email. You can also add a name and a reference_customer_id. If you add your own reference ID, you’ll be able to pass that in for future references to the customer. In either case, we’ll also give you back a customer_id that you can use.

You also have to option to mark the customer as tax exempt with the is_tax_exempt field. Let’s look at an example.

cURL

curl --request POST \
  --url https://api.numeralhq.com/tax/customers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Your Customer",
  "email": "[e-mail]",
  "is_tax_exempt": true,
  "reference_customer_id": "20506"
}'

Here, you’ve created a tax exempt customer and passed in a reference_customer_id.

We’ll respond with something that looks like

{
  "id": "cust_22a99d95-8bf6-4f6e-bdc3-ba5017E633e5",
  "object": "tax.customer",
  "reference_customer_id": "20506",
  "name": "Customer Name",
  "email": "[e-mail]",
  "is_tax_exempt": "true"
}

Take note that we’ve returned your reference_customer_id in addition to another, unique id that references the customer in the Numeral system. You’ll be able to use either when referring to the customer in the future.

Later, when you’re asking for a tax rate calculation, you’ll be able to pass in either of the id that Numeral created or the reference_customer_id that you passed in. In either case, for this customer, we’ll return a payload indicating that no tax should be charged, since you marked them as tax exempt.

Here’s an example:

Note that we’ve passed in the reference_customer_id under the customer.id field. You could also pass in the id we saw above.

curl --request POST \
  --url https://api.numeralhq.com/tax/calculations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "customer": {
    "id": "cus_123456789",
    "address": {
      "address_line_1": "3990 N County Rd 300 E",
      "address_city": "Danville",
      "address_province": "IN",
      "address_postal_code": "46122",
      "address_country": "US",
      "address_type": "shipping"
    }
  },
  "order_details": {
    "customer_currency_code": "USD",
    "tax_included_in_amount": false,
    "line_items": [
      {
        "reference_line_item_id": "line_123456789",
        "product_category": "GENERAL_MERCHANDISE",
        "amount": 200,
        "quantity": 2
      }
    ]
  }
}'

Below, you’ll get a calculation response indicating that the customer was tax exempt. See the note indicating that the exemption was a result of the customer being exempt. It’ll look something like this:

{
  "testmode": true,
  "id": "calc_173640158844105ffb1d5-37e6-4d6d-99db-659643bfc528",
  "object": "tax.calculation",
  "customer_currency_code": "USD",
  "line_items": [
    {
      "product": {
        "reference_line_item_id": "line_123456789",
        "reference_product_id": "temp-a4a427d4-42fc-47f1-9092-c74f935438a3",
        "reference_product_name": "temp-a4a427d4-42fc-47f1-9092-c74f935438a3",
        "product_tax_code": "GENERAL_MERCHANDISE"
      },
      "tax_jurisdictions": [
        {
          "tax_rate": 0,
          "rate_type": "Sales Tax",
          "jurisdiction_name": "State Tax",
          "fee_amount": 0,
          "note": "no_collection_exempt_customer"
        }
      ],
      "tax_amount": 0,
      "amount_excluding_tax": 200,
      "amount_including_tax": 200,
      "quantity": 2
    }
  ],
  "total_tax_amount": 0,
  "tax_included_in_amount": false,
  "total_amount_excluding_tax": 200,
  "total_amount_including_tax": 200,
  "expires_at": 1736487988
}

Further documentation

The full documentation for creating customers is on this page.