Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
The Rest API allows you to build a highly custom paid-membership program on your Shopify storefront.
Find the v2 reference here.
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.
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
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
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.
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.payment_succeeded
customer.payment_failed
customer.payment_methods.updated
customer_billing.attempt.failed
customer.cancellation_requested
customer.confirmed_cancellation
customer.cancelled
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
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 |
---|
Cancellations –
Name | Type | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
---|
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 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.
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
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 id like 6412233234 etc |
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. |
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. |