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


---

# 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/credits-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.