Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Member accessing and altering endpoints.
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.
Returns a single member for a given merchant. Merchant is pulled from the public API key for security reasons.
The customer ID number which you would like to retrieve.
Your private Inveterate API key.
Returned upon successful direct action to our database. Action is immediate.
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.
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.
Returns all members for a given merchant. Merchant is pulled from the public API key for security reasons.
Pagination is supported by passing limit and lastCustomerId values as
query parameters. You will get a lastCustomerId value in the response
of the previous request, which can be used for the next.
Your private Inveterate API key.
Returned upon successful direct action to our database. Action is immediate.
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.
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.
This endpoint is used to update a member. It takes a member ID and uses your public API key to match the customer to your account. As of now, all fields in the update schema are required, so it is not possible to update a single field at a time.
The customer ID number which you would like to update.
Your private Inveterate API key.
The customer's first name.
The customer's last name.
Internal notes for this customer. Only viewable by the merchant.
The customer's phone number.
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.
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.
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.
Our admin endpoints.
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.
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!
API Keys are private and should not be shared or exposed on the front end.
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.
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.
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.
This endpoint is used to create a free tier member. You can also provide a credit value to add credits to the new members account.
The overrideSpendThreshold parameter allows you to add customers to a spend based tier, and the keepInSpendBasedTier parameter
ensures that the member won't be downgraded if they don't hit the spend minimum.
NOTE: This endpoint will downgrade a customer specified to a lower tier if that is the tier provided to the endpoint!
Your private Inveterate API key.
The customerId to add to the specified free tier.
The signify whether or not the customer was referred. NOTE: NOT to be used to indicate the referring customer.
The segmentId of the tier you want to add this customer to.
Whether or not to override the spend required to add a cutomer to a spend based tier.
Whether or not you want to keep this customer in the spend based tier despite not meeting the spend threshold.
Especially for member creation requests, if you would like to add some credits to the specified customer.
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.
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.
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.
These endpoints only work for merchants with tiers enabled. Access benefits via this set of endpoints.
Get and create credit requests.
Our storefront-authenticated endpoints.
Get, create and delete webhooks. Use these to build third-party integrations.
Get your merchant data. Serves as a good health check for our services and your API key/access.
Generates a security token and places an entry with the token and the callback URL in our backend. The token is used to verify that the request is coming from Inveterate within your app, when the callback URL is triggered. Ensure that you save the token.
The callback URL will be triggered when one of the following events occurs:
`merchant.updated`
`merchant.reinstall`
`customer.created`
`customer.updated`
`customer.credits.updated`
`customer.ordered`
`customer.cancellation_requested`
`customer.confirmed_cancellation`
Your private Inveterate API key.
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.
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.
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.
Deletes a webhook for a given merchant. Merchant is pulled from the public API key for security reasons. The effects of this method are both immediate (data deleted from webhooks database) and eventual (request against backend service to confirm webhook deletion).
Your private Inveterate API key.
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.
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.
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.
Returns all webhooks for a given merchant. Merchant is pulled from the public API key for security reasons.
Your private Inveterate API key.
Returned upon successful direct action to our database. Action is immediate.
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.
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.
Returns all credits for one customer. API key is used to match the customer to your account for security reasons. Ensure that the customer ID is included in the request path.
Pagination is supported by passing limit and lastCreditEntry values as query parameters.
You will get a lastCreditEntry value in the response of the previous request, which can
be used for the next. Ensure that the lastCreditEntry value passed to the server is
encoded.
Your private Inveterate API key.
Returned upon successful direct action to our database. Action is immediate.
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.
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.
This method forwards the credit creation request to our backend. Returns the success status of the request against backend service. Like the other endpoints that make requests against our backend, the changes may not take effect immediately.
Your private Inveterate API key.
The amount of credits to add to the customer's account.
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.
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.
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.
Create a cancellation request for a member.
Get credits for a specific member.
Member get. Includes more member actions in sub-directories.
These endpoints only work for merchants with tiers enabled. Access benefits via this set of endpoints.
Create a credit redemption request for a member.
Returns all internal merchant information associated with the API key.
Your private Inveterate API key.
Returned upon successful direct action to our database. Action is immediate.
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.
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.
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.
A list of our data schemas.
CreateMemberDto
ResponseBodyDto
UpdateMemberDto
CreateCreditDto
SignupStoreCreditsDto
RecurringStoreCreditsDto
CreditsforOrdersDto
AnniversaryCreditsDto
StoreCreditsforReferralDto
FreeShippingDto
MemberOnlyDiscountDto
SignupDiscountDto
MemberPricingDto
EarlyAccessCampaignDto
WebhookDto
The Rest API allows you to build a highly custom paid-membership program on your Shopify storefront.
Find the v2 reference .
API Keys are private and should not be shared or exposed on the front end.
Include your API key as an X-Inveterate-Api-Key header on all API endpoint requests.
All API requests utilize https://public.inveterateapi.com/ as the base URL.
This method forwards the cancellation creation request to our backend. Returns the success status of the request against backend service. Like the other endpoints that make requests against our backend, the changes may not take effect immediately.
The customer ID number.
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.
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.
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.
Returns all credits for one customer. API key is used to match the customer to your account for security reasons. Ensure that the customer ID is included in the request path.
The customer ID number.
Your private Inveterate API key.
Returned upon successful direct action to our database. Action is immediate.
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.
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.
Returns all member data for a given member that is a part of your store. Merchant is pulled from the public API key for security reasons. Make sure to include the customer ID in the request path.
The customer ID number.
Your private Inveterate API key.
Returned upon successful direct action to our database. Action is immediate.
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.
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.
Forwards a redemption request to the Inveterate backend. Returns the success status of the request against the backend service. Like the other endpoints that make requests against our backend, the changes may not take effect immediately.
The customer ID number.
Your private Inveterate API key.
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.
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.
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.
merchantId*
string
customerId*
string
accountState*
string
anonymized*
boolean
contractId*
number
createdAt*
string
credit*
number
creditsEarned*
number
email*
string
firstName*
string
joinedAt*
string
lastCreditRedemptionAt*
string
lastName*
string
lastPurchaseAt*
string
notes*
string
numberOfCreditRedemptions*
number
orderCount*
number
orderIds*
[number]
paymentId*
number
phoneNumber*
string
referrals*
number
referredBy*
number
revenue*
number
status*
string
totalSpend*
number
updatedAt*
string
message*
string
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.
data*
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.
firstName*
string
The customer's first name.
lastName*
string
The customer's last name.
notes*
string
Internal notes for this customer. Only viewable by the merchant.
phoneNumber*
string
The customer's phone number.
amount*
number minimum: 1
The amount of credits to add to the customer's account.
creditAmount*
number
The amount to be awarded upon sign-up.
name*
string
The name (appearance only) of this benefit.
days*
number
The number of days to delay the credit award.
description*
string
The description of this benefit (appearance only).
type*
This is an internal identifier, leave default.
creditAmount*
number
The amount to be awarded each recurrence.
name*
string
The name (appearance only) of this benefit.
description*
string
The description of this benefit (appearance only).
frequency*
number
How often (in days) you want to award this credit.
type*
This is an internal identifier, leave default.
internalTitle*
string
The internal identifier, leave default.
type*
This is an internal identifier, leave default.
description:
This is an internal identifier, leave default.
name*
string
The name (appearance only) of this benefit.
description*
string
The description of this benefit (appearance only).
enabled*
boolean
Whether this benefit is enabled or not.
rule*
string
Which credit rule: "PERCENTAGE_BACK_ON_PURCHASE", "EARN_EVERY_ORDER", or "SPEND_AND_EARN".
Enum: [ PERCENTAGE_BACK_ON_PURCHASE, EARN_EVERY_ORDER, SPEND_AND_EARN ]
rewardValue*
number
The amount of credits (or percent) to give as an award.
excludeInveterateMembershipProducts*
boolean
Whether or not to include the membership product for credit.
minimumPurchaseAmount*
number
The minimum individual purchase amount to award credit for orders.
maximumRewardValue*
string
The discount code to use for this benefit.
allowRefunds*
boolean
Whether or not this benefit is displayed on the landing page.
appliesTo*
string
Which products or collections this benefit applies to: "ALL_PRODUCTS", "SPECIFIC_PRODUCTS", or "SPECIFIC_COLLECTIONS".
Enum: [ ALL_PRODUCTS, SPECIFIC_PRODUCTS, SPECIFIC_COLLECTIONS ]
applicableTo*
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").
string]
creditAmount*
number
The amount of credits to award on anniversary.
name*
string
The name (appearance only) of this benefit.
description*
string
The description of this benefit (appearance only).
type*
This is an internal identifier, leave default.
creditAmount*
number
The amount of credits to award on referral.
name*
string
The name (appearance only) of this benefit.
description*
string
The description of this benefit (appearance only).
type*
This is an internal identifier, leave default.
shippingType*
string
Which shipping type: "DISCOUNT_CODE" or "SCRIPT".
Enum: [ DISCOUNT_CODE, SCRIPT ]
code*
string
The name (appearance only) of this benefit.
minRequirements*
string
Which minumum requirements: "ITEM_QUANTITY", "PURCHASE_AMOUNT", or "NONE".
Enum: [ ITEM_QUANTITY, PURCHASE_AMOUNT, NONE ]
isRatesExcluded*
boolean
Whether or not to include purchases with shipping rates over a certain value.
maximumShippingPrice*
number
The maximum shipping rate over which shipping is not free (only with previous value true).
minimumQuantity*
number
If minRequirements is "ITEM_QUANTITY", include this field to indicate minimum number of items.
minimumSubtotal*
number
If minRequirements is "PURCHASE_AMOUNT", include this field to indicate the minumum purchase amount.
countryType*
string
Which country type: "ALL" or "SPECIFIC".
Enum: [ ALL, SPECIFIC ]
countries*
If previous value is "SPECIFIC", this field contains the specific countries in the format: { "label": "United States", "value": "United States" }
type*
This is an internal identifier, leave default.
description:
This is an internal identifier, leave default.
name*
string
The name (appearance only) of this benefit.
description*
string
The description of this benefit (appearance).
type*
This is an internal identifier, leave default.
description:
This is an internal identifier, leave default.
name*
string
The name (appearance only) of this benefit.
description*
string
The description of this benefit (appearance).
discountType*
string
Which discount type: "percentage" or "fixed".
Enum: [ percentage, fixed ]
value*
number
The fixed or percentage award value.
collectionIds*
If using collections, this is a string array of Shopify Collection IDs (i.e. "gid://shopify/Collection/266717724758").
string
productIds*
If using products, this is a string array of Shopify Product IDs (i.e. "gid://shopify/Product/266717724758").
string
minimumSubtotal*
number
The minimum subtotal for an individual purchase to qualify (null if using quantity).
minimumQuantity*
number
The minimum quantity of items in an individual purchase to qualify (null if using subtotal).
oneUsePerCustomer*
boolean
Whether or not this discount is single use per customer.
hasExpiration*
boolean
Whether or not this discount expires.
expirationDays*
number
If the previous value is true, this is the quantity, in days, before this discount expires.
type*
This is an internal identifier, leave default.
name*
string
The name (appearance only) of this benefit.
description*
string
The description of this benefit (appearance).
collectionId*
string
The Shopify collection ID link to apply this benefit to.
defaultDiscountPercentage*
number
The discount in pricing to apply to the collection.
type*
This is an internal identifier, leave default.
name*
string
The name (appearance only) of this benefit.
collectionIds*
The Shopify collection IDs to apply this benefit to.
startDate*
string
The Shopify discount code ID to apply to the collection.
endDate*
string
The end date that takes the format: YYYY-MM-DD HH:MM:SS +00:00
merchantId*
string
The ID of the merchant that owns this webhook.
id*
string
The ID of the webhook.
createdByApp*
string
The entity that is requesting the webhook creation.
dateCreated*
string
The date the webhook was created.
dateUpdated*
string
The date the webhook was last updated.
name*
string
The name associated with the callback URL.
callbackUrl*
string
The callback URL that will be called when one of the webhooks is triggered.
token*
string
The token associated with the webhook.
This is an advanced guide.
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:
Add the membership to cart (if it's not already in cart)
Update add to cart buttons on the page with a success state
Refresh the page with ?cart-updated=true added to the URL
Once the page reloads, it uses the URL param from step #3 to display a success message to the customer
Again, we have this functionality in place to make sure we can provide a great user experience for all merchant's customers.
In instances where the theme has slide out cart behavior and our above solution is interfering with that behavior, we provide the option to disable the steps #3 and #4 from above so that you can continue to maintain the user experience that's unique to your brand.
There are 2 ways to do this:
Add the following HTML script tag within the head of your theme.liquid file and this will disable steps #3 and #4 behavior on the landing page:
Our landing page will automatically pick up that object and disable the functionality.
We've also added a utility function that's only on the landing page to allow you to update the addToCartRedirect setting after our code has already loaded on the page. To use this method, you'll want to first make sure that window.inveterate.landing.updateLPSettings exists by using something like a setInterval or a while loop and then from there you can use that to update settings:
This will run 100 times and will run every 500ms. Once it either finds window.inveterate.landing.updateLPSettings or if the counter reaches 100, it will end the loop. The reason for the counter is to prevent this from running forever and having an impact on performance. If it doesn't find it after 100, it probably isn't loading on the page.
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:
GET https://public.inveterateapi.com/campaigns
Returns a single benefit for a given merchant. Merchant is pulled from the public API key for security reasons. The benefit ID is the type of benefit. For a list of possible benefit types, see the default values in the schema list.
The benefit ID name/type.
Your private Inveterate API key.
Returned upon successful direct action to our database. Action is immediate.
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.
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.
Returns all benefits for a given merchant. Merchant is pulled from the public API key for security reasons.
Your private Inveterate API key.
Returned upon successful direct action to our database. Action is immediate.
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.
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.
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.
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.
This filed displays the next payment date for the customer's membership. It is stored in ISO format.
This field displays a list of all completed referrals made by the member.
This field displays the amount the member has agreed to paying for the membership.
A customer in the Inveterate system is anyone that has purchased an Inveterate subscription product from this merchant's store.
A customer is represented as an object with the following structure:
GET https://public.inveterateapi.com/customers/{customerId}
Gets a single customer.
GET https://api.inveterate.com/2022-01/customers
Optionally using the limit and lastCustomerId query string parameters, you can "paginate" through the customer records returned.
For the first page, just add the limit parameter. The response for this will include the lastCustomerId, which needs to be added as a query string parameter to the request for page 2.
POST https://public.inveterateapi.com/customers/{customerId}/cancel
Step 1 of the customer's subscription cancellation process. A successful request to this endpoint submits a customer cancellation request. Customer will receive an email with a link to confirm cancellation of their subscription.
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.
Merchant events
merchant.updated
merchant.reinstall
Customer events
Account
customer.created
customer.updated
customer.credits.updated
Orders and Payments
customer.ordered
customer.resubscribed
customer.payment_succeeded
customer.payment_failed
customer.payment_methods.updated
customer_billing.attempt.failed
Cancellations – more details below.
customer.cancellation_requested
customer.confirmed_cancellation
customer.cancelled
customer.merchant_cancel
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.
POST https://public.inveterateapi.com/webhooks
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 https://public.inveterateapi.com/webhooks
Get all webhook subscribers associated with this X-Inveterate-Api-Key value.
DELETE https://public.inveterateapi.com/webhooks
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.
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: ACTIVE -> CANCELLED. Then customer.cancelled event is triggered.
if cancellation policy is end of billing cycle, customer status: ACTIVE -> PENDING_CANCELLATION . Then on the same day or the next day, customer gets cancelled and customer.cancelled event is triggered.
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
If user confirms e-mail
Event trigger: customer.confirmed_cancellation
Customer gets cancelled and loses access to their benefits
status: ACTIVE -> CANCELLED
Email gets sent: Confirmed cancellation
Event trigger: customer.cancelled
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
If user confirms e-mail
Event trigger: customer.confirmed_cancellation
Customer update: status from ACTIVE -> PENDING_CANCELLATION
Email gets sent: Confirmed cancellation
When customer's billing cycle ends
Customer gets cancelled and loses access to their benefits
status from PENDING_CANCELLATION -> CANCELLED
Event trigger: customer.cancelled
This page covers api endpoints that allow merchants add customers to their free tier membership
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:
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
| Name | Type | Description |
|---|---|---|
| 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:
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
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 is invalid.
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).
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.
On your storefront, we automatically add and update 2 files:
inveterate-theme.liquid
inveterate-checkout.liquid
See Snippets for more information about this.
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.
inveterate objectAll 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.
This section contains information about how to customize your storefront UI.
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.
| Name | Type | Description |
|---|---|---|
| Name | Type | Description |
|---|---|---|
| Name | Type | Description |
|---|---|---|
| Name | Type | Description |
|---|---|---|
| Name | Type | Description |
|---|---|---|
| Name | Type | Description |
|---|---|---|
| Name | Type | Description |
|---|---|---|
| Name | Type | Description |
|---|---|---|
| Name | Type | Description |
|---|---|---|
| Name | Type | Description |
|---|---|---|
| Name | Type | Description |
|---|---|---|
| Name | Type | Description |
|---|---|---|
| Name | Type | Description |
|---|---|---|
| Name | Type | Description |
|---|---|---|
customerId*
String
The Shopify ID for a specific customer.
X-Inveterate-Api-Key*
String
Required to access all protected endpoints on this API. Obtained from merchant's Inveterate dashboard.
limit
Int
Amount of customers to return per request. Default is no limit. Max is 100.
lastCustomerId
Int
Used to determine the index offset of which customers to return.
X-Inveterate-Api-Key*
String
Required to access all protected endpoints on this API. Obtained from merchant's Inveterate dashboard.
merchantId*
String
X-Inveterate-Api-Key*
String
Required to access all protected endpoints on this API. Obtained from merchant's Inveterate dashboard.
merchantId*
String
merchantId is the first part of the shop domain. For example if the shop domain is inveterate-demo.myshopify.com, Merchant ID is inveterate-demo
customerId*
String
Shopify legacy customer IDs with numerical values such as "6412233234" are supported. GraphQL IDs such as "gid://shopify/Customer/6412233234" are not supported
segmentId
String
Optionally provided to specify which free tier the customer is to be enrolled into. If absent, the first free tier to be created is assumed.
customerId*
Number
The customer ID which you intend to pull the data of.
X-Inveterate-Api-Key*
String
Required to access all protected endpoints on this API. Obtained from merchant's Inveterate dashboard.
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.
X-Inveterate-Api-Key
String
Required to access all protected endpoints on this API. Obtained from merchant's Inveterate dashboard.
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.
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.
X-Inveterate-Api-Key*
String
Required to access all protected endpoints on this API. Obtained from merchant's Inveterate dashboard.
callbackUrl*
String
The URL which will receive a POST request whenever an event should be passed from Inveterate to a subscriber.
name
String
Descriptive name to help identify the subscriber.
X-Inveterate-Api-Key*
String
Required to access all protected endpoints on this API. Obtained from merchant's Inveterate dashboard.
X-Inveterate-Api-Key*
String
Required to access all protected endpoints on this API. Obtained from merchant's Inveterate dashboard.
id*
String
The subscriber id.
This is an advanced guide.
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.
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 Shopify's Documentation as well for more information on selling plans.
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.
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:
Forwards a request to our backend to delete a given benefit. Benefit will be identified by the benefit type field. For a list of all benefit types, take a look at each schema's default type value.
This is STRICTLY for deleting CUSTOM benefits. You cannot delete default benefits
via the Public API. Use your admin dashboard to disable default benefits.
The benefit identification name/type.
Your private Inveterate API key.
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.
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.
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.
Returns all tiers/segments for a given merchant. Merchant is pulled from the public API key for security reasons.
Whether or not to include benefits in the response.
Your private Inveterate API key.
Returned upon successful direct action to our database. Action is immediate.
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.
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.
Returns a single tier/segment for a given merchant. Merchant is pulled from the public API key for security reasons.
The tier segment ID.
Whether or not to include benefits in the response.
Your private Inveterate API key.
Returned upon successful direct action to our database. Action is immediate.
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.
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.
This endpoint will return all benefits for a merchant under a given tier. It will return an array of benefits. Each benefit will have a type field that will identify the type of benefit.
The tier segment ID.
Your private Inveterate API key.
Returned upon successful direct action to our database. Action is immediate.
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.
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.
This endpoint will return one specific benefit given a benefit type and segment ID. Note that the benefit type is a string character. For a list of all benefit types, look at the default type value in each schema.
The tier segment ID.
The benefit type.
Your private Inveterate API key.
Returned upon successful direct action to our database. Action is immediate.
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.
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.
Returns all campaigns belonging to a specific Tier identified by its segmentId
The tier segment ID.
Your private Inveterate API key.
Returned upon successful direct action to our database. Action is immediate.
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.
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.
Returns a single tier/segment for a given merchant and customer. Merchant is pulled from the public API key for security reasons.
The customer ID.
Whether or not to include benefits in the response.
Your private Inveterate API key.
Returned upon successful direct action to our database. Action is immediate.
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.
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.
This endpoint will return all benefits for a merchant under a given tier. It will return an array of benefits. Each benefit will have a type field that will identify the type of benefit.
The customer ID.
Your private Inveterate API key.
Returned upon successful direct action to our database. Action is immediate.
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.
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.
Returns all campaigns belonging to the Tier the customer belongs to (customer identified with customerId parameter)
The customer ID.
Your private Inveterate API key.
Returned upon successful direct action to our database. Action is immediate.
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.
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.
This endpoint will return one specific benefit given a benefit type. Note that the benefit type is a string character. For a list of all benefit types, look at the default type value in each schema.
The benefit type.
Your private Inveterate API key.
Returned upon successful direct action to our database. Action is immediate.
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.
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.
This endpoint will return all benefits for a merchant. It will return
an array of benefits. Each benefit will have a type field that will
identify the type of benefit.
Your private Inveterate API key.
Returned upon successful direct action to our database. Action is immediate.
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.
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.
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.
The benefit identification name/type.
Your private Inveterate API key.
The amount to be awarded upon sign-up.
The name (appearance only) of this benefit.
The number of days to delay the credit award.
The description of this benefit (appearance only).
This is an internal identifier, leave default.
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.
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.
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.
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.
The tier segment ID.
The benefit identification name/type.
Your private Inveterate API key.
The amount to be awarded upon sign-up.
The name (appearance only) of this benefit.
The number of days to delay the credit award.
The description of this benefit (appearance only).
This is an internal identifier, leave default.
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.
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.
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.