Skip to main content
A portal session is a one-time link that signs one customer into the account page of your storefront. Use it when your own app, support desk or bot already knows who the buyer is, and the buyer should not type their email and a code again.
Send the buyer to url. The buyer lands on the account page of your store, signed in, on the tab you named in section.

​
The scope

The endpoint needs the customers.portal_sessions scope.
  • Full Access (*) does not include it. A key gets it only when you tick Log buyers into the portal in Settings → Developers → API Keys (on a Custom key, or in Edit Access next to Full Access).
  • Only the store owner (or a team member with the Owner role) can give a key this scope.
  • An OAuth app can ask for it. Its token works on this endpoint only while the member who approved the app is an owner.
Anyone who holds a key with this scope can open the account of any of your customers. Keep the key on your server, never in a browser or a mobile app.
The token is the part after #. Browsers do not send that part to any server, so the token does not appear in server logs, in a Referer header or in a link preview. The storefront page reads it, removes it from the address bar and redeems it with a form post from the same site. A mail scanner or chat preview that opens the link without running scripts does not use it up. When the buyer is already signed in on the store as somebody else, the link signs them in as the customer it names, and the earlier session on this store ends. The email address is not marked as verified: you vouched for the buyer, the buyer did not prove the address. The buyer verifies it the next time they sign in with a code.

​
What the session cannot do

A session a link opened can read the account: orders, downloads, subscriptions, tickets and the other tabs. It cannot move money, change how the buyer signs in, or see or end the buyer’s sign-ins. These actions answer 403 with Sign in with your email code to do this:
  • Pay with the store balance (Instant Buy), place a reseller order, top up the wallet or the reseller balance, redeem loyalty points
  • Request an affiliate payout, convert affiliate earnings to store balance, change the commission share of a link
  • Open the card update page of a subscription, or confirm a plan change
  • Create or revoke reseller API keys, or read, rotate or revoke the reseller delivery URL
  • Change the password, link or unlink Discord
  • List the devices the buyer is signed in on, sign one out, or sign out all others
The reseller catalog shows no delivery URLs to this session. The session works only on your storefront: the hosted customer portal and direct API calls do not accept it. The buyer signs in with their email code to do these things.

​
Sections

section is optional. Leave it out to open the overview.

​
Return URL

return_url is optional. When you send it, the account page shows Back to and your store name at the top, and the link goes to this URL. Use it to send the buyer back to the page of your app that opened the account. The URL must use https and must be on one of your store’s own addresses:
  • your myshoppex.io address, while it is on
  • a custom domain you added and verified in Store → Domains
Anything else answers 422: http, another port, a domain you did not verify, another store’s address, or any other site. This keeps the link from sending a signed-in buyer to a page you do not control. Without return_url the account page shows no such link. A used, expired or unknown link, or a link opened on another store, never signs anybody in. The buyer sees This link has expired on the account page, with a button to sign in with their email instead. A session the browser already had stays as it was.

​
Errors

​
Retries

Send an Idempotency-Key header. The link is not stored with the key, so a retry with the same key does not get it again: it answers 409 with the code CONFLICT and the subcode idempotency_key_reused, and makes no second link. Use a new key for a new link. A key still runs the request only once, so a retry after a timeout does not make two links.

​
Revoking access

  • A link that was not used expires after 15 minutes.
  • A session a link opened ends 24 hours after the sign-in.
  • Revoke the API key, or remove customers.portal_sessions from it, and its unused links stop working and the sessions they opened end at their next request. The same is true when the key expires after a rotation, and for an OAuth access token that is revoked.
  • The buyer signs out on the account page to end a session a link opened.
  • A customer you delete loses access to the account page, also through a session a link opened.