Customer account extensions

​

Overview

​

Register a block

curl -X PUT https://api.salesive.com/api/v1/checkout-extensions/customer-account \
  -H "Authorization: Bearer $APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://loyalty.example.com/salesive/account",
    "title": "Loyalty points",
    "icon": "https://cdn.example.com/loyalty.png"
  }'

• The row is bound to the installation behind the token, never to anything in the request. A second PUT replaces the registration.
• GET returns 404 when nothing is registered. DELETE removes the row.
• Uninstalling the app switches every extension kind off, this one included.
• The URL is checked with the webhook URL guard: https only, no credentials, and no loopback or private address. The platform never calls the URL; the shopper’s browser loads it in an iframe. For local development, use a public https tunnel.
• The release snapshot records the block’s title and icon. Publishing does not rewrite the live row; the Store API reads the AppCheckoutExtension row.

​

The merchant switch

PATCH /api/v1/apps/installed/:id/checkout-extensions/customer-account
{ "active": false }

​

How the theme gets your block

GET /api/v1/account/extensions

{
  "status": 200,
  "success": true,
  "message": "Account extensions retrieved",
  "data": {
    "extensions": [
      {
        "id": "665f...",
        "appName": "Loyalty App",
        "title": "Loyalty points",
        "icon": "https://cdn.example.com/loyalty.png",
        "url": "https://loyalty.example.com/salesive/account?salesive_shop=...&salesive_customer=...&salesive_exp=...&salesive_signature=..."
      }
    ]
  }
}

​

The signed URL

​

Verify before you act

1. Read salesive_shop, salesive_customer, salesive_exp and salesive_signature from the URL. Reject the request when any is missing.
2. Reject the request when salesive_exp is in the past, or more than 300 seconds ahead of your clock. The URL is minted with a 300 second lifetime, so a fresh one is always inside that window.
3. Recompute the HMAC over the three values after URL decoding, using your webhook signing secret. Compare it with salesive_signature in constant time.
4. Only after the signature matches, treat salesive_customer as the shopper and salesive_shop as the store.
5. Never take a customer id from another query parameter, a cookie, a header or local storage. An unsigned value is not proof of anything, and a valid signature for one shopper must not be reused for another.

import crypto from "crypto";

const SIGNING_SECRET = process.env.SALESIVE_WEBHOOK_SECRET; // whsec_...
const MAX_AGE_SECONDS = 300;

const safeEqual = (a, b) => {
  const left = Buffer.from(a);
  const right = Buffer.from(b);
  return left.length === right.length && crypto.timingSafeEqual(left, right);
};

// Returns the shopper and store the URL speaks for, or null.
export function verifyAccountExtension(requestUrl) {
  const params = new URL(requestUrl).searchParams;
  const shop = params.get("salesive_shop") || "";
  const customer = params.get("salesive_customer") || "";
  const expText = params.get("salesive_exp") || "";
  const signature = params.get("salesive_signature") || "";
  const exp = Number(expText);

  if (!shop || !customer || !Number.isInteger(exp) || !signature) return null;

  const now = Math.floor(Date.now() / 1000);
  if (exp <= now || exp - now > MAX_AGE_SECONDS) return null;

  const expected = crypto
    .createHmac("sha256", SIGNING_SECRET)
    .update(`${expText}.${shop}.${customer}`)
    .digest("base64url");

  if (!safeEqual(signature, expected)) return null;
  return { shopId: shop, customerId: customer };
}

​

What your page must do

• Serve over https. The URL is embedded in an iframe on the storefront.
• Verify the signature on every request, as above.
• Work in an iframe, including a narrow mobile width. The theme controls the frame; your page owns its contents.
• Not depend on document.referrer or on the shopper’s storefront cookies. Third party cookies may be blocked in an iframe, and the theme opens your page with no referrer.
• Not assume the URL is single use. The same URL can be opened more than once until it expires.
• Keep the block to one purpose. One installation has one customer account block, and a second registration replaces it.
• Return an error page, not a redirect to the storefront login, when the signature is missing or invalid.

​

What other themes must do

1. Call GET /api/v1/account/extensions on the account page with the shopper’s normal session, using the same client the theme already uses for /user.
2. Read data.extensions.
3. Render nothing when the list is empty. No heading, no empty state.
4. Render each item as a card with title, appName and icon, and open url in an iframe when the shopper chooses it.

<iframe src={extension.url} title={extension.title} referrerPolicy="no-referrer" />

​

Not in this surface

​

Next steps