> For the complete documentation index, see [llms.txt](https://alhena.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://alhena.gitbook.io/docs/integrations/ecommerce/commerce-addons/integrating-alhena-ai-with-purple-dot.md).

# 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

1. Log in to your **Purple Dot Merchant Portal**
2. 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**.

{% hint style="warning" %}
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.
{% endhint %}

### 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:

```
purpledotprice.com/merchant-portal/{store_id}/...
```

Copy the UUID that appears right after `/merchant-portal/`.

**Example:** in the URL

```
purpledotprice.com/merchant-portal/eff4bd3e-4491-4358-8929-6dced8ee473f/settings/integration
```

the Store ID is `eff4bd3e-4491-4358-8929-6dced8ee473f`.

{% hint style="warning" %}
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.
{% endhint %}

### Credential Summary

| Credential                   | Where to Find It                                                                                                                |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **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

1. In Alhena, go to **Settings > Integrations**
2. Find **Purple Dot** and click **Enable**
3. You'll be taken to the Purple Dot configuration page

### Step 2: Connect Your Store

Enter your Purple Dot credentials:

1. **Private API Access Token** — paste the Private token from the API Keys page
2. **Shared Secret** — paste the Shared Secret from the API Keys page
3. **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

| Capability         | Description                                                                                                                                                                                                                                                                                                                                       |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **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.

{% hint style="info" %}
The 1-click cancel link is generated using the Shared Secret and Store ID together — they sign a short-lived token embedded in the URL. If either value is wrong, the link will be returned but won't work when clicked. See **Troubleshooting** below.
{% endhint %}

***

## 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?"

{% hint style="info" %}
For cancellation requests, Alhena surfaces the 1-click cancel link directly in the chat when the pre-order is still cancellable. The customer completes the cancellation themselves with a single click — no agent intervention required.
{% endhint %}

***

## 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:

1. Go to **Settings > Integrations > Purple Dot**
2. Click **Disconnect**
3. 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