Purple Dot
Integrate Alhena with Purple Dot to let your AI assistant answer pre-order questions and offer a 1-click cancel link when a pre-order is still cancellable.
Prerequisites
A Purple Dot merchant account with admin access
Three Purple Dot credentials: a Private API Access Token, a Shared Secret, and a Store ID (instructions below)
Getting Your API Credentials
You'll need three values from your Purple Dot Merchant Portal. The first two live on the same API Keys page; the third is in the merchant portal URL itself.
Step 1: Open the API Keys Page
Log in to your Purple Dot Merchant Portal
Go to Settings > Integration > API Keys
You'll see two keys listed on this page: a Public API Key and a Private API Access Token, along with a Shared Secret.
Make sure you copy the Private API Access Token, not the Public API Key. The Public API Key is intended for storefront use and will not authenticate the Alhena integration.
Step 2: Copy the Private API Access Token and Shared Secret
Copy the following two values from the API Keys page:
Private API Access Token — the secret token Alhena uses to call Purple Dot on your behalf
Shared Secret — listed separately below the Private API Access Token. Alhena uses this to sign the short-lived token that powers the 1-click cancel link
Step 3: Find Your Store ID
Your Store ID is a 36-character UUID and is not shown on any settings page. You'll find it in the merchant portal URL.
Look at your browser's address bar while you're inside the merchant portal. The URL looks like:
Copy the UUID that appears right after /merchant-portal/.
Example: in the URL
the Store ID is eff4bd3e-4491-4358-8929-6dced8ee473f.
The Store ID is a full 36-character UUID (including hyphens). A common mistake is to stop one character short and end up with only 35 characters. If the 1-click cancel link doesn't work after connecting, the truncated Store ID is the first thing to re-check.
Credential Summary
Private API Access Token
Purple Dot Merchant Portal > Settings > Integration > API Keys — copy the Private token, not the Public API Key
Shared Secret
Same API Keys page, listed separately below the Private API Access Token
Store ID
The 36-character UUID in the merchant portal URL, right after /merchant-portal/ (e.g. eff4bd3e-4491-4358-8929-6dced8ee473f)
Setup
Step 1: Enable Purple Dot in Alhena
In Alhena, go to Settings > Integrations
Find Purple Dot and click Enable
You'll be taken to the Purple Dot configuration page
Step 2: Connect Your Store
Enter your Purple Dot credentials:
Private API Access Token — paste the Private token from the API Keys page
Shared Secret — paste the Shared Secret from the API Keys page
Store ID — paste the full 36-character UUID from the merchant portal URL
Click Connect to complete the setup. Alhena will verify the credentials with Purple Dot and confirm the connection. If anything is wrong, you'll see an error explaining what's missing or invalid.
Enabled Agents and Capabilities
When you connect Purple Dot, a pre-order-aware capability is added to your Order Management Agent. It's enabled by default because it's read-only and email-gated to the customer in the conversation.
Order Management
Get Pre-Orders
Look up the customer's pre-orders by email. Returns each pre-order's status, estimated ship date, and — if the pre-order is still cancellable — a 1-click cancel link the customer can use to instantly cancel without further support contact. If the customer provides a specific reference (e.g. #PD-5193), only that pre-order is returned.
You can disable this capability from AI Settings > Agents if you'd prefer your AI assistant not to surface pre-order details.
What your customers can ask
Once connected, your AI assistant can help pre-order customers with:
Pre-order status and ship date
"What pre-orders do I have?"
"When will my pre-order ship?"
"What's the status of my pre-order #PD-1234?"
"Has my pre-order been moved to fulfillment?"
Cancellation and refunds
"I want to cancel my pre-order"
"Can I get a refund on my pre-order?"
"How do I cancel order #PD-5193?"
Purple Dot and Shopify together
Most Purple Dot merchants are also on Shopify. When both are connected, Alhena routes pre-order questions to Purple Dot and post-fulfillment questions to Shopify.
The handoff happens at the point where Purple Dot exports a pre-order to Shopify for fulfillment (Purple Dot status: exported). Purple Dot notes the export in its response, so the agent knows where to look next.
Pre-order status, ship date estimates, and cancel requests → Purple Dot capabilities
Shipment status and tracking for a pre-order that has been exported → Shopify capabilities
Regular (non-pre-order) Shopify orders → Shopify capabilities
You don't need to configure anything — the agents pick the right capability based on the customer's question and the current state of the pre-order.
Disconnecting
To disconnect Purple Dot:
Go to Settings > Integrations > Purple Dot
Click Disconnect
Confirm the disconnection
This disables the Purple Dot-connected capability and revokes Alhena's access to your Purple Dot data. Your pre-orders in Purple Dot are unaffected.
Troubleshooting
"Invalid Private API Access Token" or 401 error
Verify the token is correct and hasn't been rotated in Purple Dot > Settings > Integration > API Keys
Tokens are case-sensitive — copy-paste carefully, with no leading or trailing whitespace
You copied the wrong key
The API Keys page lists two keys: a Public API Key and a Private API Access Token. Only the Private one authenticates the Alhena integration.
If you see authentication errors immediately after connecting, double-check that you didn't paste the Public API Key by mistake.
1-click cancel link doesn't work when the customer clicks it
The cancel link is signed with the Shared Secret and Store ID together. If either value is wrong, the URL is generated but Purple Dot will reject it when the customer clicks through.
Re-check the Store ID length. It must be a full 36 characters (including hyphens). A common failure mode is copying only 35 characters — for example, missing the last character of the UUID when selecting from the URL bar. Compare your saved Store ID against the URL in the merchant portal character-by-character.
Re-check the Shared Secret. Make sure you copied the full value from the API Keys page with no truncation or trailing whitespace.
Capabilities don't appear on the Order Management agent page
After connecting Purple Dot, refresh the agent settings page in Alhena
If the capability is still missing, confirm the connection succeeded on Settings > Integrations > Purple Dot — a partial or failed connection will not register the capability
No pre-orders returned for a customer you know has one
The lookup is by the customer's email — make sure the email Alhena is using in the conversation matches the email on the pre-order in Purple Dot
Pre-orders that have already been fully exported and fulfilled may no longer be returned as pre-orders; those questions are best answered through your storefront order capabilities
Last updated