Documentation
Documentation
https://developers.xoxoday.com/docs/overview
Authentication
https://developers.xoxoday.com/docs/authentication-2
OpenAPI Specification
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