1 of 55

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.
Stricter internal security.
Support for Tiers
A roadmap that will allow you to do many new and powerful things with our Public API.
Public API v1 will sunset in May of 2024!

Authentication

API Keys are private and should not be shared or exposed on the front end.

Using API Key in Requests

As with v1, authentication is done via the request header. Include your API key as an X-Inveterate-Api-Key header on all API endpoint requests.

API URL

All API requests utilize https://public.inveterateapi.com/v2.0/ as the base URL. If you have any issues, double check that you are prepending with https:// and appending /v2.0.

Example Get Request

Admin vs Storefront

As of now, admin and storefront methods operate in the same way--use the same API key in the header to authenticate both kinds of endpoints. The admin endpoints were created to model after admin actions within the merchant dashboard, while the storefront was made to model data that members are allowed to access.

In the (near) future, storefront endpoints will have their own "storefront" authentication through Shopify using a member's credentials. This will allow you to build authenticated apps and services outside of the Inveterate/Shopify ecosystem.

The storefront endpoints will always support authentication via the X-Inveterate-Api-Key, however.

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

Payload Fields

payload

createdAt (string): ISO timestamp when the event was created
tierId (string): Unique identifier for the 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_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

Payload Fields

payload

createdAt (string): ISO timestamp when the event was created
tierId (string): Unique identifier for the lifetime 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.changed_tier

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

`customer.changed_tier`

Payload Structure

Payload Fields

payload

createdAt (string): ISO timestamp when the event was created
tierId (string): Unique identifier for the new tier the customer moved to
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.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

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

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_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

customer.credits.updated

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

`customer.credits.updated`

Payload Structure

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

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 here.

Authentication

API Keys are private and should not be shared or exposed on the front end.

Using API Key in Requests

Include your API key as an X-Inveterate-Api-Key header on all API endpoint requests.

Requirements

All API requests utilize https://public.inveterateapi.com/ as the base URL.

Example Get Request

Reference Shortcuts

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

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

Gets merchant data.

Headers

Name

Type

Description

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

Stack Reference Docs

Landing Page

This is an advanced guide.

Dealing with Slide Out Cart Behavior

Storefront

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

inveterate-theme.liquid
inveterate-checkout.liquid

See Snippets for more information about this.

What is the Inveterate Storefront code?

The Inveterate Storefront code is code used to implement front end solutions involving memberships. It contains useful data and helpful functions we use for our standard features, as well as merchant to merchant custom features.

The `inveterate` object

All of the storefront code is contained within a single object called inveterate, which is attached to the window object.

To explore everything contained in the inveterate object, type the following code in your browser console:

Visit the following links for more information about what's contained within the inveterate object.

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:

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.

Customer Metafields

When a member is created in our system, Inveterate adds values to Shopify customer metafields. These metafields make it easier to reference membership-related data on the storefront (or in integrations).

All customer metafields below use:

Namespace: inveterate
Owner type: CUSTOMER

Metafields

(Inveterate) Balance

Metafield

Namespace: inveterate
Key: balance
Type: number_decimal

Description 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.

(Inveterate) Next Payment

Metafield

Namespace: inveterate
Key: next_payment
Type: single_line_text_field

Description This field displays the next payment date for the customer's membership. It is stored in ISO format (e.g. 2026-02-05).

(Inveterate) Referrals

Metafield

Namespace: inveterate
Key: referrals
Type: single_line_text_field

Description This field displays a list of all completed referrals made by the member.

(Inveterate) Experience Segment

Metafield

Namespace: inveterate
Key: segment_id
Type: single_line_text_field

Description This field stores the member’s Experience Segment identifier.

(Inveterate) Payment Amount

Metafield

Namespace: inveterate
Key: payment_amount
Type: single_line_text_field

Description This field displays the amount the member has agreed to pay for the membership.

(Inveterate) Payment Currency

Metafield

Namespace: inveterate
Key: payment_amount_currency
Type: single_line_text_field

Description This field displays the currency for the member’s membership payment amount (for example, USD).

(Inveterate) Credits Earned

Metafield

Namespace: inveterate
Key: credits_earned
Type: number_decimal

Description This field stores the total amount of credits earned by the member

Usage Notes

These metafields may be surfaced in Inveterate webhook payloads depending on the event type.

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

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

patch

This endpoint will take a benefit type and any other values in the relevant schema and send a request to our backend to update the benefit. with the new information. Keep in mind that, like with the POST method, this is a request against our backend. Thus, the effect will not be immediate.

Path parameters

typestringRequired

The benefit identification name/type.

Header parameters

X-Inveterate-Api-KeystringRequired

Your private Inveterate API key.

Body

creditAmountnumberRequired

The amount to be awarded upon sign-up.

namestringRequired

The name (appearance only) of this benefit.

daysnumberRequired

The number of days to delay the credit award.

descriptionstringRequired

The description of this benefit (appearance only).

typeobjectRequired

This is an internal identifier, leave default.

Default: SIGNUP_STORE_CREDITS

creditAmountnumberRequired

The amount to be awarded each recurrence.

namestringRequired

The name (appearance only) of this benefit.

descriptionstringRequired

The description of this benefit (appearance only).

frequencynumberRequired

How often (in days) you want to award this credit.

typeobjectRequired

This is an internal identifier, leave default.

Default: SCHEDULED_STORE_CREDITS

internalTitlestringRequired

The internal identifier, leave default.

typeobjectRequired

This is an internal identifier, leave default.

Default: CREDITS_FOR_ORDERS

namestringRequired

The name (appearance only) of this benefit.

descriptionstringRequired

The description of this benefit (appearance only).

enabledbooleanRequired

Whether this benefit is enabled or not.

rulestring · enumRequired

Which credit rule: "PERCENTAGE_BACK_ON_PURCHASE", "EARN_EVERY_ORDER", or "SPEND_AND_EARN".

Possible values:

rewardValuenumberRequired

The amount of credits (or percent) to give as an award.

excludeInveterateMembershipProductsbooleanRequired

Whether or not to include the membership product for credit.

minimumPurchaseAmountnumberRequired

The minimum individual purchase amount to award credit for orders.

maximumRewardValuestringRequired

The discount code to use for this benefit.

allowRefundsbooleanRequired

Whether or not this benefit is displayed on the landing page.

appliesTostring · enumRequired

Which products or collections this benefit applies to: "ALL_PRODUCTS", "SPECIFIC_PRODUCTS", or "SPECIFIC_COLLECTIONS".

Possible values:

applicableTostring[]Required

If appliesTo is either of the latter two values, this is a string array of Shopify Product IDs or Collection IDs (i.e. "gid://shopify/Collection/266717724758").

creditAmountnumberRequired

The amount of credits to award on anniversary.

namestringRequired

The name (appearance only) of this benefit.

descriptionstringRequired

The description of this benefit (appearance only).

typeobjectRequired

This is an internal identifier, leave default.

Default: ANNIVERSARY_CREDITS

creditAmountnumberRequired

The amount of credits to award on referral.

namestringRequired

The name (appearance only) of this benefit.

descriptionstringRequired

The description of this benefit (appearance only).

typeobjectRequired

This is an internal identifier, leave default.

Default: REFERRALS

shippingTypestring · enumRequired

Which shipping type: "DISCOUNT_CODE" or "SCRIPT".

Possible values:

codestringRequired

The name (appearance only) of this benefit.

minRequirementsstring · enumRequired

Which minumum requirements: "ITEM_QUANTITY", "PURCHASE_AMOUNT", or "NONE".

Possible values:

isRatesExcludedbooleanRequired

Whether or not to include purchases with shipping rates over a certain value.

maximumShippingPricenumberRequired

The maximum shipping rate over which shipping is not free (only with previous value true).

minimumQuantitynumberRequired

If minRequirements is "ITEM_QUANTITY", include this field to indicate minimum number of items.

minimumSubtotalnumberRequired

If minRequirements is "PURCHASE_AMOUNT", include this field to indicate the minumum purchase amount.

countryTypestring · enumRequired

Which country type: "ALL" or "SPECIFIC".

Possible values:

countriesstring[]Required

If previous value is "SPECIFIC", this field contains the specific countries in the format: { "label": "United States", "value": "United States" }

typeobjectRequired

This is an internal identifier, leave default.

Default: FREE_SHIPPING

namestringRequired

The name (appearance only) of this benefit.

descriptionstringRequired

The description of this benefit (appearance).

typeobjectRequired

This is an internal identifier, leave default.

Default: DISCOUNTS

namestringRequired

The name (appearance only) of this benefit.

descriptionstringRequired

The description of this benefit (appearance).

discountTypestring · enumRequired

Which discount type: "percentage" or "fixed".

Possible values:

valuenumberRequired

The fixed or percentage award value.

collectionIdsstring[]Required

If using collections, this is a string array of Shopify Collection IDs (i.e. "gid://shopify/Collection/266717724758").

productIdsstring[]Required

If using products, this is a string array of Shopify Product IDs (i.e. "gid://shopify/Product/266717724758").

minimumSubtotalnumberRequired

The minimum subtotal for an individual purchase to qualify (null if using quantity).

minimumQuantitynumberRequired

The minimum quantity of items in an individual purchase to qualify (null if using subtotal).

oneUsePerCustomerbooleanRequired

Whether or not this discount is single use per customer.

hasExpirationbooleanRequired

Whether or not this discount expires.

expirationDaysnumberRequired

If the previous value is true, this is the quantity, in days, before this discount expires.

typeobjectRequired

This is an internal identifier, leave default.

Default: SIGNUP_DISCOUNTS

namestringRequired

The name (appearance only) of this benefit.

descriptionstringRequired

The description of this benefit (appearance).

collectionIdstringRequired

The Shopify collection ID link to apply this benefit to.

defaultDiscountPercentagenumberRequired

The discount in pricing to apply to the collection.

typeobjectRequired

This is an internal identifier, leave default.

Default: MEMBER_ONLY_PRICING

namestringRequired

The name (appearance only) of this benefit.

collectionIdsstring[]Required

The Shopify collection IDs to apply this benefit to.

startDatestringRequired

The Shopify discount code ID to apply to the collection.

endDatestringRequired

The end date that takes the format: YYYY-MM-DD HH:MM:SS +00:00

Responses

201

Returned upon successful request made to our backend. Requests that return this code may take a small amount of time after successful API return to fully update.

application/json

400

Returned upon a malformed request. Check your API key, URL parameters, and body parameters when this error is returned. Generally, if you see this error, that also means NO action was taken on our backend.

application/json

messagestringRequired

The message associated with the response. Generally, the message only confirms the requested action. In the case of errors, the message will give insight into the source of the error.

dataobjectRequired

The data associated with the response. Data is only returned from errors if the error originates from our backend to give further insight into the nature of the error.

500

Returned for all other errors. Generally these come from our backend. Some multipart functions may execute somewhat and then fail, causing some data to be updated.

application/json

messagestringRequired

The message associated with the response. Generally, the message only confirms the requested action. In the case of errors, the message will give insight into the source of the error.

dataobjectRequired

The data associated with the response. Data is only returned from errors if the error originates from our backend to give further insight into the nature of the error.

patch

/v2.0/admin/benefits/{type}

patch

This endpoint will take a benefit type, segment ID, and any other values in the relevant schema and send a request to our backend to update the benefit with the new information. Keep in mind that, like with the POST method, this is a request against our backend. Thus, the effect will not be immediate.

Path parameters

idstringRequired

The tier segment ID.

typestringRequired

The benefit identification name/type.

Header parameters

X-Inveterate-Api-KeystringRequired

Your private Inveterate API key.

Body

creditAmountnumberRequired

The amount to be awarded upon sign-up.

namestringRequired

The name (appearance only) of this benefit.

daysnumberRequired

The number of days to delay the credit award.

descriptionstringRequired

The description of this benefit (appearance only).

typeobjectRequired

This is an internal identifier, leave default.

Default: SIGNUP_STORE_CREDITS

creditAmountnumberRequired

The amount to be awarded each recurrence.

namestringRequired

The name (appearance only) of this benefit.

descriptionstringRequired

The description of this benefit (appearance only).

frequencynumberRequired

How often (in days) you want to award this credit.

typeobjectRequired

This is an internal identifier, leave default.

Default: SCHEDULED_STORE_CREDITS

internalTitlestringRequired

The internal identifier, leave default.

typeobjectRequired

This is an internal identifier, leave default.

Default: CREDITS_FOR_ORDERS

namestringRequired

The name (appearance only) of this benefit.

descriptionstringRequired

The description of this benefit (appearance only).

enabledbooleanRequired

Whether this benefit is enabled or not.

rulestring · enumRequired

Which credit rule: "PERCENTAGE_BACK_ON_PURCHASE", "EARN_EVERY_ORDER", or "SPEND_AND_EARN".

Possible values:

rewardValuenumberRequired

The amount of credits (or percent) to give as an award.

excludeInveterateMembershipProductsbooleanRequired

Whether or not to include the membership product for credit.

minimumPurchaseAmountnumberRequired

The minimum individual purchase amount to award credit for orders.

maximumRewardValuestringRequired

The discount code to use for this benefit.

allowRefundsbooleanRequired

Whether or not this benefit is displayed on the landing page.

appliesTostring · enumRequired

Which products or collections this benefit applies to: "ALL_PRODUCTS", "SPECIFIC_PRODUCTS", or "SPECIFIC_COLLECTIONS".

Possible values:

applicableTostring[]Required

If appliesTo is either of the latter two values, this is a string array of Shopify Product IDs or Collection IDs (i.e. "gid://shopify/Collection/266717724758").

creditAmountnumberRequired

The amount of credits to award on anniversary.

namestringRequired

The name (appearance only) of this benefit.

descriptionstringRequired

The description of this benefit (appearance only).

typeobjectRequired

This is an internal identifier, leave default.

Default: ANNIVERSARY_CREDITS

creditAmountnumberRequired

The amount of credits to award on referral.

namestringRequired

The name (appearance only) of this benefit.

descriptionstringRequired

The description of this benefit (appearance only).

typeobjectRequired

This is an internal identifier, leave default.

Default: REFERRALS

shippingTypestring · enumRequired

Which shipping type: "DISCOUNT_CODE" or "SCRIPT".

Possible values:

codestringRequired

The name (appearance only) of this benefit.

minRequirementsstring · enumRequired

Which minumum requirements: "ITEM_QUANTITY", "PURCHASE_AMOUNT", or "NONE".

Possible values:

isRatesExcludedbooleanRequired

Whether or not to include purchases with shipping rates over a certain value.

maximumShippingPricenumberRequired

The maximum shipping rate over which shipping is not free (only with previous value true).

minimumQuantitynumberRequired

If minRequirements is "ITEM_QUANTITY", include this field to indicate minimum number of items.

minimumSubtotalnumberRequired

If minRequirements is "PURCHASE_AMOUNT", include this field to indicate the minumum purchase amount.

countryTypestring · enumRequired

Which country type: "ALL" or "SPECIFIC".

Possible values:

countriesstring[]Required

If previous value is "SPECIFIC", this field contains the specific countries in the format: { "label": "United States", "value": "United States" }

typeobjectRequired

This is an internal identifier, leave default.

Default: FREE_SHIPPING

namestringRequired

The name (appearance only) of this benefit.

descriptionstringRequired

The description of this benefit (appearance).

typeobjectRequired

This is an internal identifier, leave default.

Default: DISCOUNTS

namestringRequired

The name (appearance only) of this benefit.

descriptionstringRequired

The description of this benefit (appearance).

discountTypestring · enumRequired

Which discount type: "percentage" or "fixed".

Possible values:

valuenumberRequired

The fixed or percentage award value.

collectionIdsstring[]Required

If using collections, this is a string array of Shopify Collection IDs (i.e. "gid://shopify/Collection/266717724758").

productIdsstring[]Required

If using products, this is a string array of Shopify Product IDs (i.e. "gid://shopify/Product/266717724758").

minimumSubtotalnumberRequired

The minimum subtotal for an individual purchase to qualify (null if using quantity).

minimumQuantitynumberRequired

The minimum quantity of items in an individual purchase to qualify (null if using subtotal).

oneUsePerCustomerbooleanRequired

Whether or not this discount is single use per customer.

hasExpirationbooleanRequired

Whether or not this discount expires.

expirationDaysnumberRequired

If the previous value is true, this is the quantity, in days, before this discount expires.

typeobjectRequired

This is an internal identifier, leave default.

Default: SIGNUP_DISCOUNTS

namestringRequired

The name (appearance only) of this benefit.

descriptionstringRequired

The description of this benefit (appearance).

collectionIdstringRequired

The Shopify collection ID link to apply this benefit to.

defaultDiscountPercentagenumberRequired

The discount in pricing to apply to the collection.

typeobjectRequired

This is an internal identifier, leave default.

Default: MEMBER_ONLY_PRICING

namestringRequired

The name (appearance only) of this benefit.

collectionIdsstring[]Required

The Shopify collection IDs to apply this benefit to.

startDatestringRequired

The Shopify discount code ID to apply to the collection.

endDatestringRequired

The end date that takes the format: YYYY-MM-DD HH:MM:SS +00:00

Responses

201

Returned upon successful request made to our backend. Requests that return this code may take a small amount of time after successful API return to fully update.

application/json

400

application/json

messagestringRequired

The message associated with the response. Generally, the message only confirms the requested action. In the case of errors, the message will give insight into the source of the error.

dataobjectRequired

The data associated with the response. Data is only returned from errors if the error originates from our backend to give further insight into the nature of the error.

500

Returned for all other errors. Generally these come from our backend. Some multipart functions may execute somewhat and then fail, causing some data to be updated.

application/json

messagestringRequired

The message associated with the response. Generally, the message only confirms the requested action. In the case of errors, the message will give insight into the source of the error.

dataobjectRequired

The data associated with the response. Data is only returned from errors if the error originates from our backend to give further insight into the nature of the error.

patch

/v2.0/admin/tiers/{id}/benefits/{type}

Account Widget Frontend API

The goal of the Account Widget Frontend API is to allow developers to programatically interact with the Account Widget. For more general information on the Account Widget, see Merchant Account Widget Documentation.

This is a Shopify Plus only feature and is only supported with the use of Shopify Legacy Customer Accounts.

To view all of the properties and methods that exist in this API, add the following code to your browser console window which will list out all of the available properties and methods:

All of the methods in this API allow for you to use either the async/await pattern or the classic callback pattern. The async/await pattern is always the recommended approach, but the callback pattern is just as viable if necessary. See the following examples:

Properties

config - Provides general Shopify information about the store and the customer (if logged in)
isLoggedIn - Boolean value to show whether customer is logged into widget or not

Methods

Add a Product to a Wishlist

Adds a product to a wishlist. Defaults to adding the product to the main/default wishlist if wishlistId argument is left empty or set to null.

Usage: addToWishlist(productId, wishlistId, callback)

Arguments:

productId[string]: (required) Then numeric Shopify product ID that will be added to the wishlist
wishlistId[string|null]: (optional) The wishlistId of the wishlist the product will be added to - if left empty or set to null will default to the "main/default" wishlist

Response:

data[object|null] - The product and wishlist associated with the request.
error[object|null] - The error the method ran into; null if method finished successfully

For the majority of use cases, we recommend leaving wishlistId blank and letting the system add items to the main/default wishlist.

Get a Customer's Wishlist by ID

Gets the information a wishlist specified by ID.

Usage: getCustomerWishlistById(wishlistId, callback)

Arguments:

wishlistId[string] - (required) The id of the wishlist you would like to get
callback[function|null] - (optional) Function to run after method completes

Response:

data[object|null] - The wishlist data associated with the requested ID
error[object|null] - The error the method ran into; null if method finished successfully

Get All Wishlists for a Customer

Get all of the wishlists for the logged in customer. This includes wishlist metadata plus associated wishlist items.

Usage: getCustomerWishlists(callback)

Arguments:

callback[function|null] - (optional) Function to run after method completes

Response:

data[object|null] - Returns all of the customer's wishlists with both wishlist metadata as well as items lists
error[object|null] - The error the method ran into; null if method finished successfully

Get the ID of the Main/Default Wishlist

Gets the ID of the main/default wishlist. This is just a convenience function if the main/default wishlist ID is needed for anything.

Usage: getDefaultWishlistId(callback)

Arguments:

callback[function|null] - (optional) Function to run after method completes

Response:

data[object|null] - Returns the ID of the main/default wishlist
error[object|null] - The error the method ran into; null if method finished successfully

Get the Items Associated with a Wishlist

Gets only the items associated with a specified wishlist identified by ID.

Usage: getWishlistItems(wishlistId, callback)

Arguments:

wishlistId[string] - (required) The id of the wishlist you would like to get the items from
callback[function|null] - (optional) Function to run after method completes

Response:

data[object|null] - The wishlist items associated with the requested ID
error[object|null] - The error the method ran into; null if method finished successfully

Hides the widget from the customer's view.

Usage: hide(callback)

Arguments:

callback[function|null] - (optional) Function to run after method completes

Response:

data[null] - Always null
error[object|null] - The error the method ran into; null if method finished successfully

Refreshes the contents of the widget. Useful when there are data changes being made outside of the widget but the customer needs to refresh the widget for them to show. This is not a commonly needed method.

Usage: refresh(callback)

Arguments:

callback[function|null] - (optional) Function to run after method completes

Response:

data[null] - Always null
error[object|null] - The error the method ran into; null if method finished successfully

Changes the view displayed in the widget. When called, will also show the widget so there's no need to call the show method either before/after this method.

Usage: setView(viewName, options, callback)

Arguments:

viewName[string] - (required) The name of the view you want to display. See below for full list of supported views.
options[object|null] - (optional) View specific options
callback[function|null] - (optional) Function to run after method completes

Response:

data[object|null] - Information that was used to select the view
error[object|null] - The error the method ran into; null if method finished successfully

Supported view names:

View name

Description

Supported options

Option

Description

Shows the widget to the customer.

Usage: show(callback)

Arguments:

callback[function|null] - (optional) Function to run after method completes

Response:

data[null] - Always null
error[object|null] - The error the method ran into; null if method finished successfully

Toggles the visibility of the widget depending on it's current visibility state.

Usage: toggle(callback)

Arguments:

callback[function|null] - (optional) Function to run after method completes

Response:

data[null] - Always null
error[object|null] - The error the method ran into; null if method finished successfully

Track a Product

Tracks a product view for the "recently viewed" feature. Useful for stores that have quick buy functionality and want a product viewed in quick buy to count as a recently viewed product for the customer.

Usage: trackProduct(productHandle, callback)

Arguments:

productHandle[string] - (required) The unique handle for the product. Usually found in the product page URL.
callback[function|null] - (optional) Function to run after method completes

Response:

data[object|null] - The product handle and a boolean saying whether or not the item was tracked
error[object|null] - The error the method ran into; null if method finished successfully

Inject Section

Allows developers to inject their own custom sections into the 'for you' view of the widget via JavaScript.

Usage: injectSection(location, html, classname, callback)

Arguments:

location[number|string] - (required) The 0-indexed location for the section to be injected. If adding an index, use a number. Also supports the strings start and end to add the section at the beginning or end. Adding an section shifts the index of the sections that come after it. The login block will always display at the top. Using 0 or start will add the section below the login block.
html[string]

Response: No response

Callbacks

For all methods that accept a callback function, we pass 2 arguments to the callback: data and error. If the function completed successfully, error will be null. For certain methods, even when successful, data will be null since there are not data points to return. So if you're just trying to see if a method completed successfully, check the error argument. See the following example of creating and passing a generic callback:

This will log Success: null to the console since the method successfully ran, but there is no data returned to the client for the show method.

Events

We also add events to the window object. This allows your code to react to changes rather than requiring you to setInterval or other methods of waiting for an action to complete.

All events come with a detail property that provides useful information related to the action. See the following example of how to use events:

All events are as follows:

Event name

Description

Detail properties

Dev

Inveterate Dev Docs

hashtagGet Started

API Reference Docs

Public API 2.0 Reference

hashtagWhy Switch?

hashtagAuthentication

hashtagUsing API Key in Requests

hashtagAPI URL

hashtagExample Get Request

hashtagAdmin vs Storefront

Admin

Benefits

Members

Credits

Merchant

Tiers

Benefits

Campaigns

Webhooks

Overview

Topics

customer.joined.paid_tier

hashtagcustomer.joined.paid_tier

hashtagPayload Structure

hashtagPayload Fields

customer.joined.free_tier

hashtagcustomer.joined.free_tier

hashtagPayload Structure

hashtagPayload Fields

customer.joined.free_trial

hashtagcustomer.joined.free_trial

hashtagPayload Structure

hashtagPayload Fields

customer.joined.lifetime_tier

hashtagcustomer.joined.lifetime_tier

hashtagPayload Structure

hashtagPayload Fields

customer.changed_tier

hashtagcustomer.changed_tier

hashtagPayload Structure

hashtagPayload Fields

customer.updated

hashtagcustomer.updated

hashtagPayload Structure

customer.ordered

hashtagcustomer.ordered

hashtagPayload Structure

customer.payment_succeeded

hashtagcustomer.payment_succeeded

hashtagPayload Structure

customer.payment_failed

hashtagcustomer.payment_failed

hashtagPayload Structure

hashtagPayload Fields

customer_billing.attempt.failed

hashtagcustomer_billing.attempt.failed

hashtagPayload Structure

customer.payment_methods.updated

hashtagcustomer.payment_methods.updated

hashtagPayload Structure

customer.credits.updated

hashtagcustomer.credits.updated

hashtagPayload Structure

customer.credits.expired

hashtagcustomer.credits.expired

hashtagPayload Structure

hashtagPayload Fields

customer.cancelled

hashtagcustomer.cancelled

hashtagPayload Structure

hashtagPayload Fields

customer.pending_cancellation

hashtagcustomer.pending_cancellation

hashtagPayload Structure

Storefront

Members

Credits

Redemption

Cancellation

Get Started

Why Switch?

Authentication

Using API Key in Requests

API URL

Example Get Request

Admin vs Storefront

`customer.joined.paid_tier`

Payload Structure

Payload Fields

`customer.joined.free_tier`

Payload Structure

Payload Fields

`customer.joined.free_trial`

Payload Structure

Payload Fields

`customer.joined.lifetime_tier`

Payload Structure

Payload Fields

`customer.changed_tier`

Payload Structure

Payload Fields

`customer.updated`

Payload Structure

`customer.ordered`

Payload Structure

`customer.payment_succeeded`

Payload Structure

`customer.payment_failed`

Payload Structure

Payload Fields

`customer_billing.attempt.failed`

Payload Structure

`customer.payment_methods.updated`

Payload Structure

`customer.credits.updated`

Payload Structure

`customer.credits.expired`

Payload Structure

Payload Fields

`customer.cancelled`

Payload Structure

Payload Fields

`customer.pending_cancellation`

Payload Structure

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

Authentication

Using API Key in Requests

Requirements

Example Get Request

Reference Shortcuts

Endpoints & Methods

Get all campaigns

Endpoints & Methods

Get merchant

Headers

Sign up customer for free tier

Dealing with Slide Out Cart Behavior

What is the Inveterate Storefront code?

The `inveterate` object

Metafields

(Inveterate) Balance

(Inveterate) Next Payment

(Inveterate) Referrals

(Inveterate) Experience Segment

(Inveterate) Payment Amount

(Inveterate) Payment Currency

(Inveterate) Credits Earned

Usage Notes

Why Switch?

Authentication

Using API Key in Requests

API URL

Example Get Request

Admin vs Storefront

Get Started

`customer.joined.paid_tier`

Payload Structure

Payload Fields