1 of 54

Dev

Inveterate Dev Docs

Welcome to the Inveterate developer documentation. Here we'll cover our API, API SDK and Frontend SDK.

Get Started

Get started by hopping into the documentation that is most necessary for you:

Public API 2.0 Reference [LEGACY] Public API Reference Storefront

API Reference Docs

Public API 2.0 Reference

API v1 has been updated with many new features, performance improvements, and a brand new roadmap that will empower our merchants to do so much more with our Public API.

Why Switch?

Massive performance improvements: most if not all endpoints are operating anywhere between 1.5x and 8x faster than our previous implementation.

Admin

Our admin endpoints.

Benefits

This set of benefit endpoints should only be used by merchant that have Tiers disabled. Benefit access for merchants that have enabled Tiers can be found in the Tiers tab in this API reference.

Members

Member accessing and altering endpoints.

Credits

Get and create credit requests.

Merchant

Get your merchant data. Serves as a good health check for our services and your API key/access.

Tiers

These endpoints only work for merchants with tiers enabled. Access benefits via this set of endpoints.

Benefits

Campaigns

Webhooks

Overview

Get, create, update and delete webhook subscriptions. Use these to build third-party integrations.

Topics

Once the webhook subscription is in place, you can have it choose to act on or disregard each of the types of events.

Customer events

Account
Orders and Payments
Credit
Cancellations

customer.joined.paid_tier

Triggered when a customer joins a paid tier in the loyalty program through subscription purchase.

`customer.joined.paid_tier`

Payload Structure

Payload Fields

payload

createdAt (string): ISO timestamp when the event was created
tierId (string): Unique identifier for the paid tier the customer joined
merchantId (string): Merchant identifier

metadata

id (string): Unique event identifier
retryCount (number): Number of retry attempts for this event
shopDomain (string): Shopify domain of the merchant

customer.joined.free_tier

Triggered when a customer joins a free tier in the loyalty program.

`customer.joined.free_tier`

Payload Structure

customer.joined.free_trial

Triggered when a customer joins a free trial tier in the loyalty program.

`customer.joined.free_trial`

Payload Structure

Payload Fields

payload

createdAt (string): ISO timestamp when the event was created
tierId (string): Unique identifier for the trial tier the customer joined
merchantId (string): Merchant identifier

metadata

id (string): Unique event identifier
retryCount (number): Number of retry attempts for this event
shopDomain (string): Shopify domain of the merchant

customer.joined.lifetime_tier

Triggered when a customer joins a lifetime tier in the loyalty program through one-time purchase.

`customer.joined.lifetime_tier`

Payload Structure

customer.changed_tier

Triggered when a customer changes from one tier to another in the loyalty program.

`customer.changed_tier`

Payload Structure

customer.updated

Triggered when a customer's information is updated.

`customer.updated`

Payload Structure

customer.ordered

Triggered when a customer places an order.

`customer.ordered`

Payload Structure

Payload Fields

payload

createdAt (string): ISO timestamp when the event was created
updatedAt (string): ISO timestamp when the event was last updated
merchantId (string): Merchant identifier

metadata

id (string): Unique event identifier
retryCount (number): Number of retry attempts for this event
shopDomain (string): Shopify domain of the merchant

customer.payment_succeeded

Triggered when a customer's payment is successfully processed.

`customer.payment_succeeded`

Payload Structure

customer.payment_failed

Triggered when a customer's payment has failed after all retry attempts have been exhausted.

`customer.payment_failed`

Payload Structure

customer_billing.attempt.failed

Triggered when a billing attempt fails but there may be more retry attempts remaining.

`customer_billing.attempt.failed`

Payload Structure

customer.payment_methods.updated

Triggered when a customer's payment method is updated.

`customer.payment_methods.updated`

Payload Structure

Payload Fields

payload

customerId (string): Customer identifier
merchantId (string): Merchant identifier
createdAt (string): ISO timestamp when the event was created

metadata

id (string): Unique event identifier
retryCount (number): Number of retry attempts for this event
shopDomain (string): Shopify domain of the merchant

customer.credits.updated

Triggered when a customer's credit balance is updated (credits earned or redeemed).

`customer.credits.updated`

Payload Structure

Payload Fields

payload

createdAt (string): ISO timestamp when the event was created
updatedAt (string): ISO timestamp when the event was last updated
merchantId (string): Merchant identifier

metadata

retryCount (number): Number of retry attempts for this event
shopDomain (string): Shopify domain of the merchant
topic (string): Event topic name

customer.credits.expired

Triggered when a customer's credits have expired and are removed from their balance.

`customer.credits.expired`

Payload Structure

Payload Fields

payload

merchantId (string): Merchant identifier
customerId (string): Customer identifier
email (string): Customer's email address

metadata

id (string): Unique event identifier
retryCount (number): Number of retry attempts for this event
shopDomain (string): Shopify domain of the merchant

customer.cancelled

Triggered when a customer's subscription is cancelled.

`customer.cancelled`

Payload Structure

Payload Fields

payload

createdAt (string): ISO timestamp when the event was created
tierId (string): Unique identifier for the tier the customer was cancelled from
merchantId (string): Merchant identifier

metadata

id (string): Unique event identifier
retryCount (number): Number of retry attempts for this event
shopDomain (string): Shopify domain of the merchant

customer.pending_cancellation

Triggered when a customer has requested cancellation but the cancellation is scheduled for a future date.

`customer.pending_cancellation`

Payload Structure

Payload Fields

payload

createdAt (string): ISO timestamp when the event was created
merchantId (string): Merchant identifier
customerId (string): Customer identifier

metadata

id (string): Unique event identifier
retryCount (number): Number of retry attempts for this event
shopDomain (string): Shopify domain of the merchant

Storefront

Our storefront-authenticated endpoints.

Members

Member get. Includes more member actions in sub-directories.

Credits

Get credits for a specific member.

Redemption

Create a credit redemption request for a member.

Cancellation

Create a cancellation request for a member.

Benefits

This set of benefit endpoints should only be used by merchant that have Tiers disabled. Benefit access for merchants that have enabled Tiers can be found in the Tiers tab in this API reference.

Tiers

These endpoints only work for merchants with tiers enabled. Access benefits via this set of endpoints.

Benefits

Campaigns

[LEGACY] Public API Reference

The Rest API allows you to build a highly custom paid-membership program on your Shopify storefront.

NOTE: With the release of Public API v2, Public API v1 will be sunset in May of 2024!

Find the v2 reference .

Campaigns API

Campaigns are directly associated with the Early Access benefit. It represents what collections will utilize the early access benefit and between what timeframes.

A campaign is represented as an object with the following structure:

{
  collectionIds: Array[String],
  endDate: String,
  updatedAt: String,
  startDate: String,
  createdAt: String,
  id: String,
  name: String,
  merchantId: String
}

Endpoints & Methods

Get all campaigns

GET https://public.inveterateapi.com/campaigns

Merchant API

A merchant is represented as an object with the following structure:

Endpoints & Methods

Get merchant

Free tiers API

This page covers api endpoints that allow merchants add customers to their free tier membership

To sign up for free tier membership, customer has to be registered in Shopify.

POST https://public.inveterateapi.com/signup-free-tier

Request Body

Name

Type

Description

Stack Reference Docs

Landing Page

This is an advanced guide.

Dealing with Slide Out Cart Behavior

Since we accommodate a wide variety of merchants who utilize a wide variety of themes, our code does not directly make changes to general functionality of themes. For instance, some themes will automatically update the cart contents and the cart icon in real-time when a product is added to cart and some do not. At a base level, our add to cart button on the landing page will do the following:

Storefront

On your storefront, we automatically add and update 2 files:

inveterate-theme.liquid
inveterate-checkout.liquid

See for more information about this.

Properties

All Inveterate properties can be found in the properties namespace within the inveterate object.

To view the properties object paste the following into the browser console:

window.inveterate.properties

The above code will display the following object structure:

benefits: An object of benefits you have enabled/disabled and all of the settings associated with them.
campaigns - An object of campaigns you have created in association with the Early Access benefit.
constants - Object is empty at the moment.
customer - An object containing information about the current signed in customer and their membership status.
pageType: The type of page you're currently on.
product: An object containing details about the membership subscription product.
redirectUrl: The default URL location of the landing page.
referralApiUrl: URL for making get request to track referrals.
referralData: An object containing the details of a referral in progress.
referralStorageName: The name where referral data is stored within localStorage.

Customizations

This section contains information about how to customize your storefront UI.

Add To Cart Button

Customer Metafields

When a member is created in our system we add a few values to Shopify customer metafields to make it easier to utilize specific information on the storefront website.

(Inveterate) Balance

This field is the store credits balance of the customer. This number indicates the amount of store credits they have received, but have not yet redeemed.

newData (object): Updated customer data
- accountState (string): Current state of the account (e.g., "ENABLED")
- lastCreditRedemptionAt (string|null): ISO timestamp of last credit redemption
- lastName (string): Customer's last name
- notes (string|null): Additional notes about the customer
- anonymized (boolean): Whether the customer data is anonymized
- createdAt (string): ISO timestamp when the customer was created
- revenue (number): Total revenue from the customer
- merchantId (string): Merchant identifier
- paymentId (string|null): Payment identifier
- referrals (number): Number of referrals made by the customer
- customerId (string): Customer identifier
- credit (number): Available credit amount
- email (string): Customer's email address
- updatedAt (string): ISO timestamp when the customer was last updated
- joinedAt (string): ISO timestamp when the customer joined
- trigger (string): Trigger type (e.g., "PAID_SUBSCRIPTION")
- firstName (string): Customer's first name
- creditsEarned (number): Total credits earned by the customer
- phoneNumber (string): Customer's phone number
- referredBy (string|null): Identifier of the customer who referred this customer
- contractId (number): Contract identifier
- lastPurchaseAt (string): ISO timestamp of last purchase
- currencyCode (string): Currency code (e.g., "USD")
- freeTrialActive (boolean): Whether the customer has an active free trial
- status (string): Customer status (e.g., "ACTIVE")
- tierId (string): Membership tier identifier
- tierName (string): Name of the membership tier
oldData (object): Previous customer data before the update
- Contains the same fields as newData
- May include additional fields like spendingProcess that were removed in the update

{ "payload": { "newData": { "accountState": "ENABLED", "lastCreditRedemptionAt": null, "lastName": "inveterate", "notes": null, "anonymized": false, "createdAt": "2025-05-25T00:27:56.503Z", "revenue": 102.32, "merchantId": "inveterate", "paymentId": null, "referrals": 0, "customerId": "22978031812972", "credit": 10, "email": "[email protected]", "updatedAt": "2025-05-25T00:27:59.220Z", "joinedAt": "2025-05-25T00:27:52Z", "trigger": "PAID_SUBSCRIPTION", "firstName": "inveterate", "creditsEarned": 10, "phoneNumber": "+16416805498", "referredBy": null, "contractId": 82559795564, "lastPurchaseAt": "2025-06-12T12:40:44.819Z", "currencyCode": "USD", "freeTrialActive": false, "status": "ACTIVE", "tierId": "c560bce7", "tierName": "PAID" }, "oldData": { "accountState": "ENABLED", "lastCreditRedemptionAt": null, "lastName": "inveterate", "notes": null, "anonymized": false, "spendingProcess": { "time": "2025-06-12T12:40:44.819Z", "status": "ACTIVE" }, "createdAt": "2025-05-25T00:27:56.503Z", "revenue": 102.32, "merchantId": "inveterate", "paymentId": null, "referrals": 0, "customerId": "22978031812972", "credit": 10, "email": "[email protected]", "updatedAt": "2025-05-25T00:27:59.220Z", "joinedAt": "2025-05-25T00:27:52Z", "trigger": "PAID_SUBSCRIPTION", "firstName": "inveterate", "creditsEarned": 10, "phoneNumber": "+16416805498", "referredBy": null, "contractId": 82559795564, "lastPurchaseAt": "2025-06-12T12:40:44.819Z", "currencyCode": "USD", "freeTrialActive": false, "status": "ACTIVE", "tierId": "c560bce7", "tierName": "PAID" } }, "metadata": { "id": "056f9ad3c189f9897e893c8477fce1f6", "retryCount": 0, "shopDomain": "inveterate.myshopify.com", "topic": "customer.updated", "version": "2025-06", "triggerredAt": "2025-06-12T12:40:46.309Z" } }

Add To Cart Button

Inveterate utilizes Shopify's native subscription functionality to provide a seamless purchasing experience for your customers. We create a normal product in your Shopify instance, but the main differences between this product and other products is it has a selling plan attached to it and it's a subscription-only product. A selling plan is the mechanism Shopify uses to identify how a subscription product should be billed and shipped to the customer. These selling plans have an ID attached to them which is required when adding the product to cart for Shopify to understand it needs to be treated line a subscription.

Normally, when adding a product to cart through Shopify's AJAX Cart API, you would do the following:

As shown above, we are adding one item to cart by passing in its variant ID and quantity in the id and quantity fields. For subscription products we would add the following change:

As shown above, we have mostly the same code with one small tweak. In the items array we've updated the item we're adding to have the selling plan id (seen in the selling_plan field). As mentioned earlier, this is what lets Shopify know that this is a subscription product and should be treated as such during checkout as well as in Shopify's backend system.

Where do I find the selling plan ID for my membership product?

Shopify does not display the selling plan ID in their admin, which makes it a little tougher to find. In our front end JavaScript, we've added some properties to help.

On the front end storefront of your site (any page besides checkout) type inveterate into your browser console. This should return an Object that looks something like this (if yours looks slightly different you're using a newer version):

If you see an error, that usually means the Inveterate app embed has not been enabled in the theme settings yet. Once enabled, you should be able to see this.

Next, type inveterate.properties.product. You should see the following:

If you see an error or "falsey" value, that usually means the product either has not been created correctly, is still in "Draft" mode in Shopify or is not in the "Online Store" sales channel. Check those three options before continuing.

With those 2 checks out of the way, you should be able to type in: inveterate.properties.product.selling_plan_groups[0].selling_plans[0].id which should display something like:

Those numbers are you selling plan ID. This is what you pass along to Shopify when adding the product to cart.

See as well for more information on selling plans.

(Optional) _inveterate_subscription Property

One last thing to notice in the fetch code snippet above is that we're passing in a properties object to Shopify with _inveterate_subscription: true. This is a useful troubleshooting tool to identify how the membership product was added to cart. This is not required, but strongly recommended to add.

How To Set Up ATCs For Tiers

When setting up a landing page with multiple tiers, the process remains the same for each ATC button. As you configure each one, you just need to ensure you select the correct product and selling plan for each ATC button.

You can find the product, variant and selling plan information for each tier in our inveterate.membershipProducts property.

If you use a custom Landing Page, you will need to adjust the Add To Cart code further in order for the benefit to work properly. In the guide above, only one product was added to the [items] array. In order to configure the Free Gift benefit, all you need to do is add the second (free gift) product to the array as well.

This is an example of one product:

This is an example of two products, e.g. the membership product and the free gift:

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:

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

Headers

Name

Type

Description

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

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.

In the case of a missing customerId parameter, you will receive the following:

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

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

Headers

Name

Type

Description

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.

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

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

On failure, you will receive a code 400. There are a few reasons this may be. Primarily, an incomplete body in the request.

On success, you will receive a response code 200 and the response body will contain the discount code generated by our back-end.

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

Webhooks

Use the "Create Webhook Subscriber" endpoint and pass in a callbackUrl on your system that will receive a POST request for all of events listed below.

Once the webhook subscriber is in place, you can have it choose to act on or disregard each of the following types of events.

Webhooks Events

Merchant events

merchant.updated
merchant.reinstall

Customer events

Account
- customer.created
- customer.updated

Create a Webhook Subscriber

The token field in the response body for the Create Webhook Subscriber endpoint is important to take note of. For security reasons, it only appears here, and in the body of post requests for events forwarded from the Inveterate system to the subscriber's callbackUrl. This will allow your 3rd party app to make sure the requests made to your endpoint are legitimate. Simply store the token value you get when you create the subscriber, and check for incoming events on your callbackUrl for a matching token in the request body.

Create Webhook Subscriber

POST https://public.inveterateapi.com/webhooks

Headers

Name

Type

Description

Request Body

Name

Type

Description

Get Webhook Subscribers

You may have wondered about the createdByApp field in the response body for the "Create Webhook Subscriber" request. This is derived from the app field which is attached behind the scenes to your API key (the X-Inveterate-Api-Key one). For example, let's say you work at a SaaS company called "Smithy", and are developing an integration with Inveterate. Then the API key you are issued to access the Inveterate API will have an app field value of Smithy, and all the webhook subscriber objects created with your API key will have the same createdByApp value.

TLDR: The "Get Webhook Subscribers" endpoint responds with all the webhook subscribers associated with the X-Inveterate-Api-Key included in the request. Note that this is not necessarily all of the webhook subscribers associated with a particular merchant, but a particular app.

Get Webhook Subscribers

GET https://public.inveterateapi.com/webhooks

Get all webhook subscribers associated with this X-Inveterate-Api-Key value.

Headers

Name

Type

Description

Delete Webhook Subscriber

DELETE https://public.inveterateapi.com/webhooks

Headers

Name

Type

Description

Request Body

Name

Type

Description

Anecdote: Cancellation Events

Customer cancellation events follow different patterns depending on the cause of cancellation (payment failure or customer request) and, for the latter, also the store's cancellation policy.

Please take a look at the trees of events below to see which cancellation lifecycle should be expected for a given customer, given the circumstances of their cancellation.

Event Timeline: Cancellation due to payment failure

Let's say the customer's payment was due on Jan 10, it failed then. Two more follow-up attempts will be performed over the next two days. If these two fail as well, then the customer will be automatically cancelled and will lose access to their benefits.

Jan 10

Event trigger: customer_billing.attempt.failed
- If enabled in merchant's messaging, user also gets an e-mail communicating them of the payment failure and informing them that they have three days to update their payment methods.

Jan 11

Event trigger: customer_billing.attempt.failed

Jan 12

Event trigger: customer_billing.attempt.failed , customer.payment_failed
Customer gets cancelled and loses access to their benefits
- if cancellation policy is immediately, customer status

Event Timelines: Cancellation due to customer request

For stores with cancellation policy set to immediate:

Customer requests cancellation
- Event trigger: customer.cancellation_requested
Confirmation e-mail is sent, asking customer to confirm

Stores with cancellation policy set to end of billing cycle:

Customer requests cancellation
Event trigger: customer.cancellation_requested
Confirmation e-mail is sent, asking customer to confirm