Playbook: Kashmir Apples Reservation-Fee Group Buy

Last updated: 2026-03-29

1. Purpose and when to use this

Use this playbook when you want to launch a physical-product drop on 10xDotin without inventing custom commerce infrastructure. The supported shape today is:

• a public story page for the drop
• a group-buy for quantity interest
• a paid reservation page with a flat booking fee
• a linked offer that keeps checkout locked until the group-buy target is reached

This pattern is honest for a June Kashmir apples launch because it lets buyers express interest first, then pay a reservation fee only after demand is viable.

2. Jobs to be done

• Community manager: launch one handle-owned flow from story to interest to reservation.
• Buyer: understand orchard/source, June timing, transport notes, and refund terms before paying.
• Revenue / ops manager: open reservations only after threshold, watch paid buyers, and refund if the batch is cancelled.

3. Honest boundary

This flow uses only current 10x primitives. The platform handles:

• campaign attribution
• public pages
• group-buy interest capture
• threshold-gated paid-page checkout
• paid-buyer list and refunds

The platform does not handle:

• quantity-priced checkout
• automatic INR 4,00,000 procurement-cap enforcement
• shipment batches or dispatch tracking
• transport settlement
• final apple invoicing

Keep all page copy explicit that the paid step is a reservation fee, not the final produce invoice.

4. Recommended 10x object structure

Recommended groupBuy.metadata fields:

• orchardName
• originRegion
• procurementCapInr
• dispatchWindow
• transportNote
• opsOwner

Important behavior:

• publish the reservation page before traffic if you want the route live
• link a LAUNCH_THRESHOLD offer to that page
• set requireActiveInterest=true on the link if only interested visitors should be able to pay after unlock
• before the target is reached, checkout returns offer_not_unlocked
• with autoCloseOnTarget=true, reaching the target moves the group-buy to CLOSED_SUCCESS
• after threshold, no more interest submissions are accepted
• after the target is reached, checkout can stay limited to visitors with active interest when the link enables that guard

5. Roles and auth modes

• JWT owner: required for paid-page pricing and refunds.
• JWT creator/operator: campaign, group-buy, offer linking, and publish flows.
• VISITOR_COOKIE: required for interest submission and checkout.

The paid page requires ENTERPRISE in v1.

6. Creator setup flow

1. Connect Stripe and confirm the handle is on ENTERPRISE.
2. Create the campaign.
3. Create and publish the public story page.
4. Create and publish the paid reservation page with a flat fee.
5. Create the offer from that reservation page with launchMode = LAUNCH_THRESHOLD.
6. Create the group-buy with interest thresholds, shipping text, refund text, and metadata.
7. Link the offer to the group-buy.
8. Publish the group-buy and send traffic to the story page, not directly to checkout.

7. API workflow map

Use the Onboarding and API Primer first, then run the core sequence below.

export API_BASE="https://ai.10x.in"
export HANDLE="orchardclub"
export CAMPAIGN_ID="kashmir-apples-june"
export STORY_PAGE_SLUG="kashmir-apples-june-story"
export RESERVATION_PAGE_SLUG="kashmir-apples-june-reservation"
export GROUPBUY_SLUG="kashmir-apples-june"
export OFFER_ID="offer_kashmir_apples_june"

KA-01 Create the campaign

curl -sS -X POST "${API_BASE}/v2/handles/${HANDLE}/campaigns" \
  -H "authorization: Bearer ${JWT_TOKEN}" \
  -H 'content-type: application/json' \
  -d '{
    "campaignId": "kashmir-apples-june",
    "goalType": "PRODUCT_SALE",
    "status": "ACTIVE",
    "primarySlug": "kashmir-apples-june-story"
  }'

KA-02 Create the public story page

curl -sS -X POST "${API_BASE}/v2/handles/${HANDLE}/pages" \
  -H "authorization: Bearer ${JWT_TOKEN}" \
  -H 'content-type: application/json' \
  -d '{
    "pageSlug": "kashmir-apples-june-story",
    "title": "June Kashmir Apples Drop",
    "description": "Story page for the orchard, timeline, transport notes, and reservation terms.",
    "accessMode": "PUBLIC",
    "campaignId": "kashmir-apples-june",
    "content": "<h1>June Kashmir Apples</h1><p>Reservation fee opens only after the group-buy target is met.</p>",
    "teaser": "<p>Reserve your place in the June batch.</p>"
  }'

Publish it:

curl -sS -X POST "${API_BASE}/v2/handles/${HANDLE}/pages/${STORY_PAGE_SLUG}/publish" \
  -H "authorization: Bearer ${JWT_TOKEN}" \
  -H 'content-type: application/json' \
  -d '{}'

KA-03 Create the paid reservation page

curl -sS -X POST "${API_BASE}/v2/handles/${HANDLE}/pages" \
  -H "authorization: Bearer ${JWT_TOKEN}" \
  -H 'content-type: application/json' \
  -d '{
    "pageSlug": "kashmir-apples-june-reservation",
    "title": "June Kashmir Apples Reservation Fee",
    "description": "Flat reservation fee for the June apples batch.",
    "accessMode": "PAID",
    "priceAmountCents": 9900,
    "priceCurrency": "inr",
    "campaignId": "kashmir-apples-june",
    "content": "<h1>Reservation fee</h1><p>This payment reserves your allocation slot. It is not the final apple invoice.</p>",
    "teaser": "<p>Flat booking fee. Final fulfillment is handled manually after confirmation.</p>"
  }'

Publish it:

curl -sS -X POST "${API_BASE}/v2/handles/${HANDLE}/pages/${RESERVATION_PAGE_SLUG}/publish" \
  -H "authorization: Bearer ${JWT_TOKEN}" \
  -H 'content-type: application/json' \
  -d '{}'

KA-04 Create the offer and link it to the reservation page

curl -sS -X POST "${API_BASE}/v2/handles/${HANDLE}/offers" \
  -H "authorization: Bearer ${JWT_TOKEN}" \
  -H 'content-type: application/json' \
  -d '{
    "offerId": "offer_kashmir_apples_june",
    "title": "June Kashmir Apples Reservation",
    "summary": "Unlock the flat reservation fee after the demand target is met.",
    "pageSlug": "kashmir-apples-june-reservation",
    "launchMode": "LAUNCH_THRESHOLD"
  }'

KA-05 Create the group-buy

curl -sS -X POST "${API_BASE}/v2/handles/${HANDLE}/group-buys" \
  -H "authorization: Bearer ${JWT_TOKEN}" \
  -H 'content-type: application/json' \
  -d '{
    "groupBuySlug": "kashmir-apples-june",
    "title": "June Kashmir Apples Group Buy",
    "summary": "Collect quantity interest before opening the reservation fee.",
    "visibility": "PUBLIC",
    "product": {
      "productId": "kashmir-apples-june",
      "productName": "Kashmir Apples",
      "unitLabel": "box"
    },
    "pricing": {
      "currency": "INR",
      "estimatedUnitPriceCents": 280000,
      "targetUnitPriceCents": 250000
    },
    "conditions": {
      "targetInterestCount": 50,
      "targetUnits": 200,
      "minUnitsPerVisitor": 1,
      "maxUnitsPerVisitor": 10,
      "closeAt": "2026-06-15T18:30:00.000Z",
      "autoCloseOnTarget": true,
      "allowedCountries": ["IN"],
      "requireVerifiedVisitor": true
    },
    "logistics": {
      "shippingWindowText": "Expected dispatch in late June after orchard confirmation and route planning.",
      "refundPolicyText": "Reservation fees are refundable if the batch is cancelled or the operator cannot confirm allocation."
    },
    "metadata": {
      "orchardName": "South Kashmir collective",
      "originRegion": "Kashmir",
      "procurementCapInr": 400000,
      "dispatchWindow": "late-june",
      "transportNote": "Manual reefer routing confirmed after target is met."
    }
  }'

KA-06 Link the offer to the group-buy

curl -sS -X PUT "${API_BASE}/v2/handles/${HANDLE}/offers/${OFFER_ID}/group-buy" \
  -H "authorization: Bearer ${JWT_TOKEN}" \
  -H 'content-type: application/json' \
  -d '{
    "groupBuySlug": "kashmir-apples-june",
    "launchMode": "LAUNCH_THRESHOLD",
    "requireActiveInterest": true
  }'

KA-07 Publish the group-buy

curl -sS -X POST "${API_BASE}/v2/handles/${HANDLE}/group-buys/${GROUPBUY_SLUG}/publish" \
  -H "authorization: Bearer ${JWT_TOKEN}" \
  -H 'content-type: application/json' \
  -d '{}'

8. Buyer flow

1. Buyer lands on the public story page.
2. Buyer reads orchard/source, expected June window, transport note, and refund terms.
3. Buyer opens the public group-buy page.
4. Buyer authenticates with magic link if prompted.
5. Buyer submits quantity interest:

curl -sS -X POST "${API_BASE}/v2/public/group-buys/${HANDLE}/${GROUPBUY_SLUG}/interest" \
  -H "cookie: _10x_visitor=${VISITOR_COOKIE}" \
  -H "Idempotency-Key: apples-interest-001" \
  -H 'content-type: application/json' \
  -d '{
    "quantity": 4,
    "maxUnitPriceCents": 260000
  }'

1. Before threshold unlock, checkout on the reservation page returns offer_not_unlocked.
2. When the target is reached, the group-buy auto-closes as CLOSED_SUCCESS.
3. After threshold unlock, the same page can open Stripe checkout for visitors who still have active interest because the offer link enabled requireActiveInterest:

curl -sS -X POST "${API_BASE}/v2/public/pages/${HANDLE}/${RESERVATION_PAGE_SLUG}/checkout" \
  -H "cookie: _10x_visitor=${VISITOR_COOKIE}" \
  -H 'content-type: application/json' \
  -d '{
    "successUrl": "https://orchardclub.10x.in/kashmir-apples-june-reservation?checkout=success",
    "cancelUrl": "https://orchardclub.10x.in/kashmir-apples-june-reservation?checkout=cancel"
  }'

9. Ops flow and manual control points

1. Watch group-buy interest counts and units while the group-buy is still PUBLISHED.
2. When the threshold is hit, expect the group-buy to auto-close as CLOSED_SUCCESS; no more interest submissions are accepted after that point.
3. Watch paid buyers on the reservation page:

curl -sS "${API_BASE}/v2/handles/${HANDLE}/pages/${RESERVATION_PAGE_SLUG}/buyers" \
  -H "authorization: Bearer ${JWT_TOKEN}"

1. Maintain a manual procurement sheet outside native commerce. Current 10x does not calculate the INR 4,00,000 cap from buyer quantity or landed cost.
2. When the manual cap is close, stop new reservations by moving the reservation page out of PUBLISHED:

curl -sS -X PUT "${API_BASE}/v2/handles/${HANDLE}/pages/${RESERVATION_PAGE_SLUG}" \
  -H "authorization: Bearer ${JWT_TOKEN}" \
  -H 'content-type: application/json' \
  -d '{
    "status": "DRAFT"
  }'

1. If you need to stop new interest before threshold is reached, pause the group-buy while it is still PUBLISHED:

curl -sS -X POST "${API_BASE}/v2/handles/${HANDLE}/group-buys/${GROUPBUY_SLUG}/pause" \
  -H "authorization: Bearer ${JWT_TOKEN}" \
  -H 'content-type: application/json' \
  -d '{}'

1. Refund cancelled or oversold reservations:

curl -sS -X POST "${API_BASE}/v2/handles/${HANDLE}/pages/${RESERVATION_PAGE_SLUG}/refund" \
  -H "authorization: Bearer ${JWT_TOKEN}" \
  -H 'content-type: application/json' \
  -d '{
    "visitorId": "vis_123"
  }'

10. Verification checklist

• Story page is publicly reachable and says reservation fee, not final order payment.
• Group-buy details expose shippingWindowText and refundPolicyText.
• Reservation checkout is blocked with offer_not_unlocked before threshold.
• Threshold completion moves the group-buy to CLOSED_SUCCESS and unlocks checkout without changing the page slug.
• After threshold, public interest submits are no longer accepted.
• With requireActiveInterest=true, checkout rejects visitors who never submitted interest or withdrew it.
• Successful checkout adds the buyer to the reservation page buyers list.
• Refund revokes access.
• Setting the reservation page to DRAFT stops new reservations.

11. Failure modes and truthful remediation

• offer_not_unlocked during checkout:
• Expected before threshold. Verify the linked offer uses LAUNCH_THRESHOLD and the group-buy is actually published.
• Reservation page accepts payment too early:
• Check that the page is linked to exactly one offer and that the offer is not DIRECT.
• Only interested visitors should be able to reserve:
• Set requireActiveInterest=true on the linked offer-to-group-buy relation. Checkout then returns group_buy_interest_required for visitors without active interest.
• Ops cannot tell when the INR 4,00,000 cap is exceeded:
• Current platform does not calculate procurement exposure. Use a manual ops sheet and stop reservations by unpublishing the reservation page.
• Buyers assume the fee is the full apple invoice:
• Fix the copy on both the story page and reservation page. Do not imply native physical-order fulfillment.

12. Related docs

• Creator Economy
• Campaign Funnel Workflow
• Visitor Auth and Access
• UC-15: Group-Buy Lifecycle
• UC-14: Monetized Pages Checkout and Refunds