---
name: "upsell_cross_sell"
description: "Write upsell and cross-sell offers that fit the purchase: pairing logic for choosing the add-on, timing by placement (product page, cart, checkout, post-purchase, follow-up email), worked copy for each placement, price proportion checks, and measuring acceptance without hurting checkout conversion or trust. Use when someone asks for an upsell, cross-sell, order bump, bundle add-on, post-purchase offer, frequently bought together copy, or help raising average order value with add-on offers. For the core offer itself use offer_design_framework, for page copy use copywriting, for subscription gates use paywall_design."
---

# Upsell and Cross-Sell Offers

## Purpose
Build add-on offers that a buyer reads as help finishing the job they already started, not as a toll on the way out. This skill picks the right add-on for an anchor purchase, places it at the moment it costs the least trust, writes the copy for that exact placement, checks the price proportion and margin, and measures whether the offer earned its place.

Definitions used throughout, following Shopify's guide to upselling and cross-selling:
- Upsell: a pricier or premium version of the same kind of product the buyer already chose. Same job, higher tier.
- Cross-sell: a related or complementary item the buyer adds alongside the anchor. Different item, same job.
- Downsell: a smaller or cheaper version of an offer the buyer just declined, shown once.
- Order bump: a small add-on offered inside checkout, before payment.
- Bundle: anchor and add-on sold together at one combined price, usually shown on the product page.

## Workflow

### 1. Name the anchor and the job it does
- Write down the anchor product, its price, and the job the buyer hired it for in one plain sentence, for example: a camera body, job is taking sharp photos on a trip.
- Every candidate add-on must complete, protect, maintain, or extend that job. If the link needs a paragraph to explain, the pairing is weak. Cut it.
- List what the buyer will need in the first week of use, what they will run out of, and what could ruin the anchor if it fails. Those three lists are where good add-ons live.

### 2. Pair with logic, not with bestsellers
Score each candidate with the pairing method in references/pairing-logic.md. The short version:
- Co-purchase evidence first: items buyers already buy together in real orders beat opinions.
- Compatibility second: the add-on must actually fit, work with, or be consumed by the specific anchor variant in the cart. A case for the wrong model is a return waiting to happen.
- Completeness third: does the anchor disappoint without it? Batteries for a device that ships without them is the classic case Shopify uses. Completeness pairings convert because they prevent a bad first use.
- Refill cycle fourth: consumables the buyer will need again, timed to when the first supply runs low.
- Never pair to clear slow stock. Buyers can tell, and one irrelevant offer teaches them to ignore every later offer.

### 3. Pick one placement and respect what it can carry
Full timing rules are in references/placement-timing.md. Summary:
- Product page: bundles, version upgrades, frequently bought together. Room to explain, buyer is still comparing.
- Cart: small completeness add-ons, quantity help, free shipping gap fillers. One offer, one click to add, total updates in plain sight.
- Checkout (order bump): one low-price, zero-explanation add-on only. Checkout is where surprise costs already kill orders, so an offer here must show its full price and never slow payment down.
- Post-purchase page: the strongest slot for a true add-on. Payment is done, so acceptance cannot risk the original order, and one-click acceptance can reuse the payment method already given. One offer, then at most one downsell.
- Thank-you and order status pages: softer recommendations and next-order offers. No pressure copy, the purchase is complete.
- Follow-up email: refill and companion offers timed to delivery and first use, not to the order date alone. A fulfillment event is not a delivery, so allow shipping time before any copy that assumes the item arrived.

### 4. Check price proportion and margin before writing copy
- Run scripts/offer_math.py on the anchor and the candidate. It reports the add-on price as a share of the anchor price, the margin on the add-on, and the acceptance rate the offer needs to clear a target gain per order.
- Working heuristic, labeled as a heuristic to test and not a researched constant: in-cart and checkout add-ons tend to work in the range of about 10 to 30 percent of the anchor price. Shopify's own guidance makes the same point in plain form: weigh whether the add-on swells the total out of proportion to the anchor.
- Post-purchase offers can carry a higher price than checkout bumps because they cannot hurt the original conversion, but they still need the pairing logic from step 2.
- Kill any add-on whose margin goes negative after its discount, shipping, and expected return cost. Revenue per order is the wrong scoreboard if profit per order falls.

### 5. Write the copy for that placement
Use the worked copy in references/copy-library.md. Every offer, in every placement, carries five parts:
1. The link: one line naming why this goes with the anchor, in the buyer's words for the job.
2. The outcome: what goes better, faster, or safer with it.
3. The full price: add-on price and the new order total, before the button, never after.
4. The accept action: a button that says what happens, for example Add the case for $24.
5. The decline path: a plain, equally visible way to say no that moves the buyer forward at once. No guilt copy on the decline button, ever.
Keep the offer to one product, one reason, one price. Three choices is the ceiling on a product page and one choice is the rule in checkout and post-purchase.

### 6. Run the consent and honesty check
Before any offer ships, check it against references/measurement.md, which includes the consent list drawn from the FTC staff report Bringing Dark Patterns to Light (September 2022):
- No pre-checked add-on boxes. Acceptance is an explicit act by the buyer.
- No fake timers, fake stock counts, or invented demand claims.
- Total price, taxes, and shipping effect shown before acceptance, not revealed after.
- For any offer that starts a subscription or recurring charge: material terms up front, express informed consent before charging, and cancellation as simple as signup.
- Declining is as easy as accepting. If the no path is smaller, greyer, or slower, the offer fails the check.

### 7. Measure acceptance and guardrails together
- Primary metric: acceptance rate, accepts divided by offers shown, per placement and per pairing.
- Money metrics: incremental revenue per order and incremental margin per order versus a no-offer holdout or the pre-launch baseline.
- Guardrails, checked on the same report: checkout conversion rate, refund and return rate on orders with the add-on, support contacts about surprise charges, and repeat purchase rate.
- An offer that lifts order value while checkout conversion or repeat purchase falls is losing money on a delay. Pause it and fix the pairing or the placement.
- Change one variable per test: pairing, placement, price, or headline. Read results only after the test has enough orders to matter, and write the decision down. Method detail is in references/measurement.md.

## Output Contract
When asked to build or fix an upsell or cross-sell offer, return:
1. Anchor summary: product, price, and the job sentence.
2. Pairing table: each candidate add-on, its pairing type (completeness, compatibility, refill, upgrade, companion), the evidence for it, and a keep or cut verdict.
3. Placement plan: one primary placement per offer, with the timing reason.
4. Offer copy: for each shipped offer, the link line, outcome line, full price line, accept button text, and decline text, written for its placement.
5. Math sheet: output from scripts/offer_math.py or the same figures computed by hand, including price share, margin, and break-even acceptance.
6. Test plan: the one variable being tested, the holdout or baseline, the primary metric, the guardrails, and the stop rule.

## Operating Rules
1. One offer at a time in checkout and post-purchase. Stacked offers train buyers to click no on everything.
2. Relevance beats margin when picking the add-on. A high-margin item that does not fit the job is a return and a lost repeat buyer.
3. Show the full price and the new total before acceptance. Surprise costs are the top fixable reason buyers abandon checkout in Baymard Institute research, so an add-on offer must never become one.
4. Never pre-check an add-on, never hide the decline path, never use a timer or stock claim that is not literally true.
5. A downsell appears at most once, after a decline, and is a genuinely smaller offer, not the same offer with louder copy.
6. Do not offer an add-on the buyer already owns, already has in the cart, or bought in a recent order. Check the cart and the order history first.
7. Post-purchase copy never implies the original order is incomplete, at risk, or held until the buyer decides. The first order is done and confirmed.
8. Numbers in copy (savings, percentages, counts) must be true for this buyer and this cart, or they come out.
9. If pairing evidence is thin, say so, launch to a small share of orders as a test, and label the expected result as a guess until the data lands.

## References
- references/pairing-logic.md: how to score candidate add-ons from order data and product facts.
- references/placement-timing.md: what each placement can carry, timing rules, and sequence limits.
- references/copy-library.md: worked offer copy for product page, cart, checkout, post-purchase, and email.
- references/measurement.md: metrics, guardrails, test design, and the consent and honesty checklist.
- scripts/offer_math.py: price share, margin, break-even acceptance, and free shipping gap math.
- assets/offer-brief-template.md: fill-in brief for one offer from anchor to test plan.