# Customers API

A customer in the Inveterate system is anyone that has purchased an Inveterate subscription product from this merchant's store.

A `customer` is represented as an object with the following structure:

```javascript
{
  accountState: String, // from Shopify
  contractId: Number,
  createdAt: String,
  credit: Number,
  customerId: String,
  email: String,
  firstName: String,
  lastName: String,
  orderCount: Number,
  orderIds: Array[Number]
  merchantId: String,
  status: String, // status of Inveterate subscription
  totalSpend: Number,
  updatedAt: String
}
```

## Endpoints & Methods

## Get a single customer

<mark style="color:blue;">`GET`</mark> `https://public.inveterateapi.com/customers/{customerId}`

Gets a single customer.

#### Path Parameters

| Name                                         | Type   | Description                             |
| -------------------------------------------- | ------ | --------------------------------------- |
| customerId<mark style="color:red;">\*</mark> | String | The Shopify ID for a specific customer. |

#### Headers

| Name                                                   | Type   | Description                                                                                            |
| ------------------------------------------------------ | ------ | ------------------------------------------------------------------------------------------------------ |
| X-Inveterate-Api-Key<mark style="color:red;">\*</mark> | String | Required to access all protected endpoints on this API. Obtained from merchant's Inveterate dashboard. |

{% tabs %}
{% tab title="200 Get customer success" %}

```json
{
  "data": {
    "customer": {
      "accountState": "ENABLED",
      "contractId": 1234567890,
      "createdAt": "2021-10-27T18:10:08.754Z",
      ...
    }
  }
  "success": true,
  "errors": []
}
```

{% endtab %}

{% tab title="400: Bad Request All errors" %}

```json
{
  "data": {}
  "success": false,
  "errors": [
    "Invalid API key"
  ]
}
```

{% endtab %}
{% endtabs %}

## Get all customers

<mark style="color:blue;">`GET`</mark> `https://api.inveterate.com/2022-01/customers`

#### Query Parameters

| Name           | Type | Description                                                                 |
| -------------- | ---- | --------------------------------------------------------------------------- |
| limit          | Int  | Amount of customers to return per request. Default is no limit. Max is 100. |
| lastCustomerId | Int  | Used to determine the index offset of which customers to return.            |

#### Headers

| Name                                                   | Type   | Description                                                                                            |
| ------------------------------------------------------ | ------ | ------------------------------------------------------------------------------------------------------ |
| X-Inveterate-Api-Key<mark style="color:red;">\*</mark> | String | Required to access all protected endpoints on this API. Obtained from merchant's Inveterate dashboard. |

{% tabs %}
{% tab title="200: OK Get customers success" %}

```javascript
{
  "data": {
    "customers": [
      {
        "accountState": "ENABLED",
        "contractId": 1234567890,
        "createdAt": "2021-10-27T18:10:08.754Z",
        ...
      }
    ],
    "lastCustomerId": "1234567890"
  }
  "success": true,
  "errors": []
}
```

{% endtab %}

{% tab title="400: Bad Request All errors" %}

```javascript
{
  "data": {}
  "success": false,
  "errors": [
    "Invalid API key"
  ]
}
```

{% endtab %}
{% endtabs %}

### Get Customers (Paginated)

Optionally using the `limit` and `lastCustomerId` query string parameters, you can "paginate" through the customer records returned.

For the first page, just add the `limit` parameter. The response for this will include the `lastCustomerId`, which needs to be added as a query string parameter to the request for page 2.

#### Page 1 request example

```
curl --location --request GET "${PUBLIC_API_URL}/customers?limit=1" \
--header "X-Inveterate-Api-Key: ${PUBLIC_API_KEY}"
```

#### Page 1 response example

```
{
    "success": true,
    "data": {
        "customers": [
            {
                "lastName": "Alda",
                "firstName": "Alan",
                "customerId": "6082598928622"
            }
        ],
        "lastCustomerId": "6082598928622",
        "limit": "1"
    },
    "errors": []
}
```

#### Page 2 request example

```
curl --location --request GET "${PUBLIC_API_URL}/customers?limit=1&lastCustomerId=6082598928622" \
--header "X-Inveterate-Api-Key: ${PUBLIC_API_KEY}"
```

#### Page 2 response example

```
{
    "success": true,
    "data": {
        "customers": [
            {
                "lastName": "Bernanke",
                "firstName": "Ben",
                "customerId": "6082606694638"
            }
        ],
        "lastCustomerId": "6082606694638",
        "limit": "1"
    },
    "errors": []
}
```

## Cancel Customer Subscription

## Request customer cancellation

<mark style="color:green;">`POST`</mark> `https://public.inveterateapi.com/customers/{customerId}/cancel`

Step 1 of the customer's subscription cancellation process. A successful request to this endpoint submits a customer cancellation request. Customer will receive an email with a link to confirm cancellation of their subscription.

#### Request Body

| Name                                         | Type   | Description |
| -------------------------------------------- | ------ | ----------- |
| merchantId<mark style="color:red;">\*</mark> | String |             |

{% tabs %}
{% tab title="200: OK Request received successfully" %}

```javascript
{
    "success": true,
    "data": {
        "cancelRequest": {
            "merchantId": "inveterate-staging-barefoot",
            "cancelToken": "c52157e9-2406-49d1-b374-583c92a3e3dd",
            "customerId": "5574691979318",
            "status": "INITIALIZED",
            "createdAt": "2022-03-15T00:07:16.168Z",
            "updatedAt": "2022-03-15T00:07:16.168Z"
        }
    },
    "errors": []
}
```

{% endtab %}

{% tab title="400: Bad Request All errors" %}

```javascript
{
  "data": {}
  "success": false,
  "errors": [
    "Invalid API key"
  ]
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.inveterate.com/dev/api-reference-docs/legacy-public-api-reference/customers-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.