REST API for programmatic distribution of digital rewards including gift cards, merchandise, experiences, charity donations, lounge access, airmiles, and mobile top-ups. Supports full reward lifecycle management including catalog browsing, order placement, order tracking, and payment reconciliation.
openapi: 3.1.0
info:
title: Xoxoday Plum Rewards 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: Authentication
description: Token generation, validation, and refresh
- name: Gift Cards
description: Browse and order gift card vouchers
- name: Orders
description: Order placement, tracking, and history
- name: Balance
description: Account balance retrieval
- name: Payments
description: Payment report and transaction history
- name: Reward Points
description: Send, fetch, and cancel reward points
- name: Reward Links
description: Generate and send personalized reward links
paths:
/v1/oauth/token:
post:
operationId: getAccessToken
summary: Get Access Token
description: >-
Obtain an OAuth 2.0 access token using client credentials. The token is
required for all subsequent API calls and expires after the duration
indicated in the response.
tags:
- Authentication
security: []
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- grant_type
- client_id
- client_secret
properties:
grant_type:
type: string
enum:
- client_credentials
description: OAuth 2.0 grant type.
client_id:
type: string
description: Your API client ID.
client_secret:
type: string
description: Your API client secret.
responses:
'200':
description: Access token issued successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/TokenResponse'
'400':
$ref: '#/components/responses/BadRequest'
get:
operationId: validateToken
summary: Validate Access Token
description: Validate the current access token and retrieve its expiry information.
tags:
- Authentication
security:
- bearerAuth: []
responses:
'200':
description: Token is valid.
content:
application/json:
schema:
$ref: '#/components/schemas/TokenResponse'
'400':
$ref: '#/components/responses/BadRequest'
/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:
- Gift Cards
- Orders
- Balance
- Payments
- Reward Points
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: [email protected]
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: [email protected]
sendPoints:
summary: Send Reward Points
value:
query: storesAdmin.mutation.sendBalance
tag: storeAdmin
variables:
sender_email: [email protected]
expiry_month: 12
recipients:
- to_name: Jane Doe
to_email: [email protected]
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'
/v1/oauth/api/generateLink:
post:
operationId: generateRewardLink
summary: Generate Reward Links
description: >-
Generate one or more personalized reward links for a campaign. Links can
be distributed to recipients via email, SMS, or chat. Recipients do not
need a Xoxoday account to redeem.
tags:
- Reward Links
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- query
- tag
- variables
properties:
query:
type: string
enum:
- xoxo_link.mutation.generateLink
description: Fixed operation identifier.
tag:
type: string
enum:
- xoxo_link
description: Fixed tag identifier.
variables:
type: object
required:
- data
properties:
data:
type: object
required:
- campaignId
- links_quantity
- link_expiry
properties:
campaignId:
type: integer
description: Campaign identifier.
links_quantity:
type: integer
description: Number of reward links to generate.
link_expiry:
type: string
pattern: ^\d{2}-\d{2}-\d{4}$
description: Expiry date in DD-MM-YYYY format.
example: 31-12-2024
example:
query: xoxo_link.mutation.generateLink
tag: xoxo_link
variables:
data:
campaignId: 7890
links_quantity: 5
link_expiry: 31-12-2024
responses:
'200':
description: Reward links generated successfully.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
generateLink:
type: object
properties:
success:
type: integer
description: 1 = success.
message:
type: string
links:
type: array
items:
type: string
format: uri
batchId:
type: string
campaignName:
type: string
campaignId:
type: string
denomination_value:
type: integer
countryName:
type: string
currencyCode:
type: string
'400':
$ref: '#/components/responses/BadRequest'
components:
securitySchemes:
oauth2ClientCredentials:
type: oauth2
flows:
clientCredentials:
tokenUrl: https://accounts.xoxoday.com/chef/v1/oauth/token
scopes: {}
bearerAuth:
type: http
scheme: bearer
schemas:
TokenResponse:
type: object
properties:
access_token:
type: string
description: OAuth 2.0 access token.
token_type:
type: string
enum:
- bearer
expires_in:
type: integer
description: Token lifetime in seconds (or epoch expiry timestamp).
required:
- access_token
- token_type
- expires_in
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.
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'
GetVouchersResult:
type: object
properties:
status:
type: integer
description: 1 = success.
data:
type: array
items:
$ref: '#/components/schemas/Voucher'
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.
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
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).
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
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
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
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
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.
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
ApiError:
type: object
properties:
error:
type: string
error_description:
type: string
code:
type: string
errorId:
type: string
errorInfo:
type: string
responses:
BadRequest:
description: Bad request — invalid or missing parameters / authorization failure.
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'
BadGateway:
description: Upstream / internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'