# Loyalty API The Loyalty API powers membership, credits, tiers, and benefits for your storefront. It exposes two families of endpoints: **Admin** endpoints for managing members, benefits, tiers, merchant settings, and webhooks server-to-server; and **Storefront** endpoints for member-facing experiences such as authentication, viewing credits, and redemptions. Authenticate every request with your private API key in the `X-Inveterate-Api-Key` header (see the security scheme below). The same key authenticates both Admin and Storefront endpoints. Version: 2.0.0 ## Servers ``` https://public.inveterateapi.com ``` ## Security ### api_key Your private Inveterate API key, sent on every request. The same key authenticates both Admin and Storefront endpoints. API keys are private and should never be exposed in front-end code. Type: apiKey In: header Name: X-Inveterate-Api-Key ## Download OpenAPI description [Loyalty API](https://docs.useonward.com/_bundle/apis/loyalty.yaml) ## Members Server-to-server Members endpoints, authenticated with your private API key. ### List members - [GET /v2.0/admin/members](https://docs.useonward.com/apis/loyalty/admin-members/get_admin_members.md): 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. ### Create a free-tier member - [POST /v2.0/admin/members](https://docs.useonward.com/apis/loyalty/admin-members/create_admin_members.md): 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! ### Get a member - [GET /v2.0/admin/members/{id}](https://docs.useonward.com/apis/loyalty/admin-members/get_admin_members_byid.md): Returns a single member for a given merchant. Merchant is pulled from the public API key for security reasons. ### Update a member - [PATCH /v2.0/admin/members/{id}](https://docs.useonward.com/apis/loyalty/admin-members/update_admin_members_byid.md): 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. ## Credits Server-to-server Credits endpoints, authenticated with your private API key. ### List a member's credits - [GET /v2.0/admin/members/{id}/credits](https://docs.useonward.com/apis/loyalty/admin-credits/get_admin_members_byid_credits.md): 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. ### Issue credits to a member - [POST /v2.0/admin/members/{id}/credits](https://docs.useonward.com/apis/loyalty/admin-credits/create_admin_members_byid_credits.md): 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. ## Cancellation Server-to-server Cancellation endpoints, authenticated with your private API key. ### Request a membership cancellation - [POST /v2.0/admin/members/{id}/cancellation](https://docs.useonward.com/apis/loyalty/admin-cancellation/create_admin_members_byid_cancellation.md) ## Reactivation Server-to-server Reactivation endpoints, authenticated with your private API key. ### Reactivate a membership - [POST /v2.0/admin/members/{id}/reactivation](https://docs.useonward.com/apis/loyalty/admin-reactivation/create_admin_members_byid_reactivation.md) ## Tiers Server-to-server Tiers endpoints, authenticated with your private API key. ### Get a member's periodic spend - [GET /v2.0/admin/members/{id}/sbt](https://docs.useonward.com/apis/loyalty/admin-tiers/get_admin_members_byid_sbt.md): Returns a single customers periodic spend. Includes monthly, quarterly, semi-annual, annual, and all-time spend. If the data field in the return body is undefined, the customer has no eligible SBT spend history (or the customer does not exist). You can use this endpoint to track a customers progress towards the next tier. ### List tiers - [GET /v2.0/admin/tiers](https://docs.useonward.com/apis/loyalty/admin-tiers/get_admin_tiers.md): Returns all tiers/segments for a given merchant. Merchant is pulled from the public API key for security reasons. ### Get a tier - [GET /v2.0/admin/tiers/{id}](https://docs.useonward.com/apis/loyalty/admin-tiers/get_admin_tiers_byid.md): Returns a single tier/segment for a given merchant. Merchant is pulled from the public API key for security reasons. ### List a tier's benefits - [GET /v2.0/admin/tiers/{id}/benefits](https://docs.useonward.com/apis/loyalty/admin-tiers/get_admin_tiers_byid_benefits.md): 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. ### Get a tier's benefit - [GET /v2.0/admin/tiers/{id}/benefits/{type}](https://docs.useonward.com/apis/loyalty/admin-tiers/get_admin_tiers_byid_benefits_bytype.md): 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. ### Update a tier's benefit - [PATCH /v2.0/admin/tiers/{id}/benefits/{type}](https://docs.useonward.com/apis/loyalty/admin-tiers/update_admin_tiers_byid_benefits_bytype.md): 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. ### List a tier's campaigns - [GET /v2.0/admin/tiers/{id}/campaigns](https://docs.useonward.com/apis/loyalty/admin-tiers/get_admin_tiers_byid_campaigns.md): Returns all campaigns belonging to a specific Tier identified by its segmentId ## Change Tier Server-to-server Change Tier endpoints, authenticated with your private API key. ### Change a member's tier - [POST /v2.0/admin/members/{id}/change-tier](https://docs.useonward.com/apis/loyalty/admin-change-tier/create_admin_members_byid_changetier.md): This endpoint allows merchants to upgrade or downgrade a customer by specifying a new tierId. ## Benefits Server-to-server Benefits endpoints, authenticated with your private API key. ### List benefits - [GET /v2.0/admin/benefits](https://docs.useonward.com/apis/loyalty/admin-benefits/get_admin_benefits.md): 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. ### Get a benefit - [GET /v2.0/admin/benefits/{type}](https://docs.useonward.com/apis/loyalty/admin-benefits/get_admin_benefits_bytype.md): 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. ### Update a benefit - [PATCH /v2.0/admin/benefits/{type}](https://docs.useonward.com/apis/loyalty/admin-benefits/update_admin_benefits_bytype.md): 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. ## Merchant Server-to-server Merchant endpoints, authenticated with your private API key. ### Get merchant settings - [GET /v2.0/admin/merchant](https://docs.useonward.com/apis/loyalty/admin-merchant/get_admin_merchant.md): Returns all internal merchant information associated with the API key. ### Update merchant settings - [PATCH /v2.0/admin/merchant](https://docs.useonward.com/apis/loyalty/admin-merchant/update_admin_merchant.md): Updates specific merchant settings, based on the provided fields. Fields not provided will not be updated. ## Webhooks Server-to-server Webhooks endpoints, authenticated with your private API key. ### Register a webhook - [POST /v2.0/admin/webhooks](https://docs.useonward.com/apis/loyalty/admin-webhooks/create_admin_webhooks.md): 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 ### List webhooks - [GET /v2.0/admin/webhooks](https://docs.useonward.com/apis/loyalty/admin-webhooks/get_admin_webhooks.md): Returns all webhooks for a given merchant. Merchant is pulled from the public API key for security reasons. ### Delete a webhook - [DELETE /v2.0/admin/webhooks](https://docs.useonward.com/apis/loyalty/admin-webhooks/delete_admin_webhooks.md): 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). ### Create a webhook subscription - [POST /v2.0/admin/webhook-subscriptions](https://docs.useonward.com/apis/loyalty/admin-webhooks/create_admin_webhooksubscriptions.md): Creates a new webhook subscription for the merchant ### Delete a webhook subscription - [DELETE /v2.0/admin/webhook-subscriptions](https://docs.useonward.com/apis/loyalty/admin-webhooks/delete_admin_webhooksubscriptions.md): Removes an existing webhook subscription ### Update a webhook subscription - [PUT /v2.0/admin/webhook-subscriptions](https://docs.useonward.com/apis/loyalty/admin-webhooks/update_admin_webhooksubscriptions.md): Updates an existing webhook subscription configuration ### List webhook subscriptions - [GET /v2.0/admin/webhook-subscriptions](https://docs.useonward.com/apis/loyalty/admin-webhooks/get_admin_webhooksubscriptions.md): Returns all webhook subscriptions for the merchant ## Authentication Member-facing Authentication endpoints for your storefront. ### Authenticate a member - [POST /v2.0/storefront/auth](https://docs.useonward.com/apis/loyalty/storefront-authentication/create_storefront_auth.md): Authenticates a user and returns a JWT token. This token is used to authenticate the user for all other storefront requests. JWTs expire after 2 hours. ## Members Member-facing Members endpoints for your storefront. ### Get a member - [GET /v2.0/storefront/members/{id}](https://docs.useonward.com/apis/loyalty/storefront-members/get_storefront_members_byid.md): 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. ## Credits Member-facing Credits endpoints for your storefront. ### List a member's credits - [GET /v2.0/storefront/members/{id}/credits](https://docs.useonward.com/apis/loyalty/storefront-credits/get_storefront_members_byid_credits.md): 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. ## Redemption Member-facing Redemption endpoints for your storefront. ### Redeem credits - [POST /v2.0/storefront/members/{id}/credits/redemption](https://docs.useonward.com/apis/loyalty/storefront-redemption/create_storefront_members_byid_credits_redemption.md): 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. ## Cancellation Member-facing Cancellation endpoints for your storefront. ### Request a membership cancellation - [POST /v2.0/storefront/members/{id}/cancellation](https://docs.useonward.com/apis/loyalty/storefront-cancellation/create_storefront_members_byid_cancellation.md): 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. ## Payment Method Member-facing Payment Method endpoints for your storefront. ### Update a member's payment method - [PATCH /v2.0/storefront/members/{id}/payment-method](https://docs.useonward.com/apis/loyalty/storefront-payment-method/update_storefront_members_byid_paymentmethod.md) ## Benefits Member-facing Benefits endpoints for your storefront. ### List benefits - [GET /v2.0/storefront/benefits](https://docs.useonward.com/apis/loyalty/storefront-benefits/get_storefront_benefits.md): Returns all benefits for a given merchant. Merchant is pulled from the public API key for security reasons. ### Get a benefit - [GET /v2.0/storefront/benefits/{id}](https://docs.useonward.com/apis/loyalty/storefront-benefits/get_storefront_benefits_byid.md): 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. ## Tiers Member-facing Tiers endpoints for your storefront. ### Get a tier - [GET /v2.0/storefront/tiers/{id}](https://docs.useonward.com/apis/loyalty/storefront-tiers/get_storefront_tiers_byid.md): Returns a single tier/segment for a given merchant and customer. Merchant is pulled from the public API key for security reasons. ### List a tier's benefits - [GET /v2.0/storefront/tiers/{id}/benefits](https://docs.useonward.com/apis/loyalty/storefront-tiers/get_storefront_tiers_byid_benefits.md): 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. ### List a tier's campaigns - [GET /v2.0/storefront/tiers/{id}/campaigns](https://docs.useonward.com/apis/loyalty/storefront-tiers/get_storefront_tiers_byid_campaigns.md): Returns all campaigns belonging to the Tier the customer belongs to (customer identified with customerId parameter)