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). 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)
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.
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 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
- In your Stay AI dashboard, go to Account → API tokens → Add API key.
- 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.
- Copy the key and store it somewhere safe. Treat it like a password.
Connecting Stay AI in the setup wizard
When you reach Step 1: Connect provider in the Subscription Upgrade wizard:- Select Stay AI from the Subscription provider dropdown.
- Paste your API key into the API key field.
- Click Test API key. Aftersell validates the key, checking that it authenticates and that it belongs to your store.
- Once the test passes (green check), click Continue to move to Step 2.
- 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.
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.
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.
← Back to Subscription upgrades overview · Setup & configuration · What are integrations?