EZ Loyalty API - Frequently Asked Questions

General Questions

What is the EZ Loyalty API?

The EZ Loyalty API allows developers to interact with the EZ Loyalty platform. It provides endpoints for managing users, handling rewards, and accessing various features of the platform.

Which environments are available for the API?

The API is available in both test and production environments:

• Test: https://api.test.myezrewards.com/{version}/{endpoint}
• Production: https://api.myezrewards.com/{version}/{endpoint}

What versions of the API are currently available?

The current version of the API is Version 2 (v2), which uses JSON-based requests and RESTful endpoints. Version 1 (v1) is legacy and is not part of the public API.

Is there API documentation available?

Yes, Swagger documentation is available at:

• Test: https://api.test.myezrewards.com/swagger/index.html?urls.primaryName=v2
• Production: https://api.myezrewards.com/swagger/index.html?urls.primaryName=v2

Authentication Questions

How do I authenticate with the API?

Authentication is a three-step process:

1. Obtain an API key from EZ Loyalty
2. Exchange this API key for a Bearer token by calling GET /v2/GetAuthToken with the API key in the ApiKey header
3. Include the Bearer token in the Authorization header for all subsequent requests

How long are Bearer tokens valid?

Bearer tokens have a lifespan of 5 minutes before they expire. You'll need to generate a new token after expiration.

What happens if I use an invalid or expired token?

Endpoints will return a 401 status code if the API key or Bearer token provided is missing, invalid, or expired.

How do I handle token expiration in my application?

You should implement token refresh logic in your application. When you receive a 401 error, your application should generate a new token using the API key and retry the request.

User Management Questions

How do I create a new user?

In v2, you can create a new user by sending a POST request to /v2/users with the required JSON payload containing user details like email address, name, and level.

What user levels are available?

The available user levels are:

• Basic
• Basic Plus
• Premium
• Premium Plus

How do I update a user's information?

In v2, you can update a user's information by sending a PATCH request to /v2/users/{identifier} (or to /v2/users, identifying the user by email address or partner member ID) with the updated user details in JSON format.

How do I cancel a user's subscription?

To cancel a user's subscription, send a PATCH request to /v2/users/{identifier}/cancel where identifier is the user's unique ID. The endpoint will return a 200 status code on successful cancellation.

What's the difference between renewing and extending a user subscription?

• Renewing: Send a PATCH request to /v2/users/renew with either the user's email address or partner member ID to renew a subscription for one year from the current date.
• Extending: Send a PATCH request to /v2/users/{identifier}/renew to extend a subscription to a specific date. You can optionally include a RenewDate, or it will default to one year from now.

How do I look up a user?

In v2, there are multiple ways to look up a user:

1. By email or partner member ID: GET /v2/users?EmailAddress={email}&memberId={id}
2. By user identifier: GET /v2/users/{identifier}
3. By level: GET /v2/users/{level}/level

What is a user identifier and how do I get it?

A user identifier is a unique numeric ID assigned to each user by the EZ Loyalty system. You can obtain it by:

1. Looking up a user by email or partner member ID
2. Checking the response when creating a new user
3. It's included in most API responses that return user information

What are Org Unit Levels and how do I use them?

Org Unit Levels allow you to categorize users into subgroups of your organization. They're specified as an array of strings when creating or managing users and are only needed if you want to subcategorize your members.

What user statuses might I encounter?

User statuses typically include:

• Active: User has a valid subscription
• Inactive: User is not currently active
• Cancelled: User's subscription has been cancelled

Response Handling

What format are API responses in?

API responses in v2 are in JSON format. Successful responses include data about the operation performed, while error responses include details about what went wrong.

What information is included in user lookup responses?

User lookup responses include:

• identifier: The user's unique ID
• joinDate: When the user joined
• renewalDate: When the user's subscription renews
• loginUrl: URL for the user to access their account
• hubLoginUrl: URL for the user to access their account via the hub
• level: The user's subscription level
• status: Current status of the account
• firstName/lastName: User's name
• emailAddress: User's email address
• orgUnits: The user's org units (if any)

Responses to creating a user also include externalMemberId, your identifier for this user.

What is the loginUrl in the API responses?

The loginUrl is a personalized URL that allows the user to log into the EZ Loyalty rewards platform directly. This URL contains an authentication token (iframe parameter) and should be provided to the user to access their rewards.

Technical Questions

What protocol is used for API communication?

The API requires TLS 1.2 or higher. Less secure versions of TLS are not supported, and calls made over plain HTTP will fail.

What HTTP status codes might I encounter?

Common status codes include:

• 200: Successful operation
• 400: Invalid request or payload
• 401: Unauthorized (invalid or missing authentication)
• 404: Resource not found
• 500: Server error

Each endpoint documentation specifies which status codes to expect for that particular operation.

What countries are supported?

The API supports most countries worldwide. You can specify a country using its name, two-letter code or three-letter ISO code (case insensitive). Examples include: USA, GBR, CAN, DEU, FRA, JPN, AUS and IND. For a complete list of supported countries and their codes, please refer to our Country List documentation.

Can I test the API before using it in production?

Yes, use the test environment (https://api.test.myezrewards.com) to test your integration before moving to production.

Troubleshooting

My API requests are failing with a 401 error. What should I do?

Check that:

1. You're using a valid API key
2. Your Bearer token hasn't expired (they only last 5 minutes)
3. You're including the Authorization header correctly with the format Bearer {token}

I'm getting a 404 error when looking up a user. What could be wrong?

This typically means the user doesn't exist in the system. Double-check:

1. You're using the correct identifier, email address, or partner member ID
2. The user hasn't been deleted or removed from the system
3. You're using the correct environment (test vs. production)

How do I report issues with the API?

Contact EZ Loyalty support with details about the issue you're experiencing, including request details and any error responses received.