# 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 %}