Skip to main content

What You’ll Build

A Manage orders button on your site. When a signed-in customer clicks it, your server asks Waffo Pancake for a portal link and redirects the browser there. The customer lands in your store’s customer portal, already signed in, with no email or verification code. In the portal the customer can:
Customers who arrive this way cannot request refunds from the portal. Handle refund requests through your own support channel, then refund from the Dashboard or with the Create Refund Ticket API.

Prerequisites

  • An API Key (Dashboard → API & Development). Use a test key while you build
  • The Store ID (STO_xxx) of the store whose portal the customer should see
  • Orders created with authenticated checkout, so they carry your buyerIdentity
  • Your own sign-in: this flow trusts your server’s session, so the customer must already be authenticated on your site
  • If you use an SDK: @waffo/pancake-ts 0.26.0 or later, @waffo/pancake-nextjs 0.9.0 or later, or the Go SDK v0.17.0 or later
  • Your store’s Website set in Store Settings. When a portal session ends, the portal offers a Return to merchant site button that links only to this address; if no website is set, the button is hidden

Step 1: Choose the Customer Identity

The portal shows the orders whose buyerIdentity equals the value you pass here, in the store you name. Use the same stable value you pass when creating orders.
  • Recommended: your internal customer ID — stable, and never reassigned to another person
  • Avoid email addresses: a customer who changes email would lose sight of earlier orders, and a recycled address could expose them to someone else
  • Orders placed anonymously, or under a different identity, do not appear. Waffo Pancake does not merge identities; if you switch identifiers, earlier orders stay under the old value
Take buyerIdentity and storeId from your server’s own signed-in session — never from a query parameter, form field, header, or cookie value the browser can set. Whoever controls buyerIdentity gets that customer’s portal. Waffo Pancake trusts your server and does not verify the customer’s email.

Call the API from your backend only. The API Key must never reach the browser.
  • Environment follows the API Key. A test key opens the portal with test data; a production key opens it with production data. There is no environment parameter
  • Create the link on every click, right before redirecting. Do not cache it, store it, or send it by email
  • Redirect with 302. Add Cache-Control: no-store and Referrer-Policy: no-referrer to the redirect response, so the tokenized link is neither cached nor passed on as a referrer
The SDK helper createCustomerPortalRedirect takes these options: Every response the helper builds carries Cache-Control: no-store and Referrer-Policy: no-referrer. A response you return from onError is your own — set both headers on it as well.
Set loginUrl to a path you control. Never build it by copying request parameters (such as a returnTo query value) verbatim — that turns your portal route into an open redirect.
Not using an SDK? Call Issue Session Token with purpose: "portal" and storeId, then redirect to portalUrl + "#token=" + token.

Step 3: Add the Button

Point the button at your own route, not at Waffo Pancake. The browser never sees the API Key, and the link is minted only when the customer clicks.

How the Session Behaves

The #token= part of the link is a bearer credential. Do not write the link to logs, analytics, error trackers, or support tickets, and do not share it in email or chat.

Test Before Going Live

1

Create a test order

With your test API Key, place an order through authenticated checkout using a test customer’s buyerIdentity.
2

Open the portal

Sign in to your site as that customer and click Manage orders. The test order should be listed.
3

Check the identity boundary

Sign in as a different customer and confirm the first customer’s order does not appear. Try adding another customer’s ID to the request — your route must ignore it.
4

Switch to production

Deploy with your production API Key. Links now open production data.

Troubleshooting

  1. Check that the orders were created with the same buyerIdentity string (exact match, including case)
  2. Check that the orders belong to the storeId you passed
  3. Check the API Key’s environment: a test key shows only test orders, a production key only production orders
  4. Orders from anonymous checkout carry no buyerIdentity and never appear here
The portal shows Please re-enter from the merchant’s site when the session was idle for more than 15 minutes, or when the portal was opened for a different store than the session in this browser, without a new link. Send the customer back through Manage orders on your site to get a new link.
The customer entered the portal again in the same browser — from your site in another tab, from another store’s portal, or with an email Magic Link. The newest entry becomes the browser’s portal session; older tabs show Session switched and move to the current session. No action is needed.
You called the Customer Portal API with a portal token and an X-Environment that differs from the API Key’s environment. Send the key’s environment.

Checklist

  • The link is created on your server; the API Key never reaches the browser
  • buyerIdentity comes from your own signed-in session and matches the value used at checkout
  • storeId comes from your server configuration, not the request
  • The route responds with a 302, Cache-Control: no-store and Referrer-Policy: no-referrer
  • Portal links and tokens are never logged or stored
  • Refund requests have a support path outside the portal

Next Steps

Issue Session Token

Request and response fields for purpose: "portal".

Customer Portal

What customers see in the portal.