openapi: 3.1.1
info:
  title: Mews Loyalty Reverse API
  description: |
    This document describes an API which needs to be implemented by the loyalty program provider.
  version: 2025.08.11
  summary: Reverse API to be implemented by loyalty program providers
  contact:
    name: Mews Partner Success
    email: partnersuccess@mews.com
    url: 'https://www.mews.com/en/partnerships'
  termsOfService: 'https://www.mews.com/en/terms-conditions/master'
tags:
  - name: Members
    description: Operations related to working with customers who are members of provider's loyalty program.
  - name: Memberships
    description: Operations related to working with customers' membership details, i.e. linking loyalty program members to Mews customers and retrieving point values and tiers.
servers:
  - url: '[provider]'
    description: Provider server
security:
  - bearerAuth: []
paths:
  /members/search:
    post:
      tags:
        - Members
      summary: Search members
      description: |-
        Search members based on customer information provided by Mews PMS.

        Mews PMS will use this operation to display existing members based on customer-provided data. All available customer data is sent.
      operationId: searchMembers
      parameters:
        - $ref: '#/components/parameters/acceptLanguage'
      requestBody:
        description: Find members using customer details.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/searchMembersRequest'
            example:
              mewsEnterpriseId: 123e4567-e89b-12d3-a456-426614174000
              providerEnterpriseId: ENT-9876-AZ
              memberFilter:
                email: john.doe@example.com
                firstName: John
                lastName: Doe
      responses:
        '200':
          description: Search result with list of matching members.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/searchMembersResponse'
              example:
                isPartialResult: false
                data:
                  - firstName: John
                    lastName: Doe
                    membership:
                      providerMembershipId: MEMB-123456-ABC123
                      membershipNumber: M-123-72ca09f4
                      status: enrolled
        '400':
          description: 'Bad Request - Returned when the request is invalid, such as missing required fields or containing data in an incorrect format (e.g., an improperly formatted email).'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/problemDetail'
              example:
                type: https://purl.mews.com/problem/loyalty/invalid-member-search-criteria
                title: Invalid search criteria
                status: 400
                detail: First name and last name are required for member search.
                errors:
                  - type: https://purl.mews.com/problem/core/field-required
                    pointer: "#/memberFilter/firstName"
                    detail: First name is required for member search.
                  - type: https://purl.mews.com/problem/core/field-required
                    pointer: "#/memberFilter/lastName" 
                    detail: Last name is required for member search.
        '401':
          $ref: '#/components/responses/unauthorized'
        '408':
          $ref: '#/components/responses/requestTimeout'
        '422':
          description: 'Unprocessable Content - Used when the request is syntactically valid but fails due to business logic constraints, such as required parameter combinations or insufficient search parameters.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/problemDetail'
              example:
                type: https://purl.mews.com/problem/core/unprocessable-entity
                title: Unprocessable Content
                status: 422
                detail: The request could not be processed due to business validation rules.
                errors:
                  - type: https://purl.mews.com/problem/core/field-required
                    pointer: "#/memberFilter"
                    detail: At least one valid filter parameter must be provided.
        '500':
          $ref: '#/components/responses/internalServerError'
  /members:
    post:
      tags:
        - Members
      summary: Enroll a customer
      description: Enrolls a customer from Mews into the provider's loyalty system by creating a new loyalty membership.
      operationId: enrollCustomer
      parameters:
        - $ref: '#/components/parameters/acceptLanguage'
      requestBody:
        description: Enrolls a customer in the loyalty program.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/enrollCustomerRequest'
            example:
              mewsEnterpriseId: 123e4567-e89b-12d3-a456-426614174000
              providerEnterpriseId: ENT-9876-AZ
              customer:
                mewsCustomerId: 550e8400-e29b-41d4-a716-446655440000
                firstName: John
                lastName: Doe
                address:
                  city: New York
      responses:
        '200':
          description: 'Enrollment was accepted, member is successfully enrolled or their membership is pending.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/enrollCustomerResponse'
              example:
                data:
                  providerMembershipId: MEMB-123456-ABC123
                  membershipNumber: M-123-72ca09f4
                  status: pending
        '400':
          description: 'Bad Request - Returned when the enrollment request is invalid, such as missing required fields or containing data in an incorrect format.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/problemDetail'
              example:
                type: https://purl.mews.com/problem/core/bad-request
                title: Invalid customer data
                status: 400
                detail: Some of the customer data is either missing or is invalid.
                errors:
                  - type: https://purl.mews.com/problem/core/field-required
                    pointer: "#/customer/email"
                    detail: Email is required.
        '401':
          $ref: '#/components/responses/unauthorized'
        '408':
          $ref: '#/components/responses/requestTimeout'
        '422':
          description: Unprocessable Entity
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/problemDetail'
              example:
                type: https://purl.mews.com/problem/core/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The enrollment was declined due to validation errors.
                errors:
                  - type: https://purl.mews.com/problem/core/field-email-invalid
                    pointer: "#/email"
                    detail: The provided email address is invalid.
        '500':
          $ref: '#/components/responses/internalServerError'
  /memberships/list:
    post:
      tags:
        - Memberships
      summary: List memberships by IDs
      description: Fetch the latest details of loyalty memberships from the provider's system using memberships' unique IDs.
      operationId: listMemberships
      parameters:
        - $ref: '#/components/parameters/acceptLanguage'
      requestBody:
        description: Retrieves loyalty memberships matching the provided provider membership IDs.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/listMembershipsRequest'
            example:
              providerMembershipIds:
                - MEMB-845329-JK92A
                - MEMB-423678-BR42A
              mewsEnterpriseId: 123e4567-e89b-12d3-a456-426614174000
              providerEnterpriseId: ENT-9876-AZ
      responses:
        '200':
          description: |-
            List matching memberships.

            If a membership with requested `providerMembershipId` is not found in the result set, it will be requested again later.

            Memberships with `status` of `notFound` will be removed on Mews' side.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/listMembershipsResponse'
              example:
                data:
                  - providerMembershipId: MEMB-845329-JK92A
                    membershipNumber: M-845-329JK92A
                    status: enrolled
                  - providerMembershipId: MEMB-423678-BR42A
                    membershipNumber: M-423-678BR42A
                    status: enrolled
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '408':
          $ref: '#/components/responses/requestTimeout'
        '422':
          description: 'Unprocessable Content - Used when the request is syntactically valid but fails due to business logic constraints.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/problemDetail'
              example:
                type: https://purl.mews.com/problem/core/unprocessable-entity
                title: Unprocessable Content
                status: 422
                detail: The request could not be processed due to business validation rules.
                errors:
                  - type: https://purl.mews.com/problem/core/field-required
                    pointer: "#/providerMembershipIds"
                    detail: At least one provider membership ID must be provided.
        '500':
          $ref: '#/components/responses/internalServerError'
  /memberships/link:
    put:
      tags:
        - Memberships
      summary: Link or unlink membership
      description: Links or unlinks a Mews customer to an existing membership in the loyalty program.
      operationId: updateMembershipLink
      parameters:
        - $ref: '#/components/parameters/acceptLanguage'
      requestBody:
        description: Request payload containing the membership ID, customer ID, and link status.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/linkMembershipRequest'
            example:
              mewsEnterpriseId: 123e4567-e89b-12d3-a456-426614174000
              providerEnterpriseId: ENT-9876-AZ
              providerMembershipId: MEMB-123456-ABC123
              mewsCustomerId: 550e8400-e29b-41d4-a716-446655440000
              isLinked: true
      responses:
        '200':
          description: 'Link operation was successful.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Indicates if the link operation was successful.
                    examples:
                      - true
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '408':
          $ref: '#/components/responses/requestTimeout'
        '422':
          description: 'Unprocessable Content - Used when the link operation is syntactically valid but fails due to business logic constraints.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/problemDetail'
              example:
                type: https://purl.mews.com/problem/core/unprocessable-entity
                title: Unprocessable Content
                status: 422
                detail: The link operation could not be processed due to business validation rules.
                errors:
                  - type: https://purl.mews.com/problem/core/field-required
                    pointer: "#/providerMembershipId"
                    detail: Provider membership ID is required for linking.
        '500':
          $ref: '#/components/responses/internalServerError'
components:
  responses:
    unauthorized:
      description: Unauthorized
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/problemDetail'
          example:
            type: https://purl.mews.com/problem/core/unauthorized
            title: Unauthorized
            status: 401
            detail: Bearer token is missing or invalid
    requestTimeout:
      description: Request Timeout
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/problemDetail'
          example:
            type: https://purl.mews.com/problem/core/request-timeout
            title: Request Timeout
            status: 408
            detail: The server timed out waiting for the request
    internalServerError:
      description: Internal Server Error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/problemDetail'
          example:
            type: https://purl.mews.com/problem/core/internal-server-error
            title: Internal Server Error
            status: 500
            detail: An unexpected error occurred on the server. Please try again later.
    badRequest:
      description: 'Bad Request - Returned when the request is invalid, such as missing required fields or containing data in an incorrect format.'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/problemDetail'
          example:
            type: https://purl.mews.com/problem/core/bad-request
            title: Bad Request
            status: 400
            detail: The request is invalid due to missing or incorrect data.
  parameters:
    acceptLanguage:
      name: Accept-Language
      in: header
      description: |
        Language preference for error messages and descriptions.
        If not provided, English will be used as the default language.
      schema:
        type: string
        examples:
          - "en-US"
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token provided by loyalty program provider.
  schemas:
    memberFilter:
      type: object
      description: Filter criteria for searching loyalty members. At least one valid filter combination must be provided.
      additionalProperties: false
      properties:
        providerMembershipId:
          type: string
          description: Unique identifier for the membership in the provider's system.
          examples:
            - "MEMB-123456-ABC123"
        membershipNumber:
          type: string
          description: Membership number assigned by the loyalty program.
          examples:
            - "M-123-72ca09f4"
        email:
          type: string
          format: email
          maxLength: 255
          description: Customer's email address for searching.
          examples:
            - "john.doe@example.com"
        firstName:
          type: string
          maxLength: 255
          description: Customer's first name for searching.
          examples:
            - "John"
        lastName:
          type: string
          maxLength: 255
          description: Customer's last name for searching.
          examples:
            - "Doe"
        phoneNumber:
          type: string
          description: Customer's phone number for searching.
          examples:
            - "+1-555-123-4567"
        city:
          type: string
          maxLength: 255
          description: Customer's city.
          examples:
            - "New York"
        postalCode:
          type: string
          maxLength: 255
          description: Customer's postal code.
          examples:
            - "10001"
        countryCode:
          type: string
          description: ISO 3166-1 code of the country.
          examples:
            - "US"
      examples:
        - email: "john.doe@example.com"
          firstName: "John"
          lastName: "Doe"
          city: "New York"
          countryCode: "US"
      anyOf:
        - title: "Email filter"
          required:
            - email
        - title: "Membership number filter"
          required:
            - membershipNumber
        - title: "Provider membership ID filter"
          required:
            - providerMembershipId
        - title: "Name filter"
          required:
            - firstName
            - lastName
        - title: "Location filter"
          required:
            - lastName
            - city
            - countryCode
    membership:
      type: object
      description: Contains membership information including provider membership ID, membership number, tier, points, and current status.
      additionalProperties: false
      required:
        - providerMembershipId
        - membershipNumber
        - status
      properties:
        providerMembershipId:
          $ref: '#/components/schemas/providerMembershipId'
        membershipNumber:
          $ref: '#/components/schemas/membershipNumber'
        tier:
          type: string
          maxLength: 50
        points:
          type: integer
        status:
          type: string
          minLength: 1
          enum:
            - pending
            - enrolled
            - canceled
            - declined
            - notFound
        expiresAt:
          type: string
          format: date-time
        deeplinkUrl:
          type: string
          format: uri
    enrollmentMembership:
      description: Membership information returned when enrolling a customer, extending the base membership with enrollment-specific details.
      allOf:
        - $ref: '#/components/schemas/membership'
        - type: object
          required:
            - status
          properties:
            status: # Overriding status property from the base membership schema
              type: string
              minLength: 1
              enum:
                - pending
                - enrolled
      examples:
        - providerMembershipId: MEMB-123456-ABC123
          membershipNumber: M-123-72ca09f4
          tier: Bronze
          points: 0
          status: pending
          expiresAt: "2026-12-31T23:59:59Z"
          deeplinkUrl: "https://loyaltyportal.example.com/member/M-123-72ca09f4"
    searchMembership:
      description: Membership information returned in search results, extending the base membership with search-specific details.
      allOf:
        - $ref: '#/components/schemas/membership'
        - type: object
          required:
            - status
          properties:
            status: # Overriding status property from the base membership schema
              type: string
              minLength: 1
              enum:
                - pending
                - enrolled
                - canceled
                - declined
    customer:
      type: object
      title: Mews Customer
      description: Contains personal and contact information about a customer, including their unique Mews identifier used for referencing within the Mews platform.
      required:
        - mewsCustomerId
        - firstName
        - lastName
      properties:
        mewsCustomerId:
          type: string
          minLength: 1
          format: uuid
          examples:
            - '550e8400-e29b-41d4-a716-446655440000'
        firstName:
          type: string
          minLength: 1
          maxLength: 255
          examples:
            - John
        lastName:
          type: string
          minLength: 1
          maxLength: 255
          examples:
            - Doe
        email:
          type: string
          format: email
          maxLength: 255
          examples:
            - john.doe@example.com
        birthday:
          type: string
          format: date
          description: Customer's date of birth in ISO 8601 format (YYYY-MM-DD)
          examples:
            - '1986-11-08'
        phoneNumber:
          type: string
          examples:
            - '+123456789'
        address:
          $ref: '#/components/schemas/address'
    address:
      type: object
      description: Physical address information including street address, city, postal code, and country details.
      additionalProperties: false
      properties:
        line1:
          type: string
          maxLength: 1023
          examples:
            - 123 Main St
        line2:
          type: string
          maxLength: 255
          examples:
            - Apt 4B
        city:
          type: string
          maxLength: 255
          examples:
            - Sample City
        postalCode:
          type: string
          examples:
            - '12345'
        countryCode:
          type: string
          examples:
            - US
        countrySubdivisionCode:
          type: string
          examples:
            - CA
      title: Customer address
    member:
      type: object
      title: Loyalty program member
      description: Represents a customer who is part of a loyalty program. This object combines personal details with loyalty membership information.
      required:
        - firstName
        - lastName
        - membership
      properties:
        firstName:
          type: string
          minLength: 1
          maxLength: 255
          examples:
            - John
        lastName:
          type: string
          minLength: 1
          maxLength: 255
          examples:
            - Doe
        email:
          type: string
          format: email
          maxLength: 255
          examples:
            - john.doe@example.com
        birthday:
          type: string
          format: date
          description: User's date of birth in ISO 8601 format (YYYY-MM-DD)
          examples:
            - '1986-11-08'
        phoneNumber:
          type: string
          examples:
            - '+123456789'
        address:
          $ref: '#/components/schemas/address'      
        membership:
          $ref: '#/components/schemas/searchMembership'
      examples:
        - firstName: John
          lastName: Doe
          email: john.doe@example.com
          phoneNumber: '+123456789'
          birthday: '1986-11-08'
          address:
            line1: 123 Main St
            line2: Apt 4B
            city: Sample City
            postalCode: '12345'
            countryCode: US
            countrySubdivisionCode: CA
          membership:
            providerMembershipId: MEMB-123456-ABC123
            membershipNumber: M-123-72ca09f4
            tier: Gold
            points: 2500
            status: enrolled
            expiresAt: '2026-12-31T23:59:59Z'
            deeplinkUrl: 'https://loyaltyportal.example.com/member/M-123-72ca09f4'
    problemDetail:
      type: object
      additionalProperties: true
      description: 'A standardized format for problem details following [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457).'
      title: Problem details
      required:
        - type
        - status
        - title
        - detail
      properties:
        type:
          type: string
          minLength: 1
          description: A URI reference that identifies the problem type. Can be any URI or one of the predefined error types.
          anyOf:
            - title: Predefined Problem Types
              type: string
              enum:
                - https://purl.mews.com/problem/core/not-found
                - https://purl.mews.com/problem/core/bad-request
                - https://purl.mews.com/problem/core/unprocessable-content
                - https://purl.mews.com/problem/core/unauthorized
                - https://purl.mews.com/problem/core/request-timeout
                - https://purl.mews.com/problem/core/too-many-requests
                - https://purl.mews.com/problem/core/internal-server-error
                - https://purl.mews.com/problem/loyalty/invalid-member-search-criteria
            - title: Custom Problem Type URI
              type: string
              format: uri
          examples:
            - https://purl.mews.com/problem/core/bad-request
        title:
          type: string
          minLength: 1
          maxLength: 255
          description: 'A short, human-readable summary of the problem type.'
          examples:
            - Invalid customer data
        status:
          type: integer
          description: The HTTP status code generated by the origin server for this occurrence of the problem.
          minimum: 100
          maximum: 599
          examples:
            - 404
        detail:
          type: string
          minLength: 1
          description: A human-readable explanation specific to this occurrence of the problem.
          examples:
            - Some of the customer data is either missing or is invalid.
        instance:
          type: string
          format: uri
          description: A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
          examples:
            - tag:example.com,2025-07-10:error:12345
        errors:
          type: array
          description: An array of field-level error details, typically used to describe validation failures or missing/invalid input fields.
          items:
            type: object
            additionalProperties: false
            required:
              - type
              - pointer
            properties:
              type:
                type: string
                minLength: 1
                description: A URI reference that identifies the field-level error type. Can be any URI or one of the predefined error types.
                anyOf:
                  - title: Custom Field Error Type URI
                    type: string
                    format: uri
                  - title: Predefined Field Error Types
                    type: string
                    enum:
                      - https://purl.mews.com/problem/core/field-required
                      - https://purl.mews.com/problem/core/field-invalid-format
                      - https://purl.mews.com/problem/core/field-too-short
                      - https://purl.mews.com/problem/core/field-too-long
                      - https://purl.mews.com/problem/core/field-out-of-range
                      - https://purl.mews.com/problem/core/field-invalid-type
                      - https://purl.mews.com/problem/core/field-not-allowed-value
                      - https://purl.mews.com/problem/core/field-duplicate
                      - https://purl.mews.com/problem/core/field-email-invalid
                examples:
                  - https://purl.com/errors/field-required
              pointer:
                type: string
                description: JSON Pointer to the field that has an error. See [RFC 6901](https://datatracker.ietf.org/doc/html/rfc6901) for the JSON Pointer specification.
                minLength: 1
                maxLength: 255
                examples:
                  - "#/email"
              detail:
                type: string
                description: A human-readable message describing the error.
                maxLength: 500
                examples:
                  - Email is required for enrollment
          examples:
            - - pointer: "#/email"
                type: https://purl.mews.com/field-required
                detail: Email is required for enrollment.
              - pointer: "#/phoneNumber"
                type: https://purl.mews.com/invalid-format
                detail: Phone number format is invalid.
    membershipNumber:
      type: string
      title: Membership number
      description: 'Member code or number, typically on loyalty card.'
    mewsCustomerId:
      type: string
      format: uuid
      title: Mews customer Identifier
      description: Unique identifier of customer account in Mews. Can be used in Connector API.
      examples:
        - "550e8400-e29b-41d4-a716-446655440000"
    mewsEnterpriseId:
      title: Mews Enterprise Identifier
      type: string
      format: uuid
      description: The identifier of the Mews enterprise on whose behalf the request has been made.
      examples:
        - "123e4567-e89b-12d3-a456-426614174000"
    providerEnterpriseId:
      title: Provider Enterprise Identifier
      type: string
      description: An optional identifier of the enterprise from the loyalty provider on whose behalf the request has been made.
      examples:
        - "ENT-9876-AZ"
    providerMembershipId:
      type: string
      title: Provider membership Identifier
      description: Unique internal identifier of membership from the loyalty provider. Can be the same as `membershipNumber` if no other value is needed.
      maxLength: 50
      examples:
        - M-123-72ca09f4
    searchMembersRequest:
      type: object
      description: Request payload for searching loyalty program members based on customer information from Mews PMS.
      additionalProperties: false
      required:
        - mewsEnterpriseId
        - memberFilter
      properties:
        mewsEnterpriseId:
          $ref: '#/components/schemas/mewsEnterpriseId'
        providerEnterpriseId:
          $ref: '#/components/schemas/providerEnterpriseId'
        memberFilter:
          $ref: '#/components/schemas/memberFilter'
    enrollCustomerRequest:
      type: object
      description: Request payload for enrolling a customer from Mews into the provider's loyalty program.
      additionalProperties: false
      required:
        - customer
        - mewsEnterpriseId
      properties:
        customer:
          allOf:
            - $ref: '#/components/schemas/customer'
          examples:
            - mewsCustomerId: 550e8400-e29b-41d4-a716-446655440000
              firstName: John
              lastName: Doe
              email: john.doe@example.com
              birthday: '1986-11-08'
              phoneNumber: '+123456789'
              address:
                line1: 123 Main St
                line2: Apt 4B
                city: Sample City
                postalCode: '12345'
                countryCode: US
                countrySubdivisionCode: CA
        mewsEnterpriseId:
          $ref: '#/components/schemas/mewsEnterpriseId'
        providerEnterpriseId:
          $ref: '#/components/schemas/providerEnterpriseId'
    linkMembershipRequest:
      type: object
      description: Request payload for linking or unlinking a Mews customer to an existing membership in the loyalty program.
      additionalProperties: false
      required:
        - mewsEnterpriseId
        - providerMembershipId
        - mewsCustomerId
        - isLinked
      properties:
        mewsEnterpriseId:
          $ref: '#/components/schemas/mewsEnterpriseId'
        providerMembershipId:
          allOf:
            - $ref: '#/components/schemas/providerMembershipId'
          examples:
            - MEMB-123456-ABC123
        providerEnterpriseId:
          $ref: '#/components/schemas/providerEnterpriseId'
        mewsCustomerId:
          $ref: '#/components/schemas/mewsCustomerId'
        isLinked:
          type: boolean
          description: |-
            `true` if the customer is linked to the membership, `false` if unlinked.

            Providers may delete unlinked memberships; for purposes of this API it's not necessary to keep them stored on provider's side.
          examples:
            - true
    listMembershipsRequest:
      type: object
      description: Request payload for fetching the latest details of loyalty memberships using their unique provider IDs.
      additionalProperties: false
      required:
        - mewsEnterpriseId
        - providerMembershipIds
      properties:
        mewsEnterpriseId:
          $ref: '#/components/schemas/mewsEnterpriseId'
        providerEnterpriseId:
          $ref: '#/components/schemas/providerEnterpriseId'
        providerMembershipIds:
          type: array
          minItems: 1
          maxItems: 100
          items:
            $ref: '#/components/schemas/providerMembershipId'
          description: Array of membership IDs to retrieve.
          examples:
            - - MEMB-845329-JK92A
              - MEMB-423678-BR42A
    searchMembersResponse:
      type: object
      description: Response payload containing search results with matching loyalty program members.
      additionalProperties: false
      required:
        - isPartialResult
        - data
      properties:
        isPartialResult:
          type: boolean
          description: 'If the number of matching results exceeds the allowed maximum number of result items (10), set `isPartialResult` to `true` to indicate an incomplete result set.'
          examples:
            - false
        data:
          type: array
          maxItems: 10
          description: Array of matching members.
          items:
            $ref: '#/components/schemas/member'
          examples:
            - - firstName: John
                lastName: Doe
                email: john.doe@example.com
                phoneNumber: '+123456789'
                address:
                  line1: 123 Main St
                  city: New York
                  countryCode: US
                membership:
                  providerMembershipId: MEMB-123456-ABC123
                  membershipNumber: M-123-72ca09f4
                  tier: Gold
                  points: 1500
                  status: enrolled
                  expiresAt: "2026-12-31T23:59:59Z"
                  deeplinkUrl: "https://loyaltyportal.example.com/member/M-123-72ca09f4"
              - firstName: Jane
                lastName: Smith
                email: jane.smith@example.com
                membership:
                  providerMembershipId: MEMB-789012-XYZ789
                  membershipNumber: M-789-012XYZ789
                  tier: Bronze
                  points: 150
                  status: enrolled
                  expiresAt: "2026-12-31T23:59:59Z"
    enrollCustomerResponse:
      type: object
      description: Response payload containing the newly created or updated membership information after enrollment.
      additionalProperties: false
      required:
        - data
      properties:
        data:
          $ref: '#/components/schemas/enrollmentMembership'
    listMembershipsResponse:
      type: object
      description: Response payload containing an array of membership details for the requested provider membership IDs.
      additionalProperties: false
      required:
        - data
      properties:
        data:
          type: array
          minItems: 1
          maxItems: 100
          description: 'Array of matching memberships, if any membership is not found, return it with state `notFound`.'
          items:
            $ref: '#/components/schemas/membership'
          examples:
            - - providerMembershipId: MEMB-845329-JK92A
                membershipNumber: M-845-329JK92A
                tier: Gold
                points: 2500
                status: enrolled
                expiresAt: "2026-12-31T23:59:59Z"
                deeplinkUrl: "https://loyaltyportal.example.com/member/M-845-329JK92A"
              - providerMembershipId: MEMB-423678-BR42A
                membershipNumber: M-423-678BR42A
                tier: Silver
                points: 1200
                status: enrolled
                expiresAt: "2026-12-31T23:59:59Z"
                deeplinkUrl: "https://loyaltyportal.example.com/member/M-423-678BR42A"
