Credits API

This page covers API endpoints that allow merchants to retrieve and modify user credits.

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:

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

Endpoints & Methods

Get a customers credit ledger history

GET 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*	Number	The customer ID which you intend to pull the data of.

Headers

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

200: OK Success

In the case of a success, you will see a return that looks like the following:

{
    "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.

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:

{
    "message": "Unauthorized"
}

Add credits to a customer

POST 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*	Number	The ID which identifies the customer you intend to add credits to.
credit*	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.

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.

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.

Create a request to redeem credits

POST 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*	number	The customer ID for which you intend to create a redemption request for.
amount*	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*	string	The merchant ID for the store.

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.

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.

500: Internal Server Error On failure.

Referencing an inexistent customerId or the referenced customer having insufficient funds are the two main reasons for failures.