RetailContract Schema Pack v2.1

Overview

RetailContract is a Beckn v2.1 schema pack that declares buyer preferences, special instructions, and transaction terms at the contract (order) level. This schema was **migrated directly from v2's RetailCoreOrderAttributes** with no structural changes, establishing buyer-side terms and preferences for fulfillment execution.

The schema enables buyers to specify:

• **Special instructions** for the provider
• **Delivery preferences** (timing, contactless, leave-at-door options)
• **Gift attributes** (gift wrapping, personalized messages)
• **Invoice preferences** (tax ID, company name, email)
• **Loyalty program** participation and points redemption
• **Source attribution** for marketing and analytics

Attachment Points

This schema attaches to the following Beckn v2.0 core entities via the contractAttributes container:

• **Contract**: High-level buyer terms and preferences
• **Order** (legacy naming): Buyer-side special instructions and delivery preferences
• **Fulfillment**: Fulfillment-specific buyer constraints

Schema Structure

Design Rationale

Field Semantics

**buyerInstructions**: Free-text field for any buyer-to-provider communication that doesn't fit structured fields. Examples: "Please ring the doorbell twice," "Avoid green bell peppers," "Call before arriving."

**deliveryPreferences**: Three distinct boolean flags provide granular control:

• leaveAtDoor: Override signature/contact requirement
• contactless: Explicitly request no-contact delivery (e.g., during health crises)
• preferredTimeSlot: Time-bounded delivery window for convenience or availability

**gift**: Separates transactional purchase (invoicePreferences) from gift context:

• isGift: Enables gift-specific handling
• message: Personalized text (max length implementation-dependent)
• wrap: Boolean for premium presentation

**invoicePreferences**: Supports both B2C and B2B transactions:

• taxId: Multi-jurisdiction support via scheme and country codes
• companyName: For B2B invoicing
• email: PDF invoice delivery destination

**loyalty**: Enables rewards redemption at transaction time:

• programId: Links to buyer's loyalty account
• pointsRedeemed: Credits points used for discounts/benefits

**source**: Supports marketing analytics and attribution modeling:

• channel: Acquisition source (organic, paid, referral, etc.)
• campaignId: Campaign-specific tracking for A/B testing and ROI

Non-Goals

This schema does **not**:

• Define loyalty program mechanics (point structure, tiers, rules)
• Enforce tax compliance or validation (that's provider/market responsibility)
• Specify delivery success metrics or outcomes (see Fulfillment)
• Model buyer communication preferences (see a separate PreferencesAttributes schema)
• Encode pricing or surcharge logic
• Define payment method preferences (see PaymentAttributes)

Upstream Candidates

Future enhancement opportunities for v2.2+:

1. **Communication Preferences**: communicationChannel (sms, email, whatsapp) for delivery updates 2. **Sustainability Preferences**: ecoPreferences: {minimalPackaging: boolean, sustainableMaterials: boolean} 3. **Insurance Election**: insuranceOptIn: boolean, insuranceType: enum 4. **Subscription Metadata**: isSubscription: boolean, subscriptionId: string, nextBillingDate: date-time 5. **Recurring Instructions**: recurringInstructions: {frequency: string, startDate: date-time, endDate: date-time} 6. **Recipient Details**: recipientName: string, recipientPhone: string for sender ≠ receiver 7. **Dietary/Allergy Info**: dietaryRequirements: array, allergies: array (F&B specific but generalizable) 8. **Regional Tax Handling**: reverseChargeApplicable: boolean, placeOfSupply: string 9. **Payment Terms**: paymentTerms: {creditDays: number, dueDate: date} for B2B 10. **Notification Preferences**: notificationSettings: {email: boolean, sms: boolean, push: boolean}