> ## Documentation Index
> Fetch the complete documentation index at: https://docs.numeral.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 theme={null}
curl --request POST \
  --url https://api.numeralhq.com/tax/customers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Your Customer",
  "email": "customer@example.com",
  "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

```json theme={null}
{
  "id": "cust_22a99d95-8bf6-4f6e-bdc3-ba5017E633e5",
  "object": "tax.customer",
  "reference_customer_id": "20506",
  "name": "Customer Name",
  "email": "customer@example.com",
  "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 theme={null}
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:

```json theme={null}
{
  "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](/api-reference/endpoint/customers).