Every API request must include your API key in the api-key header. If the key is missing or does not belong to the program in the URL, the API answers 403.

Each key belongs to one program. You can create several keys, for example one per system that connects to JeriCommerce, give each one only the access it needs, and delete any of them without affecting the others.

Get API Key

To create a key, go to Settings > Technical > API keys and click Add API key. A page opens with these settings.

Add API key page with Name, Expiration, Restrict key, Permissions, Restrict by IP and Status
The Add API key page, with Restrict key checked
1

Name the key

Enter a name in Name, for example the system that will use it.

2

Choose when it expires

In Expiration, choose 15 minutes, 1 hour, 1 day, 7 days, 30 days or Never. New keys start on Never. The time counts from when you save.

3

Choose what it can access

New keys have Restrict key checked. Under Permissions, check at least one option. The table further down shows what each one allows.

4

Limit the IP addresses, if you want

Check Restrict by IP to only accept requests from certain addresses. Enter one in IP address or CIDR range, for example 203.0.113.7 or 203.0.113.0/24, and click Add. You can add up to 100 entries, IPv4 or IPv6.

5

Save and copy the key

Click Save. The API key created dialog shows the key. Copy it and store it somewhere safe, because you won't be able to see it again.

If you uncheck Restrict key, the key can call the whole API, and a leak is much riskier. Keep it checked unless a system really needs full access.

Include Token on API Requests

To access the API endpoints, include the API key obtained in the previous step as the value of the api-key header.

Here is an example using cURL that reads a customer:

curl --request GET \
  --url https://api.jericommerce.com/v1/programs/{program_slug}/customers/customer@example.com \
  --header 'api-key: {{ apiKey }}'

Keep the key on your server. Anyone with it can change your customers' data, so never put it in a website, an app, or any code that runs on the customer's device.

The Balance preview and List rewards endpoints are public and work without a key.

What Each Permission Allows

A restricted key can only do what you check under Permissions. Klaviyo webhooks are API calls too, so their key needs the permission for that action.

Permission What the key can do
Customers Get customer details
Customer tokens Get a download link and customer tokens
Balance Increase and decrease balance
Coupons and rewards Assign a coupon and redeem a reward
Campaigns Send a gift card and assign campaigns
Push Send a push notification
Earning flows Execute a custom earning flow
Subscriptions Create or cancel the program's JeriCommerce subscription
API integration Sync customers and loyalty information through the Custom API Integration
VTAP Connect a VTAP NFC reader
MCP Use this key with the JeriCommerce MCP: No access, Read or Write. Write includes reading

Edit a Key

In Settings > Technical > API keys, click the three dots next to a key and choose Edit API key. You can change everything except the key's value.

  • Expiration offers Don't change when the key has an expiry date, so saving another setting doesn't move it.
  • Status, in the side column, stops a key when you set it to Inactive. Set it back to Active to turn the key on again.
  • Delete API key, in the same menu, removes the key. Apps using this key will stop working.

The list shows a badge for each key: Active, Inactive or Expired. Keys created before these settings existed have no restrictions or expiry, and they show Unrestricted until you restrict them.

API Key Errors

These errors come in the message field of the response.

Status message What it means
401 API_KEY_INACTIVE The key is not active. Check its Status.
401 API_KEY_EXPIRED The key's Expiration has passed.
403 API_KEY_IP_NOT_ALLOWED The request comes from an address outside Restrict by IP.
403 API_KEY_PERMISSION_DENIED The key doesn't have the permission for this request.