schema-aggregator

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}