Server-to-Server REST API
The Subscriptions REST API lets your origin server verify a visitor's access and read their subscriptions directly, without relying on the onsite widget. It is the server-side counterpart to the JavaScript API: the same access decisions and response shapes, reached over HTTPS from your backend.
When to Use the REST API
The onsite JavaScript API runs in the visitor's browser and is the right tool for most integrations. Reach for the REST API when the decision has to happen on your server:
- Your CMS or application server renders paid content and needs to decide access before sending HTML.
- You expose your own API and want to authorize a request against the visitor's subscription.
- A backend job needs to read what a visitor currently holds.
Both APIs read the same entitlements, so a visitor who has access onsite has access through the REST API too.
Enable API Access
The REST API is off until you turn it on:
- In your Ezoic dashboard, open Subscriptions → Settings → Developers.
- Open the REST API card and turn on API access.
- Copy your API key from the card.
Your API key is unique to your account — the same key works for any other Ezoic API services you've enabled. You rotate it from your API settings in the Ezoic dashboard.
Base URL
All requests go through the Ezoic API:
https://api-gateway.ezoic.com/subscriptions/v1
Authentication
Every request identifies your site with your API key and a domain query parameter, and identifies the visitor with a header.
Site Credentials
| Parameter | Description |
|---|---|
X-API-Key header |
Your Ezoic API key, from the REST API settings card. |
domain query parameter |
The domain you are querying, for example example.com. It must belong to your account. |
The API authenticates the key, confirms the domain is yours, and rejects the request otherwise — so a key can only ever read its own domains.
?developerKey=YOUR_API_KEY query parameter is still accepted so existing integrations keep working, but we recommend integrations use the X-API-Key header.
Visitor Identity
Each request asks about one visitor. Identify that visitor with exactly one of these headers:
| Header | When to use it |
|---|---|
X-Ezoic-Visitor-Email |
The visitor's email address. Use this whenever your server knows it — the common case, including sites that bring their own login. |
X-Ezoic-Visitor-Token |
The visitor's Ezoic Subscriptions session token (the widget session JWT), relayed from the page. Use this on Ezoic-visitor-account sites where your server has no email to send. |
Send exactly one. A request with neither, or with both, is rejected. The older names X-Ezoic-Reader-Email and X-Ezoic-Reader-Token still work, so existing integrations need no change. Visitor identity always travels in a header, never in the query string, so email addresses and tokens stay out of URLs and logs.
By email
If your server already knows the visitor's email — you run your own login, or the visitor gave it to you — send it as X-Ezoic-Visitor-Email. This is the simplest path and works in every authentication mode.
By session token (Ezoic-visitor-account sites)
If your site uses Ezoic visitor accounts, Ezoic handles sign-in and your server never sees the visitor's email. In that case, relay the visitor's session token from the page instead.
Read the token in the browser with getSessionToken() and send it to your own backend. Your server then forwards it to the REST API as the X-Ezoic-Visitor-Token header:
curl -X GET "https://api-gateway.ezoic.com/subscriptions/v1/access?domain=example.com&product=remove-ads" \
-H "X-API-Key: YOUR_API_KEY" \
-H "X-Ezoic-Visitor-Token: THE_RELAYED_TOKEN"import requests
url = "https://api-gateway.ezoic.com/subscriptions/v1/access?domain=example.com&product=remove-ads"
headers = {"X-API-Key": "YOUR_API_KEY", "X-Ezoic-Visitor-Token": "THE_RELAYED_TOKEN"}
response = requests.get(url, headers=headers)
print(response.json())<?php
$ch = curl_init("https://api-gateway.ezoic.com/subscriptions/v1/access?domain=example.com&product=remove-ads");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-API-Key: YOUR_API_KEY", "X-Ezoic-Visitor-Token: THE_RELAYED_TOKEN"]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;getSessionToken() returns null for a signed-out visitor. The token is scoped to the current domain and expires with the visitor's session, so read it per request rather than storing it. The REST API validates the token against the requested domain, so a token from one site can't be replayed against another. See getSessionToken() in the JavaScript API reference.
Endpoints
Check Access
GET /subscriptions/v1/access HTTP/1.1
Checks whether the visitor holds a product or has bought a one-time item. It is the server-side mirror of hasAccess(product) and hasPurchased({ item }).
Query parameters (in addition to domain):
| Parameter | Description |
|---|---|
product |
A product handle to check whole-product access. |
item |
A one-time item key to check a per-item purchase. For a price that unlocks the current article automatically, send the article's URL or its page path. |
Send at least one of product or item. Both accept a comma-separated list (for example product=premium,remove-ads), and the check is an OR across every product and item sent: the visitor is allowed if they hold any one of them. A single call can mix products and items, up to 50 keys total.
curl -X GET "https://api-gateway.ezoic.com/subscriptions/v1/access?domain=example.com&product=remove-ads" \
-H "X-API-Key: YOUR_API_KEY" \
-H "X-Ezoic-Visitor-Email: visitor@example.com"import requests
url = "https://api-gateway.ezoic.com/subscriptions/v1/access?domain=example.com&product=remove-ads"
headers = {"X-API-Key": "YOUR_API_KEY", "X-Ezoic-Visitor-Email": "visitor@example.com"}
response = requests.get(url, headers=headers)
print(response.json())<?php
$ch = curl_init("https://api-gateway.ezoic.com/subscriptions/v1/access?domain=example.com&product=remove-ads");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-API-Key: YOUR_API_KEY", "X-Ezoic-Visitor-Email: visitor@example.com"]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;Response:
{
"success": true,
"data": {
"decision": "allowed",
"reasonCode": "allowed"
}
}
Grant access only when decision is allowed. Treat every other decision as no current access. See Access Decisions for every decision value.
To check a one-time per-item purchase instead, send item with the same key your site passed at checkout:
curl -X GET "https://api-gateway.ezoic.com/subscriptions/v1/access?domain=example.com&item=article-12345" \
-H "X-API-Key: YOUR_API_KEY" \
-H "X-Ezoic-Visitor-Email: visitor@example.com"import requests
url = "https://api-gateway.ezoic.com/subscriptions/v1/access?domain=example.com&item=article-12345"
headers = {"X-API-Key": "YOUR_API_KEY", "X-Ezoic-Visitor-Email": "visitor@example.com"}
response = requests.get(url, headers=headers)
print(response.json())<?php
$ch = curl_init("https://api-gateway.ezoic.com/subscriptions/v1/access?domain=example.com&item=article-12345");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-API-Key: YOUR_API_KEY", "X-Ezoic-Visitor-Email: visitor@example.com"]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;The onsite hasPurchased({ page: true }) shortcut has no server-side equivalent: the browser knows the visitor's current page, but your server doesn't, so the REST API always takes an explicit item key — the same key your site passed at checkout.
For a price that unlocks the current article automatically, that key is the article's page path (for example /my-article). Send the article's URL or its path as item; a full URL is reduced to the page path before matching. A bare path is matched verbatim, so it must not carry a trailing slash — the widget trims it when stamping the key (/my-article, never /my-article/).
List Products
GET /subscriptions/v1/products HTTP/1.1
Returns the product handles the visitor currently holds — the server-side mirror of getProducts(). One-time item purchases are not products and are not included here (use List Purchases).
curl -X GET "https://api-gateway.ezoic.com/subscriptions/v1/products?domain=example.com" \
-H "X-API-Key: YOUR_API_KEY" \
-H "X-Ezoic-Visitor-Email: visitor@example.com"import requests
url = "https://api-gateway.ezoic.com/subscriptions/v1/products?domain=example.com"
headers = {"X-API-Key": "YOUR_API_KEY", "X-Ezoic-Visitor-Email": "visitor@example.com"}
response = requests.get(url, headers=headers)
print(response.json())<?php
$ch = curl_init("https://api-gateway.ezoic.com/subscriptions/v1/products?domain=example.com");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-API-Key: YOUR_API_KEY", "X-Ezoic-Visitor-Email: visitor@example.com"]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;Response:
{
"success": true,
"data": ["remove-ads", "premium"]
}
A visitor with no active products returns an empty array.
List Purchases
GET /subscriptions/v1/purchases HTTP/1.1
Returns the visitor's purchases and entitlements — the server-side mirror of getPurchases(). Unlike /products, this includes one-time per-item purchases, and each entry carries its status and expiry.
curl -X GET "https://api-gateway.ezoic.com/subscriptions/v1/purchases?domain=example.com" \
-H "X-API-Key: YOUR_API_KEY" \
-H "X-Ezoic-Visitor-Email: visitor@example.com"import requests
url = "https://api-gateway.ezoic.com/subscriptions/v1/purchases?domain=example.com"
headers = {"X-API-Key": "YOUR_API_KEY", "X-Ezoic-Visitor-Email": "visitor@example.com"}
response = requests.get(url, headers=headers)
print(response.json())<?php
$ch = curl_init("https://api-gateway.ezoic.com/subscriptions/v1/purchases?domain=example.com");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-API-Key: YOUR_API_KEY", "X-Ezoic-Visitor-Email: visitor@example.com"]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;Response:
{
"success": true,
"data": [
{
"productKey": "premium",
"status": "active",
"expiresAt": "2026-12-31T23:59:59Z"
},
{
"item": "article-12345",
"status": "active"
}
]
}
Each entry has:
| Field | Description |
|---|---|
productKey |
The product the purchase belongs to. Omitted for a one-time item purchase, and omitted if the product was removed. |
item |
Set only for a one-time per-item purchase. |
status |
The entitlement status: pending, active, expired, revoked, or suspended. Filter on active for current access. |
expiresAt |
RFC 3339 timestamp, set only for time-limited access. Lifetime access omits it. |
A visitor with no purchases returns an empty array.
List Prices
GET /subscriptions/v1/prices HTTP/1.1
Returns the display data for prices addressed by key — for rendering an offer on your own server when your content-to-price mapping already knows which price to show. This is the domain's active catalog, not visitor state, so it takes no visitor-identity header.
Query parameters (in addition to domain):
| Parameter | Description |
|---|---|
keys |
Comma-separated price handles, up to 50. |
curl -X GET "https://api-gateway.ezoic.com/subscriptions/v1/prices?domain=example.com&keys=premium-monthly,premium-annual" \
-H "X-API-Key: YOUR_API_KEY"import requests
url = "https://api-gateway.ezoic.com/subscriptions/v1/prices?domain=example.com&keys=premium-monthly,premium-annual"
headers = {"X-API-Key": "YOUR_API_KEY"}
response = requests.get(url, headers=headers)
print(response.json())<?php
$ch = curl_init("https://api-gateway.ezoic.com/subscriptions/v1/prices?domain=example.com&keys=premium-monthly,premium-annual");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-API-Key: YOUR_API_KEY"]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;Response:
{
"success": true,
"data": [
{
"name": "Premium Monthly",
"priceKey": "premium-monthly",
"type": "recurring",
"amountCents": 499,
"currency": "usd",
"billingInterval": "month",
"billingIntervalCount": 1,
"grantScope": "product",
"trialPeriodDays": 7,
"badgeLabel": "",
"ctaLabel": ""
}
]
}
| Field | Description |
|---|---|
name |
The price's display name. |
priceKey |
The price handle. |
type |
recurring or one_time. |
amountCents |
The amount in the smallest unit of currency. |
currency |
The price's default currency. |
billingInterval |
day, week, month, or year for recurring prices; none for one-time prices. |
billingIntervalCount |
Number of intervals between billings. |
grantScope |
What the price unlocks — the whole product or specific items. |
trialPeriodDays |
Free-trial length, when the price has one. |
badgeLabel / ctaLabel |
The price's display badge and call-to-action labels. |
accessDurationDays |
Access length for a time-limited one-time price. |
boundItems |
The item keys an item-scoped price grants. |
Get Identity Token
POST /subscriptions/v1/identity-token HTTP/1.1
Returns a short-lived, signed identity token for a signed-in visitor.
You only need this endpoint if you use bring-your-own login and want to keep the visitor's email off the page. It exists for sites whose pages run third-party scripts: instead of returning the visitor's email to page JavaScript (where any script can read it), you return this token, so the page never sees the email. If that doesn't apply to you, skip it — the JavaScript API and the other endpoints here use a plain email.
The flow:
- Your page's
AuthAdapterimplementsgetIdentityToken(), which calls an endpoint on your server. - Your server reads the signed-in visitor's email from its own session and calls this endpoint with it.
- This endpoint returns a signed token; the email is encrypted inside it.
- Your server returns the token to the page, and
getIdentityToken()resolves with it. The widget sends the token instead of the email.
Unlike the other endpoints, this is a POST with a JSON body, and it carries no visitor-identity header — the email goes in the body because this endpoint creates a token for that address; it does not look a visitor up.
curl -X POST "https://api-gateway.ezoic.com/subscriptions/v1/identity-token?domain=example.com" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
--data '{ "email": "visitor@example.com" }'import requests
url = "https://api-gateway.ezoic.com/subscriptions/v1/identity-token?domain=example.com"
headers = {"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"}
payload = """{ "email": "visitor@example.com" }"""
response = requests.post(url, headers=headers, data=payload)
print(response.json())<?php
$ch = curl_init("https://api-gateway.ezoic.com/subscriptions/v1/identity-token?domain=example.com");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-API-Key: YOUR_API_KEY", "Content-Type: application/json"]);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{ "email": "visitor@example.com" }');
$response = curl_exec($ch);
curl_close($ch);
echo $response;Response:
{
"success": true,
"data": {
"token": "eyJhbGciOiJIUzI1NiIs...",
"expiresAt": "2026-08-13T18:00:00Z"
}
}
| Field | Description |
|---|---|
token |
The signed identity token. Hand it to the page and return it from getIdentityToken(). The visitor's email is encrypted inside it — the token reveals nothing to page JavaScript. |
expiresAt |
RFC 3339 expiry. The token is valid for one hour. |
Don't cache the token. Call this endpoint whenever the page needs one — typically from a small endpoint on your server that getIdentityToken() hits. Don't fetch once and reuse. After expiresAt the token is rejected, and checkout falls back to asking for an email.
Errors: 400 for a missing or invalid email (the address must be one Stripe will accept at checkout); 503 if identity tokens are not configured for the service — an operations condition, not a caller bug.
Access Decisions
/access returns a decision and a reasonCode. Grant access only for allowed.
| Decision | Meaning |
|---|---|
allowed |
The visitor has active access. |
denied |
The visitor is known but has no entitlement for this product or item. |
login_required |
No visitor could be resolved from the identity you sent — treat as signed out. |
expired |
The visitor had access, but it has ended. |
revoked |
Access was removed. |
The reasonCode gives more detail behind the decision. Possible values: allowed, customer_required, no_entitlement, not_started, expired, revoked, suspended, pending.
Unknown Visitors
If the identity you send doesn't resolve to a known visitor — an email that has never subscribed, or a session token that has lapsed — the visitor simply holds nothing:
/accessreturnsdecision: "login_required"withreasonCode: "customer_required"./productsand/purchasesreturn an empty array.
This is a normal outcome, not an error. Prompt the visitor to sign in or subscribe.
Response Format
Every response looks like this:
{ "success": true, "data": ... }
On an error, success is false and message describes the problem:
{ "success": false, "message": "Send the X-Ezoic-Visitor-Email or X-Ezoic-Visitor-Token header" }
Common error statuses:
| Status | Cause |
|---|---|
400 Bad Request |
Missing product and item on /access, more than 50 principals on /access, a missing X-Ezoic-Visitor-Email or X-Ezoic-Visitor-Token header (or both sent), or a missing/invalid email on /identity-token. |
403 Forbidden |
Subscriptions are not enabled for the domain, the API key lacks the Subscriptions permission, or the X-Ezoic-Visitor-Token is invalid or was issued for a different domain. |
429 Too Many Requests |
Rate limited. The API allows 600 requests per minute per API key and domain; the gateway may apply its own per-key limits on top. |
503 Service Unavailable |
Identity tokens are not configured (the /identity-token endpoint only). |
Authentication and authorization for the API key and domain are handled by the Ezoic API before the request reaches Subscriptions.
Responses Are Not Cached
These reads reflect the visitor's live entitlements and are served with Cache-Control: no-store. Call the API when you need a decision rather than caching results, so a new purchase, cancellation, or expiry takes effect immediately.