The PoshVine API is organized around REST. Our API has predictable resource- oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. The APIs enable you to seamlessly connect to Poshvine's treasure of offers, gift cards, memberships and a lot more!
You can use Poshvine APIs in sandbox and production environments.
Please use the following base URI's. The URI you use will determine the environment. For all testing
purposes please use the staging URI. All the requests made to the production URI will affect production
data and all the bookings made will be considered
as actual user bookings.
PoshVine APIs use API key to authenticate requests. You can
generate your API key from the dashboard under settings.
In addition to API key, we also whitelist the IP's from where the APIs calls will be triggered.
Key | Value |
---|---|
X-API-Client-Token | [YOUR_API_KEY] |
User module Apis helps to create, update and fetch user data. User ID is required for all the redemption API calls.Redemption options are linked to with users, hence user creation is mandatory part of the integration.
API to create user
POST /cs/external/users
Sample Request
Attribute | Datatype | Description | Optional | Parameter Type |
---|---|---|---|---|
X-API-Client-Token | String | client API key shared by PoshVine Team to be passed as header parameter | No | header |
name | String | Name of the user | Yes | query parameter |
mobile | String | mobile no. of user (10 digits ) | No | query parameters |
String | user email id | yes | query parameter | |
customer_id | String | Unique identifier of user (this value will be used in X-External-Id parameter in all the APIs where user id is required) | No | query parameter |
card_name | String | name of the card issued to user | Yes | query parameter |
card_id | String | unique identifier for the card this value will used in X-External-Card-Id parameter in all the APIs where user card is required | Yes | query parameter |
bin | String | BIN no of user card, can be first 8 or first 4 last 4 digit of the card | Yes | query parameter |
segment | String | Segment if user card | Yes | query parameter |
credit_limit | String | Credit limit of user card | Yes | query parameter |
cash_limit | String | Cash limit of user card | Yes | query parameter |
Sample Response
This API is used to update the user details.
PUT /cs/external/users
Sample Request
Attribute | Datatype | Description |
---|---|---|
X-API-Client-Token | String | client API key shared by PoshVine Team |
X-External-Id | String | user external id shared in response of create user api (attribute: external_id) |
name | String | name of the user |
salutation | String | title of the user |
String | user email id | |
mobile | String | user mobile no. |
Sample Response
This API is used to fetch user details.
GET /cs/external/users
Sample Request
Attribute | Datatype | Description |
---|---|---|
X-API-Client-Token | String | client API key shared by PoshVine Team |
X-External-Id | String | user external id shared in response of create user api (attribute: external_id) |
Sample Response
These APIs allow you to integrate with PoshVine Offers Management Suite. Below is the list of commonly used APIs -
This API is used to fetch list of all offers
GET /ps/external/offers
Sample Request
Attribute | Datatype | Description | Optional | Parameter Type |
---|---|---|---|---|
X-API-Client-Token | String | client API key shared by PoshVine Team to be passed as header parameter | No | header |
X-Project-ID | String | ID of the project for which offers to be displayed. | Yes | header |
X-External-Id | String | user external id shared in response of create user api(attribute: external_id) to be passed as header parameter. If passed response will return additional parameter claimable | Yes | header |
title | String | Title of the offer | Yes | query parameter |
merchant_name | String | search for offers with merchant name | Yes | query parameter |
start_date__gte | String (format: dd/mm/yyyy) | offer start date >= start_date__gte | Yes | query parameter |
start_date__lte | String (format: dd/mm/yyyy) | offer start date <= start_date__lte | Yes | query parameter |
end_date__gte | String (format: dd/mm/yyyy) | offer end date >= end_date__gte | Yes | query parameter |
end_date__lte | String (format: dd/mm/yyyy) | offer end date <= end_date__lte | Yes | query parameter |
page | Numeric | page no to fetch offers (default value: 1) | Yes | query parameter |
per_page | Numeric | per page count of offers(default value: 30) | Yes | query parameter |
Sample Response
Attribute | Datatype | Description |
---|---|---|
id | String | Offer id |
title | String | offer title |
description | String | Offer description |
start_date | String | Offer start date |
offer_type | String | Type of offer values can be (no_voucher/generic_voucher/personalized_voucher) |
redemption_url | String | URL to redeem the coupon code |
redemption_steps | String | Steps to redeem offer |
image_url | String | Offer Image URL |
offer_end_date | String | Offer end date |
merchant | String | Merchant details of offer |
categories | String | Categories associated with offer |
offer_value | String | |
claimable | String | Offer eligibility for user (passed only if X-External-Id is passed in request header parameters) |
This API is used to fetch details of offer
GET /ps/external/offers/[OFFER ID]
Sample Request
Attribute | Datatype | Description | Optional | Parameter Type |
---|---|---|---|---|
X-API-Client-Token | String | client API key shared by PoshVine Team to be passed as header parameter | No | header |
X-Project-ID | String | ID of the project for which offer to be displayed. | Yes | header |
X-External-Id | String | user external id shared in response of create user api(attribute: external_id) to be passed as header parameter. If passed response will return additional parameter claimable | Yes | header |
Sample Response
Attribute | Datatype | Description |
---|---|---|
id | String | Offer id |
title | String | offer title |
description | String | Offer description |
start_date | String | Offer start date |
offer_type | String | Type of offer values can be (no_voucher/generic_voucher/personalized_voucher) |
redemption_url | String | URL to redeem the coupon code |
redemption_steps | String | Steps to redeem offer |
image_url | String | Offer Image URL |
offer_end_date | String | Offer end date |
merchant | String | Merchant details of offer |
categories | String | Categories associated with offer |
offer_value | String | |
claimable | String | Offer eligibility for user (passed only if X-External-Id is passed in request header parameters) |
API used to make redemption offer redemption
POST /ps/external/redemptions
Sample Request
Attribute | Datatype | Description | Optional | Parameter Type |
---|---|---|---|---|
X-API-Client-Token | String | client API key shared by PoshVine Team to be passed as header parameter | No | header |
X-External-Id | String | user external id shared in response of create user api(attribute: external_id) to be passed as header parameter. | No | header |
X-Project-ID | String | Project ID of the offer | No | header |
Origin | String | whitelisted origin | No | header |
benefit_id | String | ID of the order to be redeemed | No | query parameter |
benefit_type | String | value: offer | No | query parameter |
Sample Response
Attribute | Datatype | Description |
---|---|---|
redemption_id | String | ID of redemption |
voucher | Object | has details of voucher code and pin |
This API is used to fetch list of all gift cards
GET /ps/external/gift_cards
Sample Request
Attribute | Datatype | Description | Optional | Parameter Type |
---|---|---|---|---|
X-API-Client-Token | String | client API key shared by PoshVine Team to be passed as header parameter | No | header |
X-Project-ID | String | ID of the project for which gift cards to be displayed. | No | header |
Sample Response
Attribute | Datatype | Description |
---|---|---|
id | String | Gift Card id |
title | String | Name of gift card |
price_type | String | type of gift card denominations, can have two values(range/slab) |
active | boolean | Boolean parameter to show if gift card is available to purchase or not |
start_date | String | Gift Card sale start date |
end_date | String | Gift Card sale end date |
redemption_type | String | type of redemption of gift card (online/offline) |
redemption_url | String | Website link where gift card can be used |
image_url | String | Image to be displayed |
eligible_denominations | String | denomination available to buy |
eligible_denomination_range | String | range of denomination available to purchase |
Redeem one of more denominations of a gift card
POST /ps/external/redemptions
Sample Request
Attribute | Datatype | Description | Optional | Parameter Type |
---|---|---|---|---|
X-API-Client-Token | String | client API key shared by PoshVine Team to be passed as header parameter | No | header |
X-External-Id | String | user external id shared in response of create user api(attribute: external_id) to be passed as header parameter. | No | header |
X-External-Card-Id | String | card external id shared in response of create user api(attribute: card_id) to be passed as header parameter. | No | header |
X-Project-ID | String | Project ID of the offer | No | header |
X-Request-ID | String | Unique Request ID for retry and recon. Optional otherwise | No | header |
benefit_id | String | ID of the gift card to be redeemed | No | query parameter / body |
benefit_type | String | value: gift_card | No | query parameter / body |
denomination_quantity | Hash | Key pair value of denomination and quantity. Quantity cannot be more than 4 and not more than 5 denominations per redeem call | No | query parameter / body |
Sample Response
Verify the status of the pending gift card order
GET /ps/external/redemptions/status
Sample Request
Attribute | Datatype | Description | Optional | Parameter Type |
---|---|---|---|---|
X-API-Client-Token | String | client API key shared by PoshVine Team to be passed as header parameter | No | header |
X-Request-ID | String | The original request ID passed during redeem API call | No | header |
X-Project-ID | String | Project ID of the offer | Yes | header |
benefit_type | String | value: gift_card | No | query parameter |
order_id | String | Order ID returned in the redeem Gift Card API | No | query parameter |
Sample Response
Attribute | Datatype | Description |
---|---|---|
status | String | Current status of the gift card order |
voucher | Object | has details of voucher code and pin |
This API is used to fetch list of all memberships available
GET /ps/external/memberships
Sample Request
Attribute | Datatype | Description | Optional | Parameter Type |
---|---|---|---|---|
X-API-Client-Token | String | client API key shared by PoshVine Team to be passed as header parameter | No | header |
X-Project-ID | String | ID of the project for which gift cards to be displayed. | No | header |
Sample Response
Attribute | Datatype | Description |
---|---|---|
id | String | Membership id |
title | String | Name of Membership |
description | String | Description text for membership |
terms | string | Terms and conditions of membership |
membership_url | String | Website URL to avail membership |
start_date | String | Membership sale start date |
end_date | String | Gift Card sale end date |
redemption_steps | String | Steps to redeem membership |
original_price | Float | Original price of membership |
offer_price | Float | Offer price of membership |
image_url | String | Image Url to display |
membership_type | String |
type of membership
|
live | String | status of membership availability |
API used to make membership redemption
POST /ps/external/redemptions
Sample Request
Attribute | Datatype | Description | Optional | Parameter Type |
---|---|---|---|---|
X-API-Client-Token | String | client API key shared by PoshVine Team to be passed as header parameter | No | header |
X-External-Id | String | user external id shared in response of create user api(attribute: external_id) to be passed as header parameter. | No | header |
X-Project-ID | String | Project ID of the membership | No | header |
X-External-Card-Id | String | card external id shared in response of create user api(attribute: card_id) to be passed as header parameter. | No | header |
benefit_id | String | ID of the membership to be redeemed | No | query parameter |
benefit_type | String | value: membership | No | query parameter |
Sample Response
Attribute | Datatype | Description |
---|---|---|
redemption_id | String | ID of redemption |
voucher | Object | has details of voucher code and pin |
This API is used to fetch redemption history of the user. This is has a default pagination of 30 items per page
GET /ps/external/redemptions
Sample Request
Attribute | Datatype | Description | Optional | Parameter Type |
---|---|---|---|---|
X-API-Client-Token | String | client API key shared by PoshVine Team to be passed as header parameter | No | header |
X-External-Id | String | user external id shared in response of create user api(attribute: external_id) to be passed as header parameter. | No | header |
X-Project-ID | String | Project ID of the offer | Yes | header |
page | Numeric | page no to fetch offers (default value: 1) | Yes | query parameter |
per_page | Numeric | per page count of offers(default value: 30) | Yes | query parameter |
Sample Response
Attribute | Datatype | Description |
---|---|---|
id | String | Offer id |
type | String | will have the static value redemption |
order_no | String | Unique OrderNo for redemption |
created_at | String | Time Stamp of redemption creation(GST) |
order_value | String | Value of order |
status | String | status of redemption (possible values: initiated/processing/success/failure) |
offer | Object | offer details of redemption |
voucher | Object | Voucher details of redemption. Has details for voucher code, pin and voucher end date |
These APIs allows you to integrate with PoshVine PointsPay Suite. PointsPay Suite has 8 APIs i.e
Please check the data flow diagram for better understanding
This API is used to initiate booking, this requires all the details related to item to be purchased and the purchase amount
POST /ps/external/memberships
Sample Request
Attribute | Datatype | Description | Optional | Parameter Type |
---|---|---|---|---|
X-API-Client-Token | String | client API key shared by PoshVine Team to be passed as header parameter | No | header |
X-Project-ID | String | ID of the project for which gift cards to be displayed. | No | header |
X-External-Id | String | user external id shared in response of create user api(attribute: external_id) to be passed as header parameter. | No | header |
item_type | String | type of item to be purchased (gift_card/membership) | No | body |
item_id | String | ID of the item shared in the listing api of Gift Card and Membership | No | body |
fare_breakup | Hash Object |
Detail of fare, key to be passed in object 1.base - base fare of purchase 2.taxes - taxes applicable on purchase 3.discount - discount applied on purchase 4.price - actual purchase price |
No | body |
user_pack | Hash Object |
Detail of user, key to be passed in object 1.first_name - first name of the user 2.last_name - last name of the user 3.mobile - phone no of the user 4.email - email id of the user |
No | body |
Sample Response
Attribute | Datatype | Description |
---|---|---|
booking_id | String | ID of the booking, this id will be used for all further communication related to this purchase |
status | String | value: booking_initiated |
This API is used to collect the payment informations related to the purchase
GET /pa/external/payments
Sample Request
Attribute | Datatype | Description | Optional | Parameter Type |
---|---|---|---|---|
X-API-Client-Token | String | client API key shared by PoshVine Team to be passed as header parameter | No | header |
X-Project-ID | String | ID of the project for which gift cards to be displayed. | No | header |
X-External-Id | String | user external id shared in response of create user api(attribute: external_id) to be passed as header parameter. | No | header |
booking_id | String | ID of booking received on create booking api | No | body |
amount | String | purchase amount | No | body |
payment_date | date | date of payment | No | body |
transactions_attributes | Hash Object |
Detail of transactions, key to be passed in object 1.txn_type - transaction type (points / payment_gateway) 2.amount - amount paid by mode |
No | body |
Sample Response
Attribute | Datatype | Description |
---|---|---|
booking_id | String | ID of the booking, this id will be used for all further communication related to this purchase |
booking_status | String | value: booking_in_progress/booking_confirmed |
payment_status | String | status of payment |
This API is used to collect the payment informations related to the purchase
GET /bs/external/bookings/:booking_id
Sample Request
Attribute | Datatype | Description | Optional | Parameter Type |
---|---|---|---|---|
X-API-Client-Token | String | client API key shared by PoshVine Team to be passed as header parameter | No | header |
X-Project-ID | String | ID of the project for which gift cards to be displayed. | No | header |
X-External-Id | String | user external id shared in response of create user api(attribute: external_id) to be passed as header parameter. | No | header |
booking_id | String | ID of booking received on create booking api | No | body |
Sample Response
Attribute | Datatype | Description |
---|---|---|
booking_id | String | ID of the booking, this id will be used for all further communication related to this purchase |
booking_status | String | value: booking_in_progress/booking_confirmed |
payment_status | String | status of payment |
This API is used to collect the payment informations related to the purchase
GET /bs/external/bookings/
Sample Request
Attribute | Datatype | Description | Optional | Parameter Type |
---|---|---|---|---|
X-API-Client-Token | String | client API key shared by PoshVine Team to be passed as header parameter | No | header |
X-Project-ID | String | ID of the project for which gift cards to be displayed. | No | header |
X-External-Id | String | user external id shared in response of create user api(attribute: external_id) to be passed as header parameter. | No | header |
Sample Response
Attribute | Datatype | Description |
---|---|---|
booking_id | String | ID of the booking, this id will be used for all further communication related to this purchase |
booking_status | String | value: booking_in_progress/booking_confirmed |
payment_status | String | status of payment |
Responses from the API use HTTP response codes to indicate general classes of success and error. Error responses contain more detail about the error in the response body. Following are the few error codes and their explanation.
HTTP Status Code | Description |
---|---|
200 | Success |
201 | Record created |
204 | Record not found |
401 | Unauthorized access, missing/wrong mandatory header parameters |
403 | Forbidden, in case of wrong/not whitelisted IP or Origin |
404 | URL Not Found |
500 | Application error, contact PoshVine Team |