Goal: Sell Gift Cards

Goal ID: SELL_GIFT_CARDS

Produces at most one recommendation — create a gift card product on a site that doesn't sell one yet — carrying the full product design: name, description, preset denominations, custom amount range, expiration policy. Amounts are calibrated from the site's own AOV and catalog price distribution.

The orchestrator activates this domain on "should I sell gift cards", "add a gift card", "which amounts should my gift card offer", gift-card denominations, a gifting-season prompt where a gift card is the lever, or an open "boost my sales" prompt on a site that sells no gift card yet with a gifting occasion near.

Not this goal: issuing / redeeming / voiding / emailing an individual gift card is the Gift Cards API — a direct operation, not a recommendation. Changing denominations on a product that already exists is Update Gift Card Product.

Execution rules

1. Do NOT ask clarifying questions. The only question you may ask is the expiration question in Step 3d, and only if the merchant already raised expiry.
2. Do NOT size denominations before calling the APIs below. Amounts invented without the site's AOV and price distribution are wrong even when they look plausible.
3. Every number in reasoning must come from an API response. Name the call it came from.
4. Persist before presenting. The recommendation must be written via BatchCreate (Step 5) before the merchant sees it, unless they said SKIP_TRACKING.
5. Never create the gift card product here. Creation happens only after the merchant approves the persisted recommendation (Step 6).
6. A site supports a maximum of ONE gift card product. If one exists, there is nothing to recommend — Step 1 drops this domain.
7. All amounts are in the site's currency. Never hard-code a currency symbol, and never assume USD.
8. Always state the expiry stance in what you show the merchant — see Step 3d.

Step 1: Check whether the site already sells gift cards

MANDATORY HARD GATE — a site supports a maximum of 1 gift card product. Skipping this produces a recommendation that can only fail with GIFT_CARD_PRODUCT_ALREADY_EXISTS (409) at creation time.

Endpoint: POST https://www.wixapis.com/gift-cards/v1/gift-card-products/query

Response (amounts are in the site's currency; formattedAmount carries the site's own symbol — use it when displaying):

When a product already exists — review it, don't re-pitch it

A merchant asking "should I sell gift cards / which amounts?" who already has a product wants their current setup assessed. Never emit a create recommendation, never persist anything, and never propose a second product — a site supports one. Instead, read the design rules in Step 3 and report:

1. What exists — name, the preset amounts and custom range from the Query response (use formattedAmount), and the expiry stance read from expirationType: NONE → "these never expire, which is the safer default"; RELATIVE / FIXED → state the period or date and flag that gift card expiry is regulated and varies by market, so it's worth confirming it's permitted where they sell.
2. Whether the amounts still fit — size the ladder you would pick from the site's data (Step 3a–3c) and compare. Say plainly if the current presets sit far from that (e.g. every preset below the median product price, or a top preset far above anything the store sells), and name the numbers on both sides.
3. How to change it — Update Gift Card Product (PATCH, needs the current revision), and the dashboard link at the end of Step 5. Updating replaces the whole presetVariants list; individual presets can't be patched.

Expiry gets stated in this path too — reading it off the existing product, per Step 3d. A gift-card answer that never mentions expiry is incomplete regardless of which branch you took.

Step 2: Eligibility and urgency

Site data comes from the orchestrator's context load (eCommerce: Load Context) — siteData.currency, language, country, industry, aov, orders30d, visitors30d, catalogAnalytics, hasCatalog. Do not re-fetch any of it.

Step 2a: Eligibility gates

Step 2b: Gifting-occasion window

Gift cards are the classic last-minute gift, so the product must be live ≥ 21 days before the occasion to catch the buying window — that lead time is the whole reason urgency matters here.

Using current_date and siteData.country, resolve the nearest gifting occasion within 75 days for that country. Do not assume a US calendar — the same occasion moves, and some don't exist locally:

• Mother's Day — 2nd Sunday of May in the US, CA, AU; late March (Mothering Sunday) in the UK and IE; other dates elsewhere.
• Year-end gifting — peaks in the days before Dec 25 across most of Europe, but in Spain and much of Latin America the gift-giving peak shifts to Reyes on Jan 6.

Other occasions worth resolving per country rather than assuming: Valentine's Day, Father's Day, graduation season, Black Friday, Boxing Day, Lunar New Year, Diwali, Eid al-Fitr, Hanukkah.

If nothing lands within 75 days, do not drop the domain — recommend the evergreen case (birthdays, last-minute gifts, indecisive buyers) at lower urgency.

Step 2c: Urgency

Never use CRITICAL. Gift cards are a revenue opportunity, never a blocker — the orchestrator reserves CRITICAL for broken configuration (no shipping coverage, no payment method).

Step 3: Design the gift card product

All amounts are decimal strings in siteData.currency. The numbers in the examples below are bare on purpose — no currency symbol belongs in the params.

Step 3a: Pick the anchor

aov comes from the metasite profile fields the orchestrator already loaded, not from the catalog — so a failed or empty GetCatalogAnalytics does not stop you sizing denominations. Only both sources missing does (Step 2a).

When catalogAnalytics is available, also read priceMin (min(price)), priceMax (max(price)), and p90 from the "All Products" group — they only tune the clamps in Step 3b. Ignore every other categoryName: category-level stats do not size a store-wide gift card.

Step 3b: Preset denominations

1. Candidates: anchor × 0.5, anchor × 1, anchor × 2, anchor × 4.

2. Round each to a "nice" number:

   Raw amount	Round to nearest multiple of
   < 50	5
   50 – 199	10
   200 – 499	25
   ≥ 500	50

3. Floor every value at 10. Drop duplicates. Sort ascending.

4. If priceMin is known and the lowest preset falls below it, raise it to priceMin rounded up with the table — a card that can't buy the cheapest item is dead weight. Skip this step when catalog stats are unavailable.

5. If priceMax is known, cap the highest preset at priceMax × 2 rounded with the table. Skip when unavailable.

6. Keep 3–5 presets. Fewer than 3 after dedupe ⇒ add anchor × 3 (rounded) until you have 3.

Worked example — aov = 62, priceMin = 18, priceMax = 210, all in the site's currency: 31 → 30, 62 → 60, 124 → 120, 248 → 250; cap check 210 × 2 = 420 → no change ⇒ ["30", "60", "120", "250"].

The rounding table is currency-agnostic: it operates on the site's own currency units, whatever they are. Do not convert to another currency first, and do not re-tune the thresholds per currency.

Step 3c: Custom variant

Always include one — it captures buyers whose budget sits between presets.

• minValue = min(lowest preset ÷ 2, priceMin), rounded with the table, floored at 10.
• maxValue = highest preset × 2, rounded with the table.
• minValue must be strictly less than maxValue — otherwise creation fails with CANNOT_CREATE_GIFT_CARD_PRODUCT_WITH_INVALID_CUSTOM_AMOUNTS_RANGE.

Continuing the example: minValue = "15", maxValue = "500".

Step 3d: Expiration policy

Default: no expiration. Leave expirationMonths unset. Two reasons, both worth stating in reasoning:

• Expiry on stored-value cards is regulated, and the rules differ by market — some jurisdictions impose a multi-year minimum, others ban expiry outright. You cannot assess which applies from API data.
• Unexpiring cards convert better and generate fewer support tickets.

Only if the merchant explicitly asked for an expiry: propose expirationMonths: 60 (5 years), and add to reasoning: "Expiry set at the merchant's request. Gift card expiry is regulated in many jurisdictions — confirm 5 years is permitted where you sell." Never propose fewer than 60 months. Never volunteer an expiry the merchant didn't ask for.

State the expiry stance explicitly, every time — in every branch. When you're recommending a new product it must appear in all three of reasoning, successCriteria, and the prose you show the merchant; when a product already exists, report that product's expirationType instead (Step 1). Concretely, for a new product — "these cards never expire, which is also the safer default because expiry is regulated and varies by market", or the 5-year version with its caveat. A recommendation that silently omits expiry is incomplete: expiry is a decision the merchant is accountable for, not a default to leave unmentioned.

Step 3e: Name and description

Customer-facing copy — write both in siteData.language, not English.

Step 4: Validate

Run every check before handing the recommendation back to the orchestrator. A failure here is a recommendation that cannot be executed.

Step 5: Persist the recommendation — MANDATORY

⛔ You have not finished this goal until BatchCreate has returned an id. Do not present the recommendation to the merchant before that. Skip only if the merchant said SKIP_TRACKING or "don't track". See API: Recommendation Tracking for the lifecycle.

Endpoint: POST https://manage.wix.com/_api/agentic-recommendations/v1/agentic-recommendations/batch-create

If the orchestrator activated other domains too, this recommendation goes into that same batch — one BatchCreate for all domains, not a second call. If gift cards is the only active domain, make the call here yourself.

Save the returned id and revision — they are what the merchant approves against, and Step 6 needs them. If BatchCreate fails, present the recommendation anyway, without an id, and say that tracking failed.

The recommendation object — domain: "gift_cards", action: "create_gift_card_product":

Omit giftCardProduct.expirationMonths entirely when there's no expiry. Do not send null.

expiresAt = the earlier of (gifting occasion − 7 days) and (current_date + 30 days); current_date + 30 days when there's no occasion in window. Past that the data is stale and the window is gone.

In the orchestrator's output, echo the id and revision BatchCreate returned for this recommendation — they're required for Approve / MarkExecuting / MarkDone. When presenting, format the denominations in the site's currency and include this dashboard link (from Stores Dashboard Navigation):

https://manage.wix.com/dashboard/{siteId}/ecom-platform/gift-cards

Field rules

Step 6: On approval — create the product

Only after the merchant approves the persisted recommendation, follow the tracking transitions in API: Recommendation Tracking — Approve → MarkExecuting → create → MarkDone / MarkFailed — and call Create Gift Card Product:

POST https://www.wixapis.com/gift-cards/v1/gift-card-products

params do not map 1

Currency comes from the site's default — the request carries bare amounts, not a currency field. On success, call MarkDone with the new giftCardProduct.id in executionResult.resultPayload and hand back the dashboard link.

Error handling

Constraints

• At most one gift-card recommendation per session — one gift card product per site, so Step 1 is not optional.
• Never create, update, or delete anything before the merchant approves the persisted recommendation.
• Denominations derive from this site's AOV and catalog prices. No stock 25/50/100 ladder.
• No expiry unless the merchant asked; then ≥ 60 months, with the compliance caveat stated.
• Amounts are decimal strings in the site's currency. Never assume USD, never hard-code a symbol.
• presetVariants[].price and .value are always equal — promotional gift-card pricing is out of scope.
• Persist via BatchCreate before presenting (Step 5), unless SKIP_TRACKING.
• The expiry stance is always stated to the merchant, never left implicit.

References

• Recommend: eCommerce Strategy — the orchestrator that loads this file · API: Recommendation Tracking
• Gift Card Products API — Create · Query · Update · Delete
• Gift Cards API — individual issued cards (out of scope here)