# Credits API

Internally, credits are stored with a long list of attached data-values used for internal operations. For the purposes of this documentation, `credit` entries are represented with the following structure:

```javascript
{
    amount: number;
    createdAt: string;
    newBalance: number;
    reason: string;
}
```

## Endpoints & Methods

## Get a customers credit ledger history

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

This endpoint will pull all credit history for a given user. For batch operations, each `customerId` should be its own API call. Ensure that query parameter `customerId` is included after the endpoint path, in the form of:

`.../customers/credits?customerId=1234567890`

#### Path Parameters

| Name                                         | Type   | Description                                           |
| -------------------------------------------- | ------ | ----------------------------------------------------- |
| customerId<mark style="color:red;">\*</mark> | Number | The customer ID which you intend to pull the data of. |

#### 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 Success" %}
In the case of a success, you will see a return that looks like the following:

```json
{
    "credits": [
        {
            "amount": 5,
            "createdAt": "2000-01-01T12:00:00.000Z",
            "newBalance": 10,
            "reason": "MANUAL"
        },
        {
            ... // another object of the same structure
        }
        ... // more objects of the same structure
    ],
    
    /*
     * If the user has activated a discount code for redemption
     * through their member portal, it will be included here as follows.
     *
     * If there is no active code, redemption will be null.
     */
    "redemption": {
        "code": "REDEEM+123456789", // always begins with "REDEEM+"
        "value": 5 // USD
    }
}
```

**NOTE:** Please keep in mind that the response is exactly as it appears in the credit ledger. This means that *all* credits, even expired credits, will appear in the response. If you are using the Expiring Credits benefit and you want to calculate an accurate balance for a customer, ensure that you check the returned entries for expired entries and deduct those values.
{% endtab %}

{% tab title="400: Bad Request All errors" %}
In the case of a missing `customerId` parameter, you will receive the following:

```
{
    "success": false,
    "data": {},
    "errors": [
        "Missing query parameter: customerId"
    ]
}
```

In the case of a missing or invalid `X-Inveterate-Api-Key`, you will receive the following:

```json
{
    "message": "Unauthorized"
}
```

{% endtab %}
{% endtabs %}

## Add credits to a customer

<mark style="color:green;">`POST`</mark> `https://public.inveterateapi.com/customers/credits`

This endpoint will create a ledger entry for a given `customerId`, enabling you to add credits to a customer. For batch operations, each `customerId` should be its own API call. Ensure that the query parameters, `customerId` and `credit`, are included in the path in the form:

`.../customers/credits?customerId=1234567890&credit=5`

#### Path Parameters

| Name                                         | Type   | Description                                                        |
| -------------------------------------------- | ------ | ------------------------------------------------------------------ |
| customerId<mark style="color:red;">\*</mark> | Number | The ID which identifies the customer you intend to add credits to. |
| credit<mark style="color:red;">\*</mark>     | Number | The credit amount you intend to add to the customer.               |

#### Headers

| Name                 | Type   | Description                                                                                            |
| -------------------- | ------ | ------------------------------------------------------------------------------------------------------ |
| X-Inveterate-Api-Key | String | Required to access all protected endpoints on this API. Obtained from merchant's Inveterate dashboard. |

{% tabs %}
{% tab title="200: OK Success (please see details)" %}
Please note that 200 does not *guarantee* that the request was actually successful. It means that our back-end successfully received the request and it is being processed. The only place where this could serve to be an issue is the case that you enter an incorrect `customerId`.

If you are manually inputting all `customerId` values for batch calls, you can ensure that the call was successful by performing a `GET` call and confirming the `createdAt` date. Please keep in mind that there may be a few-second delay before the credits are fully processed and added in our back-end.
{% endtab %}

{% tab title="400: Bad Request All errors" %}
You will receive a number of different errors, similar to the ones in the `GET` endpoint (please review those two errors for reference), if you don't include the two query parameters or if your `X-Inveterate-Api-Key` is invalid.&#x20;
{% endtab %}
{% endtabs %}

## Create a request to redeem credits

<mark style="color:green;">`POST`</mark> `https://public.inveterateapi.com/redemption-discount-code`

Create a request to redeem credits as a discount code that can be used by a customer. All data should be passed through the request body (see parameters).

#### Request Body

| Name                                         | Type   | Description                                                                                                             |
| -------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------- |
| customerId<mark style="color:red;">\*</mark> | number | The customer ID for which you intend to create a redemption request for.                                                |
| amount<mark style="color:red;">\*</mark>     | number | The amount of credits you would like to redeem to this discount code.                                                   |
| email                                        | string | The email for the customer. This may not be required. If a request fails, attempt the request with the customers email. |
| merchantId<mark style="color:red;">\*</mark> | string | The merchant ID for the store.                                                                                          |

{% tabs %}
{% tab title="400: Bad Request On bad input." %}
On failure, you will receive a code 400. There are a few reasons this may be. Primarily, an incomplete body in the request.
{% endtab %}

{% tab title="202: Accepted On success." %}
On success, you will receive a response code 200 and the response body will contain the discount code generated by our back-end.
{% endtab %}

{% tab title="500: Internal Server Error On failure." %}
Referencing an inexistent `customerId` or the referenced customer having insufficient funds are the two main reasons for failures.
{% endtab %}
{% endtabs %}