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-ts0.26.0 or later,@waffo/pancake-nextjs0.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 whosebuyerIdentity 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
Step 2: Create the Link on Your Server
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-storeandReferrer-Policy: no-referrerto the redirect response, so the tokenized link is neither cached nor passed on as a referrer
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.
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
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
The portal opens but shows no orders
The portal opens but shows no orders
- Check that the orders were created with the same
buyerIdentitystring (exact match, including case) - Check that the orders belong to the
storeIdyou passed - Check the API Key’s environment: a test key shows only test orders, a production key only production orders
- Orders from anonymous checkout carry no
buyerIdentityand never appear here
The portal says the session has ended
The portal says the session has ended
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 portal says the session was switched
The portal says the session was switched
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.
403 Environment mismatch from the Customer Portal API
403 Environment mismatch from the Customer Portal API
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
-
buyerIdentitycomes from your own signed-in session and matches the value used at checkout -
storeIdcomes from your server configuration, not the request - The route responds with a 302,
Cache-Control: no-storeandReferrer-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.