FAQ

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?

There are two versions of the API:

• Version 1 (v1): The original API with form-based requests
• Version 2 (v2): The newer API with JSON-based requests and RESTful endpoints

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

What's the main difference between v1 and v2 of the API?

Version 1 uses form-based requests with a single endpoint (/members) and differentiates operations using a Type parameter. Version 2 follows RESTful principles with distinct endpoints for different operations and uses JSON for request/response payloads.

Authentication Questions

How do I authenticate with the API?

Authentication is a two-step process:

1. Obtain an API key from EZ Loyalty
2. Exchange this API key for a Bearer token by calling the /v2/GetAuthToken endpoint
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} 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/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 in UTC format, 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}&PartnerMemberId={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
• Cancelled: User's subscription has been cancelled
• Expired: User's subscription has expired

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
• loginUrl: URL for the user to access their account
• level: The user's subscription level
• status: Current status of the account
• firstName/lastName: User's name
• emailAddress: User's email address
• country: User's country
• partnerMemberId: 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
• 201: Resource successfully created
• 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 countries using their three-digit ISO country codes. Examples include: USA (840), GBR (826), CAN (124), DEU (276), FRA (250), JPN (392), AUS (036), and IND (356). 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.