Recharge Account API
Overview
Recharge Account API is a single serverless endpoint that lets a Shopify customer account UI extension talk to Recharge as the logged-in customer.
It takes the extension's Shopify session token, checks its signature, looks the customer up in Recharge by their Shopify customer ID, and returns a Recharge customer session token. The extension can then call Recharge's customer-scoped API (subscriptions, orders, addresses) directly, without ever holding a Recharge Admin token.
Customer account UI extension
│ POST /generate_recharge_jwt { "token": "<Shopify session token>", "store": "<shop>.myshopify.com" }
▼
Vercel function api/generate_recharge_jwt.ts
1. verify HS256 signature with the store's Shopify app secret
2. sub = gid://shopify/Customer/<id> → Shopify customer ID
3. GET api.rechargeapps.com/customers?external_customer_id=<id> (Admin token)
4. POST api.rechargeapps.com/customers/<rechargeId>/sessions (Admin + Storefront token)
▼
{ "customerSession": { "api_token": "...", "customer_id": 12345, ... } }Where it's used
The service is called by a customer account UI extension that lives outside this repository; no brand theme or other app repo in the workspace calls it. The stores it serves are the ones with credentials in the Vercel project: each store has its own set of <STORE_KEY> environment variables (see Architecture). Check the variable names in Vercel → recharge-account-api → Settings → Environment Variables to see which stores are configured.
There are no theme-side hooks.
Architecture
| File | Role |
|---|---|
api/generate_recharge_jwt.ts | The production function (Vercel, TypeScript, multi-store) |
api/index.ts | Status JSON at /api |
vercel.json | Rewrites /generate_recharge_jwt → /api/generate_recharge_jwt |
index.ts, routes/auth.ts | Express server for local development (pnpm dev). Single-store: reads only the un-suffixed variables and ignores store. Not deployed. |
Multi-store: the request body's store field (*.myshopify.com) selects the credentials. The store key is the myshopify subdomain, uppercased, with dashes turned into underscores:
| Shop domain | Store key | Variables read |
|---|---|---|
my-store.myshopify.com | MY_STORE | SHOPIFY_APP_SECRET_MY_STORE, RECHARGE_ADMIN_TOKEN_MY_STORE, RECHARGE_STOREFRONT_TOKEN_MY_STORE |
(no store sent) | DEFAULT | SHOPIFY_APP_SECRET, RECHARGE_ADMIN_TOKEN, RECHARGE_STOREFRONT_TOKEN |
Each store-specific variable falls back to its un-suffixed version when missing.
Responses
| Status | Meaning |
|---|---|
200 | { customerSession } from Recharge |
401 | No token, or invalid signature |
400 | Token has no gid://shopify/Customer/<id> subject |
404 | Customer not found in Recharge ("no subscriptions for this account yet") |
405 | Not POST (OPTIONS returns 200 for CORS preflight) |
500 | Credentials not configured for that store (the response names the missing variable), or an internal error |
| other | Passed through from Recharge on lookup or session failure |
CORS is open to all origins, because customer account extensions run on Shopify's domains.
Where it's deployed
| Repository | github.com/crupko93/recharge-account-api, branch master |
| Vercel | Project recharge-account-api, no framework, region iad1. Git-connected: production deploys from master. |
| Production URL | https://recharge-account-api.vercel.app, endpoint POST /generate_recharge_jwt |
| Shopify app record | None in this repo. The secret belongs to whichever Shopify app owns the calling extension. |
| Database | None |
How to use
For the extension developer:
const token = await shopify.sessionToken.get();
const res = await fetch('https://recharge-account-api.vercel.app/generate_recharge_jwt', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ token, store: shopify.shop.myshopifyDomain }),
});
const { customerSession } = await res.json();
// use customerSession.api_token with Recharge's customer-scoped APIThe extension needs network_access = true in its shopify.extension.toml.
For each store, in the Recharge merchant portal → Tools & Apps → API tokens, create:
| Token | Scopes | Env var |
|---|---|---|
| Admin token | read_customer, write_session | RECHARGE_ADMIN_TOKEN_<STORE_KEY> |
| Storefront token | As needed by the extension | RECHARGE_STOREFRONT_TOKEN_<STORE_KEY> |
Plus the Shopify app's client secret as SHOPIFY_APP_SECRET_<STORE_KEY>.
How to update & deploy
- Code: push/merge to
master. Vercel deploys automatically. - Add a store: add the three
<STORE_KEY>variables in Vercel (Production), then redeploy. No code change. - Rotate a token: update the variable in Vercel and redeploy.
Environment variables (names only; never commit values):
| Variable | Purpose |
|---|---|
SHOPIFY_APP_SECRET_<STORE_KEY> | Verifies the Shopify session token signature |
RECHARGE_ADMIN_TOKEN_<STORE_KEY> | Recharge Admin API: customer lookup and session creation |
RECHARGE_STOREFRONT_TOKEN_<STORE_KEY> | Sent with the session request |
SHOPIFY_APP_SECRET, RECHARGE_ADMIN_TOKEN, RECHARGE_STOREFRONT_TOKEN | Fallbacks when no store-specific value exists |
Local development:
git clone git@github.com:crupko93/recharge-account-api.git && cd recharge-account-api
pnpm install
cp .env.example .env # replace <STORE_KEY> with the store key and fill in the values
vercel dev # runs the production function (multi-store), needs `vercel link`
# or
pnpm dev # Express server on port 3000, single-storeThe Express server reads only the un-suffixed variables (SHOPIFY_APP_SECRET, RECHARGE_ADMIN_TOKEN, RECHARGE_STOREFRONT_TOKEN), so add those to .env when using pnpm dev.
Expose the local server with a tunnel (e.g. ngrok http 3000) so an extension can reach it.
Testing
Read-only smoke tests:
curl -s https://recharge-account-api.vercel.app/api # status JSON
curl -s -o /dev/null -w "%{http_code}\n" https://recharge-account-api.vercel.app/generate_recharge_jwt # 405 (GET not allowed)
curl -s -o /dev/null -w "%{http_code}\n" -X OPTIONS https://recharge-account-api.vercel.app/generate_recharge_jwt # 200End-to-end: log in to a customer account that has a Recharge subscription and open the extension. Vercel's function logs show [<STORE_KEY>] Session created for customer <id>.
Troubleshooting & known limits
| Symptom | Cause |
|---|---|
500 SHOPIFY_APP_SECRET not configured | No SHOPIFY_APP_SECRET_<STORE_KEY> (or fallback) for that store |
500 Recharge API tokens not configured | Admin or Storefront token missing for that store |
401 Invalid session token signature | Wrong app secret for the store, or store doesn't match the app that issued the token |
404 Customer not found in Recharge | The customer has never had a Recharge subscription |
500 instead of 401 on a garbage token | timingSafeEqual throws when signature lengths differ |
- Token claims are not validated. The function checks the signature only. It doesn't check
exp/nbf,aud(the app's client ID) ordest(the shop) againststore, so a captured session token keeps working after it expires. Hardening: checkexpandaudthe way Pet Profile'slib/session-token.tsdoes. - Fallback credentials mean a store without its own variables silently uses the default set.
- The deployment serves repo files statically. The root URL
/returns the source ofindex.ts, and/README.mdis readable, because the project has no output directory. No secrets are in the code; anoutputDirectoryor a rewrite of/to/apiwould close this.