openapi: 3.1.0
info:
  title: Xoxoday Plum Rewards Authentication Balance API
  description: REST API for programmatic distribution of digital rewards including gift cards, merchandise, experiences, charity donations, lounge access, airmiles, and mobile top-ups across 150+ countries. Supports full reward lifecycle management including catalog browsing, order placement, order tracking, and payment reconciliation. Also provides APIs for reward points distribution, reward links generation, and storefront SSO integration.
  version: 1.0.0
  contact:
    url: https://developers.xoxoday.com/docs/overview
  termsOfService: https://www.xoxoday.com/terms
  license:
    name: Proprietary
    url: https://www.xoxoday.com/terms
servers:
- url: https://accounts.xoxoday.com/chef
  description: Production server
- url: https://stagingstores.xoxoday.com/chef
  description: Staging / sandbox server
security:
- oauth2ClientCredentials: []
tags:
- name: Balance
  description: Account balance retrieval
paths:
  /v1/oauth/api:
    post:
      operationId: plumApiDispatch
      summary: Plum Pro API dispatcher
      description: Single POST endpoint used by the Plum Pro API (gift cards, lounge, airmiles, merchandise, charity, and mobile top-up). The operation is determined by the `query` field in the request body.
      tags:
      - Balance
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlumRequest'
            examples:
              getFilters:
                summary: Get Filters
                value:
                  query: plumProAPI.mutation.getFilters
                  tag: plumProAPI
                  variables:
                    data:
                      filterGroupCode: country
              getVouchers:
                summary: Get Vouchers (Gift Card Catalog)
                value:
                  query: plumProAPI.mutation.getVouchers
                  tag: plumProAPI
                  variables:
                    data:
                      limit: 10
                      page: 1
              getBalance:
                summary: Get Account Balance
                value:
                  query: plumProAPI.query.getBalance
                  tag: plumProAPI
                  variables:
                    data: {}
              placeOrder:
                summary: Place Order
                value:
                  query: plumProAPI.mutation.placeOrder
                  tag: plumProAPI
                  variables:
                    data:
                      productId: 1234
                      quantity: 1
                      denomination: 500
                      poNumber: PO-001
                      notifyReceiverEmail: 1
                      notifyAdminEmail: 0
                      email: recipient@example.com
              getOrderDetails:
                summary: Get Order Details
                value:
                  query: plumProAPI.mutation.getOrderDetails
                  tag: plumProAPI
                  variables:
                    data:
                      orderId: 98765
              getOrderHistory:
                summary: Get Order History
                value:
                  query: plumProAPI.mutation.getOrderHistory
                  tag: plumProAPI
                  variables:
                    data:
                      startDate: '2024-01-01'
                      endDate: '2024-12-31'
                      limit: 10
                      page: 1
              paymentHistory:
                summary: Get Payment Report
                value:
                  query: plumProAPI.mutation.paymentHistory
                  tag: plumProAPI
                  variables:
                    data:
                      startDate: '2024-01-01'
                      endDate: '2024-12-31'
                      limit: 10
                      page: 1
              fetchPoints:
                summary: Fetch User Points Balance
                value:
                  query: storesAdmin.query.user_balance
                  tag: storeAdmin
                  variables:
                    user_data:
                      email: user@example.com
              sendPoints:
                summary: Send Reward Points
                value:
                  query: storesAdmin.mutation.sendBalance
                  tag: storeAdmin
                  variables:
                    sender_email: admin@example.com
                    expiry_month: 12
                    recipients:
                    - to_name: Jane Doe
                      to_email: jane@example.com
                      amount: '500'
                      citation: Q4 performance bonus
              cancelPoints:
                summary: Cancel Points Transaction
                value:
                  query: storesAdmin.mutation.cancelBalance
                  tag: storeAdmin
                  variables:
                    recipients_data:
                      recipients:
                      - unique_id: 5758014
      responses:
        '200':
          description: Successful API response (operation-specific payload).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlumResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '502':
          $ref: '#/components/responses/BadGateway'
components:
  responses:
    BadGateway:
      description: Upstream / internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    UnprocessableEntity:
      description: Validation error (e.g. duplicate poNumber).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    BadRequest:
      description: Bad request — invalid or missing parameters / authorization failure.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
  schemas:
    GetFiltersResult:
      type: object
      properties:
        status:
          type: integer
          description: 1 = success.
        data:
          type: array
          items:
            type: object
            properties:
              filterGroupName:
                type: string
              filterGroupDescription:
                type: string
              filterGroupCode:
                type: string
              filters:
                type: array
                items:
                  type: object
                  properties:
                    filterValue:
                      type: string
                    isoCode:
                      type: string
                    filterValueCode:
                      type: string
    GetVouchersResult:
      type: object
      properties:
        status:
          type: integer
          description: 1 = success.
        data:
          type: array
          items:
            $ref: '#/components/schemas/Voucher'
    PlaceOrderResult:
      type: object
      properties:
        status:
          type: integer
          description: 1 = success.
        data:
          type: object
          properties:
            orderId:
              type: integer
            orderStatus:
              type: string
              example: complete
            deliveryStatus:
              type: string
              example: delivered
            vouchers:
              type: array
              items:
                type: object
                properties:
                  code:
                    type: string
                  pin:
                    type: string
                  validFrom:
                    type: string
                    format: date
                  validTo:
                    type: string
                    format: date
    FetchPointsResult:
      type: object
      properties:
        success:
          type: integer
          description: 1 = success, 0 = failure.
        message:
          type: string
          nullable: true
        data:
          type: object
          nullable: true
          properties:
            total:
              type: number
              description: Total reward points balance.
    PlumRequest:
      type: object
      required:
      - query
      - tag
      - variables
      properties:
        query:
          type: string
          description: 'Operation selector. Examples: plumProAPI.mutation.getVouchers, plumProAPI.mutation.placeOrder, plumProAPI.mutation.getOrderDetails, plumProAPI.mutation.getOrderHistory, plumProAPI.mutation.paymentHistory, plumProAPI.query.getBalance, plumProAPI.mutation.getFilters, storesAdmin.mutation.sendBalance, storesAdmin.query.user_balance, storesAdmin.mutation.cancelBalance.'
        tag:
          type: string
          description: API tag group. Use "plumProAPI" for gift card operations or "storeAdmin" for points operations.
        variables:
          type: object
          description: Operation-specific parameters object.
    CancelPointsResult:
      type: object
      properties:
        error:
          type: boolean
        message:
          type: string
        recipients:
          type: array
          items:
            type: object
            properties:
              unique_id:
                type: integer
              success:
                type: boolean
              message:
                type: string
    SendPointsResult:
      type: object
      properties:
        error:
          type: boolean
        message:
          type: string
        recipients:
          type: array
          items:
            type: object
            properties:
              unique_id:
                type: integer
              points:
                type: integer
              name:
                type: string
              phone_code:
                type: string
              phone_number:
                type: string
    GetOrderDetailsResult:
      type: object
      properties:
        status:
          type: integer
          description: 1 = success.
        data:
          type: object
          properties:
            orderId:
              type: integer
            orderTotal:
              type: number
            orderDiscount:
              type: number
            discountPercent:
              type: number
            currencyCode:
              type: string
            amountCharged:
              type: number
            orderStatus:
              type: string
            deliveryStatus:
              type: string
            orderDate:
              type: string
              format: date-time
            deliveryDate:
              type: string
              format: date-time
            quantity:
              type: integer
            vouchers:
              type: array
              items:
                type: object
                properties:
                  code:
                    type: string
                  pin:
                    type: string
                  validFrom:
                    type: string
                    format: date
                  validTo:
                    type: string
                    format: date
    PlumResponse:
      type: object
      description: Generic response wrapper. The nested payload depends on the operation invoked via the query field.
      properties:
        data:
          type: object
          description: Top-level data envelope.
          properties:
            getVouchers:
              $ref: '#/components/schemas/GetVouchersResult'
            getFilters:
              $ref: '#/components/schemas/GetFiltersResult'
            getBalance:
              $ref: '#/components/schemas/GetBalanceResult'
            placeOrder:
              $ref: '#/components/schemas/PlaceOrderResult'
            getOrderDetails:
              $ref: '#/components/schemas/GetOrderDetailsResult'
            paymentHistory:
              $ref: '#/components/schemas/PaymentHistoryResult'
            sendBalance:
              $ref: '#/components/schemas/SendPointsResult'
            user_balance:
              $ref: '#/components/schemas/FetchPointsResult'
            cancelBalance:
              $ref: '#/components/schemas/CancelPointsResult'
    ApiError:
      type: object
      properties:
        error:
          type: string
        error_description:
          type: string
        code:
          type: string
        errorId:
          type: string
        errorInfo:
          type: string
    GetBalanceResult:
      type: object
      properties:
        status:
          type: integer
          description: 1 = success.
        data:
          type: object
          properties:
            value:
              type: number
              description: Available account balance.
            currency:
              type: string
              description: Currency code (e.g. INR, USD).
    PaymentHistoryResult:
      type: object
      properties:
        status:
          type: integer
        data:
          type: array
          items:
            type: object
            properties:
              invoice_number:
                type: string
              reference_id:
                type: string
              date:
                type: string
                format: date
              reason:
                type: string
              adjusted_amount:
                type: integer
              transaction_status:
                type: string
                enum:
                - Complete
                - Cancelled
              closing_balance:
                type: integer
    Voucher:
      type: object
      properties:
        productId:
          type: integer
        name:
          type: string
        description:
          type: string
        minValue:
          type: number
        maxValue:
          type: number
        valueDenominations:
          type: string
          description: Comma-separated list of allowed denominations.
        fee:
          type: number
        discount:
          type: number
        countryCode:
          type: string
        countryName:
          type: string
        currencyCode:
          type: string
        termsAndConditionsInstructions:
          type: string
        expiryAndValidity:
          type: string
        deliveryType:
          type: string
        tatInDays:
          type: integer
        usageType:
          type: string
        imageUrl:
          type: string
          format: uri
        loyaltyName:
          type: string
        productMeta:
          type: string
          description: JSON string with additional product metadata.
  securitySchemes:
    oauth2ClientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://accounts.xoxoday.com/chef/v1/oauth/token
          scopes: {}
    bearerAuth:
      type: http
      scheme: bearer