> 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-recharge.md).

# Recharge

Integrate Alhena with Recharge to let your AI assistant manage customer subscriptions — pause, skip, swap, refund, and more — directly in chat.

## Prerequisites

* A Recharge merchant account with admin access
* A Recharge API token (instructions below)

## Getting Your API Token

### Step 1: Create an API Token in Recharge

1. Log in to your **Recharge Merchant Portal**
2. Go to **Apps & integrations > API tokens**
3. Click **Create an API token**
4. Give the token a recognizable name (e.g. `Alhena`)

### Step 2: Configure Token Scopes

Grant the token the following permissions. Each one unlocks a specific group of customer support actions.

| Scope               | Permission Level | What it enables                                                                                                                                                  |
| ------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Subscriptions**   | Read and Write   | Look up subscriptions; pause, resume, cancel, reactivate, skip, change frequency, swap product, change quantity, change address, add or remove one-time products |
| **Customers**       | Read             | Look up the customer by email; surface name, phone, lifetime value                                                                                               |
| **Discounts**       | Read             | Look up discount codes, list active promotions                                                                                                                   |
| **Orders**          | Read and Write   | Refund a past charge, skip or unskip a delivery, apply a discount to the next charge, look up the recurring-order history                                        |
| **Payment Methods** | Read             | Show the card on file (brand, last four digits, expiry) for the customer's subscriptions                                                                         |
| **Store Credits**   | Read             | Check the customer's available store-credit balance                                                                                                              |

{% hint style="warning" %}
If you skip the **Write** scope on Subscriptions or Orders, Alhena will still be able to read but cannot pause, skip, refund, or otherwise modify anything on the customer's behalf. Most subscription support requires Write — grant it unless you have a specific reason not to.
{% endhint %}

### Step 3: Copy the Token

After saving, Recharge will display the access token once. Copy it immediately — it won't be shown again.

{% hint style="warning" %}
The Access Token is only displayed once when you create it. If you lose it, you'll need to create a new token.
{% endhint %}

***

## Setup

### Step 1: Enable Recharge in Alhena

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

### Step 2: Connect Your Store

1. Paste your **Recharge Access Token** into the token field
2. Click **Connect**

Alhena will verify the token with Recharge and confirm the connection. If the token is invalid or missing required scopes, you'll see an error explaining what's wrong.

***

## Enabled Agents and Capabilities

When you connect Recharge, subscription-aware capabilities are added to your **Order Management Agent** and **Product Expert Agent**. Only **Get Subscription Info** is enabled by default — the rest are opt-in from **AI Settings > Agents** so you control exactly what your AI is allowed to do.

### Order Management

| Capability                               | Description                                                                                                                                                                                                     |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Get Subscription Info**                | Look up the customer's subscriptions — status, next charge date, cadence, product, quantity                                                                                                                     |
| **Manage Subscription**                  | Pause, resume, cancel, skip, unskip, reactivate, change next charge date, change frequency, change quantity, swap product, change address, add or remove one-time products, apply a discount to the next charge |
| **Get Subscription Payment Methods**     | Show the card on file (brand, last 4, expiry) that the customer's subscriptions will be charged on                                                                                                              |
| **Get Subscription Store Credits**       | Check the customer's available store-credit balance                                                                                                                                                             |
| **Update Subscription Shipping Address** | Update the shipping address used by the customer's subscriptions                                                                                                                                                |
| **Refund Charge**                        | Issue a full or partial refund on a past subscription charge                                                                                                                                                    |

### Product Expert

| Capability                 | Description                                                              |
| -------------------------- | ------------------------------------------------------------------------ |
| **Lookup Discount Code**   | Look up a Recharge discount code to confirm validity and discount amount |
| **List Active Promotions** | Show currently active Recharge discount codes                            |

You can enable or disable individual capabilities in **AI Settings > Agents**.

***

## What your customers can ask

Once connected, your AI assistant can help subscribers with:

### Subscription status and management

* "What subscriptions do I have?"
* "When is my next box shipping?"
* "Pause my subscription"
* "Skip my next delivery"
* "Actually, send me the next one — unskip it"
* "Cancel my subscription"
* "Reactivate my subscription"
* "Change my subscription to every 45 days instead of 30"
* "Move my next charge to July 15"
* "Increase my quantity to 2"
* "Swap me from the 30-day pack to the 60-day pack"
* "Add a one-time bottle to my next order"

### Payments and billing

* "What card am I being charged on?"
* "How do I update my payment method?"
* "Refund my last charge"
* "How much store credit do I have?"
* "Apply discount code SAVE20 to my next charge"

### Shipping address

* "Update my shipping address to 123 Main Street, Brooklyn NY 11201"
* "Ship my next box to a different zip code"

### Discounts and promotions

* "Is discount code WELCOME10 still valid?"
* "Are there any active promotions right now?"

{% hint style="info" %}
Mutating actions like cancel, refund, address changes, and frequency changes are gated behind agent guidelines that ask the customer to confirm before Alhena commits the change. You can tighten or relax these guidelines on the agent settings page.
{% endhint %}

***

## Recharge and Shopify together

Most Recharge merchants are also on Shopify. When both are connected, Alhena routes correctly:

* **Subscription questions** ("when's my next box?", "skip my delivery") → Recharge capabilities
* **One-time order questions** ("where's my order #12345?", "has it shipped?") → Shopify capabilities
* **Refunds on a past subscription charge** → Recharge `Refund Charge`
* **Cancellation of a one-time storefront order** → Shopify `Cancel Order`

You don't need to configure anything — the agents pick the right capability based on the customer's question.

***

## Disconnecting

To disconnect Recharge:

1. Go to **Settings > Integrations > Recharge**
2. Click **Disconnect**
3. Confirm the disconnection

This disables all Recharge-connected capabilities and revokes Alhena's access to your Recharge data. Your subscriptions in Recharge are unaffected.

***

## Troubleshooting

### "Invalid Recharge access token" error

* Verify the token is correct and hasn't been revoked in **Recharge > Apps & integrations > API tokens**
* Tokens are case-sensitive — copy-paste carefully, no leading or trailing whitespace

### "Access denied" or 403 errors when Alhena tries to skip, pause, or cancel

* The token is missing the **Write Subscriptions** scope
* Go to your Recharge API token settings and grant Read and Write on Subscriptions
* No need to reconnect from the Alhena dashboard — scope changes apply immediately

### Capabilities don't appear on the Order Management or Product Expert agent pages

* After connecting Recharge, refresh the agent settings page
* If only **Get Subscription Info** is showing, that's expected — every other Recharge capability is opt-in. Enable the ones you want from the capability toggles on the agent page.

### "Failed to fetch store credit balance"

* The token is missing the **Read Store Credits** scope
* Grant it in your Recharge API token settings if you want Alhena to answer "how much credit do I have?" questions

### Discount code lookup returns nothing for a known code

* Confirm the code exists and is **enabled** in **Recharge > Discounts**
* Codes that are disabled, expired, or have hit their usage limit won't be returned

### "Failed to apply discount" when the customer has an active code

* Recharge allows only one active discount per shipping address at a time
* If a discount is already applied to the address, applying another fails — that's a Recharge limitation, not an Alhena bug