Members-only store

A store can sell to members only. Shoppers apply, the merchant approves, and only active members can buy. This recipe covers the shopper side with a publishable key, and the review side with a secret key.

You need a shopper credential for the shopper steps. Read Shoppers first.

1. Read the gateCopy Anchor Link

curl https://api.shopeazy.co/v1/store \
  -H "Authorization: Bearer sez_pub_..."

{
  "data": {
    "membership": {
      "enabled": true,
      "gate": "checkout",
      "requireVerification": false,
      "applicationNote": "Tell us why you would like to join."
    },
    "auth": { "tenantId": "<tenant id>" }
  }
}

The API always enforces membership when an order is placed, whatever the gate. The gate is for your UI.

import { membersOnly, membershipGate } from '@shopeazy/storefront-client';

if (membersOnly(store.membership)) {
  const gate = membershipGate(store.membership); // 'checkout' or 'browse'
}

2. Sign the shopper inCopy Anchor Link

Sign the shopper in with the Firebase client SDK, in the store's tenant: set auth.tenantId = store.auth.tenantId before you sign in. Then exchange the Firebase ID token for a 14-day shopper session. The shopper's email must be verified.

curl https://api.shopeazy.co/v1/store/shopper/session \
  -H "Authorization: Bearer sez_pub_..." \
  -H "Content-Type: application/json" \
  -d '{ "idToken": "<firebase id token>" }'

Keep the sessionToken in an httpOnly cookie. See Shoppers for the details.

3. Check where the shopper standsCopy Anchor Link

curl https://api.shopeazy.co/v1/store/me \
  -H "Authorization: Bearer sez_pub_..." \
  -H "X-Shopper-Session: <session token>"

{
  "data": {
    "shopper": { "uid": "shopper_123", "email": "sipho@example.co.za", "name": "Sipho Dlamini", "phone": null },
    "membership": {
      "status": "pending",
      "appliedAt": 1792636800000,
      "decidedAt": null,
      "applicationNote": "Regular buyer at the market.",
      "decisionNote": null
    },
    "canCheckout": false
  }
}

membership is null if the shopper has not applied. status is pending, active, rejected or revoked. decisionNote is the merchant's message on an approval, a decline or a revoke, and the console tells the merchant the shopper sees it. canCheckout is true only for an active member of a members-only store. KYC details and documents are never returned.

4. ApplyCopy Anchor Link

A simple storeCopy Anchor Link

Send JSON. Both fields are optional. name defaults to the shopper's name, then their email.

curl https://api.shopeazy.co/v1/store/members/apply \
  -H "Authorization: Bearer sez_pub_..." \
  -H "X-Shopper-Session: <session token>" \
  -H "Content-Type: application/json" \
  -d '{ "applicationNote": "Regular buyer at the market." }'

The answer is 201 with { "data": { "status": "pending" } }. The store's auto-approve setting applies, so the status can be active at once.

const { status } = await shopeazy.asShopperSession(token).members.apply({ applicationNote });

An ID-verified storeCopy Anchor Link

When requireVerification is true, send multipart/form-data. A JSON body is 422 verification_required.

The typed client builds the form for you:

await shopeazy.asShopperSession(token).members.apply({
  firstName, lastName, dateOfBirth: '1990-01-31', idType: 'sa_id', idNumber,
  addressLine, city, over18: true, consent: true,
  selfie, // a Blob, resize to about 1200px
  idDoc,  // a Blob, an image or a PDF. Resize images to about 1600px
});

• A verified application is always pending, whatever the auto-approve setting.
• The files go to the store's private storage with no public link. The merchant reviews them in the console.
• Applying again while pending or active returns 200 with the current status and leaves the documents under review alone. A rejected or revoked shopper may apply again with new documents.
• A broken field is 422 validation_error, and the message names the field.
• Applying to a store that is open to everyone is 422 validation_error.

5. Let members buyCopy Anchor Link

An order on a members-only store needs a shopper credential. Send the session when you place the order, as in Headless checkout.

Show the shopper where they stand from GET /v1/store/me, and offer Apply when membership is null.

6. Review applications from your serverCopy Anchor Link

Use a secret key. It carries members:manage. Never send it from a browser.

curl "https://api.shopeazy.co/v1/store/members?status=pending" \
  -H "Authorization: Bearer sez_sk_..."

status is pending, active, rejected, revoked or all. The answer is a page, { items, nextCursor }, of members:

{
  "data": {
    "items": [
      {
        "uid": "shopper_123",
        "status": "pending",
        "name": "Sipho Dlamini",
        "email": "sipho@example.co.za",
        "phone": null,
        "applicationNote": "Regular buyer at the market.",
        "appliedAt": 1792636800000,
        "decidedAt": null,
        "decisionNote": null,
        "verification": null
      }
    ],
    "nextCursor": null
  }
}

On an ID-verified store, verification holds the applicant's details. List rows carry no document links. To see the selfie and ID, read one member:

curl https://api.shopeazy.co/v1/store/members/shopper_123 \
  -H "Authorization: Bearer sez_sk_..."

That answer has short-lived signed selfieUrl and idDocUrl links.

Then decide. The optional note is shown to the shopper as decisionNote.

curl -X POST https://api.shopeazy.co/v1/store/members/shopper_123/approve \
  -H "Authorization: Bearer sez_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "note": "Welcome to the club." }'

Use /decline or /revoke in place of /approve for the other decisions.

const pending = await shopeazy.members.page({ status: 'pending' });
await shopeazy.members.approve(uid, { note: 'Welcome to the club.' });

Merchants can also review applications in the console.