> ## Documentation Index > Fetch the complete documentation index at: https://docs.aftersell.com/llms.txt > Use this file to discover all available pages before exploring further. # Subscription upgrades with Stay AI > Step-by-step guide to connecting Stay AI and setting up Subscription Upgrades in Aftersell, including Stay AI-specific limitations around prepaid plans, cancellations, and currency. This page covers everything specific to using **Stay AI** with Subscription Upgrades, including its unique limitations. For a full overview of how Subscription Upgrades work, see [Subscription Upgrades](/aftersell/subscription-upgrades). ## Supported features Stay AI supports all Subscription Upgrade types: * Change delivery or billing frequency (applied to the whole subscription) * Replace with a different product * Both - change frequency and replace product * Add another subscribable item to the subscription (see [Add an item](/aftersell/subscription-upgrades-add-item)). If the customer already subscribes to that product, Stay increases its quantity instead of adding a new line (this has a price-match condition - see the limitations below). * Postpaid (pay-per-delivery) frequencies, including moving a postpaid subscription onto a pay-upfront plan (with the conditions below) Product swaps are supported **except onto a product sold only on pay-upfront plans** - see the prepaid limitation below. ### Moving a subscription onto a pay-upfront plan Switching a postpaid subscription to a pay-upfront (prepaid) plan is supported, with two conditions: * **The pay-upfront plan must already exist in Stay AI and be assigned to the product.** Aftersell cannot create one; the offer only lets you pick from plans already set up in Stay AI. * **The move creates a new subscription and cancels the old one.** Stay makes this change by creating a new subscription on the pay-upfront plan and cancelling the original, so the subscription gets a **new reference**. Warehouse, 3PL, or reporting tools that track subscriptions by reference need to re-sync. See [Fulfillment & 3PL mapping](/aftersell/subscription-upgrades-fulfillment). ## Stay AI-specific limitations * **Prepaid (pay-upfront) subscriptions cannot be modified.** Stay does not allow any change to a subscription the customer has paid upfront for, whatever the upgrade type. If a customer on a prepaid plan accepts an upgrade offer, the upgrade is cancelled and they are refunded, so the subscription is left untouched. For the same reason, you cannot swap a subscription onto a product that is only sold on pay-upfront plans. * **Cancellations are limited to one app per account.** Stay sends cancellation updates to only **one app per account**. If another app or integration registered for Stay's cancellation webhook before Aftersell, Aftersell cannot receive those updates, and the [Subscriptions cancelled chart](/aftersell/analytics_metrics_reference#subscriptions-cancelled-chart) will not reflect Stay cancellations. The API key you connect must include the **Webhooks** permission (see below) for cancellation tracking to work at all. * **A frequency change applies to the whole subscription.** Stay has one schedule per subscription, so changing how often it arrives moves every product on it. When the subscription contains two or more products, you must turn on **Keep on existing subscription** on the offer; otherwise the frequency upgrade is refused and the shopper is refunded. This is only needed for frequency changes - product swaps and add-ons are unaffected and work without it. * **Adding more of a product the customer already subscribes to needs a matching price.** When the add-on is a product the customer already has, Stay increases its quantity rather than adding a line - but only if the offer's price matches what the customer already pays for it. If the prices differ (for example the add-on offers 20% off while their plan is 10% off), the upgrade is refused and the subscription is left unchanged. Give the add-on the same discount as the customer's plan, or offer a different product (a different product is unaffected). * **Currency must match your store's pricing.** If the customer's subscription bills in a currency your store does not price in, the upgrade is refused. * **Duplicate subscriptions from one order cannot be disambiguated.** If a single order started two Stay subscriptions that both contain the offer's product, Aftersell cannot tell which one the customer meant, and the upgrade is refused rather than applied to the wrong contract. * **Rate limits cap throughput.** Stay allows 60 requests per minute per account. One upgrade takes four to six requests, so a store tops out around 10 to 15 upgrades per minute at peak. ## Generating your Stay AI API key 1. In your Stay AI dashboard, go to **Account → API tokens → Add API key**. 2. When creating the key, select **All permissions**. Aftersell needs access to **Subscriptions**, **Orders**, **Selling Plan Groups**, and **Webhooks**. The Webhooks permission is what lets Aftersell hear about cancellations. 3. Copy the key and store it somewhere safe. Treat it like a password. For more details, see [Stay AI's API authentication documentation](https://docs.stay.ai/reference/authentication). ## Connecting Stay AI in the setup wizard When you reach **Step 1: Connect provider** in the Subscription Upgrade wizard: 1. Select **Stay AI** from the **Subscription provider** dropdown. 2. Paste your API key into the **API key** field. 3. Click **Test API key**. Aftersell validates the key, checking that it authenticates and that it belongs to your store. 4. Once the test passes (green check), click **Continue** to move to Step 2. The test result shows one of two states: * **Green tick - "API key verified".** The key authenticated and belongs to your store. **Continue** is now enabled. If the key is missing the **Webhooks** permission, the test still passes but warns that subscription cancellations will not be recorded - re-create the key in Stay AI with **All permissions** if you want cancellation tracking. * **Red cancel icon.** The check did not come back clean. Read the message beside the icon: either the key was rejected, or Aftersell could not complete the check ("Could not verify the API key. Please try again."), which is a failed call rather than a bad key - in that case just test again. A could-not-verify result looks exactly like a rejection, so go by the message rather than the icon. **Continue** stays disabled until the check comes back green, and editing the provider or the key clears the previous result. ## Verifying an upgrade in Stay AI After placing a test order and accepting the upgrade offer: Go to **Subscriptions** in your Stay AI dashboard and find the customer's subscription. The billing frequency, product, or next charge date should reflect the change. The change itself is applied as soon as Aftersell processes the acceptance, but Stay can be slow to ingest a brand-new order: the upgrade usually lands within minutes, and up to 24 hours in the slowest cases. If the change is not there yet, give it a little time before treating it as a failure. ## If an upgrade can't be applied Stay AI upgrades are safe by design - a shopper is never charged for an upgrade that did not happen: * **Failed upgrades are retried automatically.** If a call to Stay AI fails, Aftersell retries it in a background workflow. * **If it still can't be applied, the shopper is refunded.** A Subscription Upgrade charges only a small placeholder line on the Shopify order (not a product the shopper keeps), so Aftersell refunds that charge when the upgrade cannot be completed. * **Anything that can't be confirmed is flagged for manual review** rather than guessed, so a shopper is never charged for an upgrade that did not happen. For the full retry-and-reconciliation mechanics (shared across providers), see [How Subscription Upgrades work](/aftersell/subscription-upgrades#how-subscription-upgrades-work). ## Troubleshooting Stay AI-specific issues **The upgrade was accepted but the subscription was not modified** The most common causes: * The customer is on a **prepaid (pay-upfront)** plan. Stay does not allow prepaid contracts to be modified, so the upgrade is cancelled and refunded. This is expected. * The subscription bills in a **currency your store does not price in**, so the upgrade was refused. * The subscription has **two or more products** and you changed the frequency without turning on **Keep on existing subscription**. * One order started **two Stay subscriptions** that both hold the offer's product, so Aftersell could not tell which to upgrade. * Your API key is from a different store, or is missing a required permission (**Subscriptions**, **Orders**, or **Selling Plan Groups**). Re-create or re-select the key in Stay AI, go to **Step 1: Connect provider**, and re-test it. * The eligible product in the funnel does not match what the customer actually subscribed to. Aftersell automatically retries failed provider calls in a background workflow. If all retries fail, contact support with your store URL, the Shopify order ID, the customer's email, the approximate time the upgrade was accepted, and the provider you are using. **Stay cancellations are not showing in analytics** Stay sends cancellation updates to only one app per account. If another app registered for Stay's cancellation webhook before Aftersell, Aftersell cannot receive them. Confirm no other integration owns Stay's cancellation webhook, and make sure the connected API key includes the **Webhooks** permission. *** ← Back to [Subscription upgrades overview](/aftersell/subscription-upgrades) · [Setup & configuration](/aftersell/subscription-upgrades-setup) · [What are integrations?](/aftersell/subscription-upgrades-integrations)