openapi: 3.1.1
info:
  title: RetailContract Schema
  version: "2.1.0"
  description: Contract-level buyer preferences and terms for retail transactions
  x-jsonld-context: ./context.jsonld
  x-jsonld-vocab: ./vocab.jsonld

paths: {}

components:
  schemas:
    RetailContract:
      type: object
      description: Container for retail contract attributes (migrated from v2 orderAttributes)
      x-beckn-container: contractAttributes
      x-jsonld:
        "@type": "rcca:RetailContract"
        "@context": "https://schema.nfh.global/RetailContract/v2.1/context.jsonld"
      properties:
        quoteReference:
          type: string
          description: >
            Reference to the quote or pro-forma invoice that preceded this contract.
            May carry a quote number (e.g. "Q-2024-00123") or a URI pointing to the
            quote document. Relevant for B2B and made-to-order patterns where a formal
            quote is agreed before the order is confirmed.
          x-jsonld-id: "rcca:quoteReference"
        buyerInstructions:
          type: string
          description: Free-text instructions from buyer to provider
          x-jsonld-id: "rcca:buyerInstructions"
        deliveryPreferences:
          type: object
          description: Buyer delivery preferences and constraints
          x-jsonld-id: "rcca:deliveryPreferences"
          properties:
            leaveAtDoor:
              type: boolean
              description: Permission to leave delivery at door without signature
              x-jsonld-id: "rcca:leaveAtDoor"
            contactless:
              type: boolean
              description: Request for contactless delivery
              x-jsonld-id: "rcca:contactless"
            preferredTimeSlot:
              type: object
              description: Preferred delivery time window
              x-jsonld-id: "rcca:preferredTimeSlot"
              properties:
                start:
                  type: string
                  format: date-time
                  description: Start of preferred delivery window
                  x-jsonld-id: "rcca:timeSlotStart"
                end:
                  type: string
                  format: date-time
                  description: End of preferred delivery window
                  x-jsonld-id: "rcca:timeSlotEnd"
        gift:
          type: object
          description: Gift-related attributes and preferences
          x-jsonld-id: "rcca:gift"
          properties:
            isGift:
              type: boolean
              description: Whether this order is being sent as a gift
              x-jsonld-id: "rcca:isGift"
            message:
              type: string
              description: Gift message to include
              x-jsonld-id: "rcca:giftMessage"
            wrap:
              type: boolean
              description: Whether to include gift wrapping
              x-jsonld-id: "rcca:giftWrap"
        invoicePreferences:
          type: object
          description: Invoice and billing preferences
          x-jsonld-id: "rcca:invoicePreferences"
          properties:
            taxId:
              type: object
              description: Tax identification details
              x-jsonld-id: "rcca:taxId"
              required:
                - value
              properties:
                scheme:
                  description: >
                    Tax identification scheme. Use canonical global values where possible
                    to ensure cross-network interoperability. Market-specific schemes not
                    listed here (e.g. NPWP for Indonesia, GSTIN for India, SSN for the US)
                    are accepted via the second branch using UPPERCASE_UNDERSCORE convention.
                    L2 schema authors SHOULD promote frequently used market values to typed
                    enums in their extensions.
                  anyOf:
                    - type: string
                      title: Canonical global scheme
                      enum:
                        - GST    # Goods and Services Tax (India, Australia, Canada, NZ, Singapore)
                        - VAT    # Value Added Tax (EU, UK, and most other markets)
                        - PAN    # Permanent Account Number (India)
                        - TIN    # Tax Identification Number (generic; used in US, EU, and others)
                        - EIN    # Employer Identification Number (US)
                        - ABN    # Australian Business Number
                        - OTHER  # Any scheme not listed above; use value field for detail
                    - type: string
                      title: Market-specific scheme
                      pattern: '^[A-Z][A-Z0-9_]*$'
                      description: >
                        Market-specific tax ID scheme identifier in UPPERCASE_UNDERSCORE
                        (e.g. NPWP, GSTIN, NIK, SSN). L2 schema authors should promote
                        frequently used values to typed enums in their extensions.
                  x-jsonld-id: "rcca:taxIdScheme"
                country:
                  type: string
                  pattern: '^[A-Z]{2}$'
                  description: ISO 3166-1 alpha-2 country code
                  x-jsonld-id: "rcca:taxIdCountry"
                value:
                  type: string
                  description: Tax ID value (required)
                  x-jsonld-id: "rcca:taxIdValue"
            companyName:
              type: string
              description: Company name for invoice
              x-jsonld-id: "rcca:invoiceCompanyName"
            email:
              type: string
              format: email
              description: Email address for invoice delivery
              x-jsonld-id: "rcca:invoiceEmail"
        loyalty:
          type: object
          description: Loyalty program participation and rewards
          x-jsonld-id: "rcca:loyalty"
          properties:
            programId:
              type: string
              description: Loyalty program identifier
              x-jsonld-id: "rcca:loyaltyProgramId"
            pointsRedeemed:
              type: number
              minimum: 0
              description: Number of loyalty points redeemed in this transaction
              x-jsonld-id: "rcca:pointsRedeemed"
        source:
          type: object
          description: Transaction source and marketing attribution
          x-jsonld-id: "rcca:source"
          properties:
            channel:
              type: string
              enum: [WEB, MOBILE_APP, API, IN_STORE, VOICE, SOCIAL_COMMERCE, STREAMING_COMMERCE, OTHER]
              description: >
                Channel through which this transaction was sourced. MOBILE_APP refers to
                a native application (distinct from a mobile browser session under WEB).
                Use OTHER for channels not listed here.
              x-jsonld-id: "rcca:sourceChannel"
            campaignId:
              type: string
              description: Marketing campaign identifier
              x-jsonld-id: "rcca:campaignId"