PoshVine API reference

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.

Base URI's

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.

For Staging:-
For Production:-

Authentication

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.

Note:-Please contact PoshVine Team for whitelisting your production IP's.
In headers pass the credentials with the following keys along with each request:-
Key Value
X-API-Client-Token [YOUR_API_KEY]
Example:-

User Module

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.

  • Create User
  • API to create user

    POST /cs/external/users

    Sample Request

    Request Attributes

    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
    email 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
    Note:- Please contact PoshVine Team for more details on parameters.

    Sample Response

  • Update User
  • This API is used to update the user details.

    PUT /cs/external/users

    Sample Request

    Request Attributes

    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
    email String user email id
    mobile String user mobile no.

    Sample Response

  • Fetch User
  • This API is used to fetch user details.

    GET /cs/external/users

    Sample Request

    Request Attributes

    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

    Offer Management Suite

    These APIs allow you to integrate with PoshVine Offers Management Suite. Below is the list of commonly used APIs -

    • Get list of all offers
    • Get details of an offer
    • Get list of all Gift Cards
    • Get list of all Memberships
    • Offer Redemption
    • Gift Card Redemption
    • Membership Redemption
    • Redemption History

  • List Offers
  • This API is used to fetch list of all offers

    GET /ps/external/offers

    Sample Request

    Note:- Please contact PoshVine Team for your staging and production project_id.

    Request Attributes

    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

    Response Attributes

    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)
  • List Offer
  • This API is used to fetch details of offer

    GET /ps/external/offers/[OFFER ID]

    Sample Request

    Request Attributes

    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

    Response Attributes

    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)
  • Redeem Offer
  • API used to make redemption offer redemption

    POST /ps/external/redemptions

    Sample Request

    Request Attributes

    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

    Response Attributes

    Attribute Datatype Description
    redemption_id String ID of redemption
    voucher Object has details of voucher code and pin
  • List Gift Cards
  • This API is used to fetch list of all gift cards

    GET /ps/external/gift_cards

    Sample Request

    Note:- Please contact PoshVine Team for your staging and production project_id.

    Request Attributes

    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

    Response Attributes

    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 Gift Card
  • Redeem one of more denominations of a gift card

    POST /ps/external/redemptions

    Sample Request

    Request Attributes

    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

  • Redemption Status
  • Verify the status of the pending gift card order

    GET /ps/external/redemptions/status

    Sample Request

    Request Attributes

    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

    Response Attributes

    Attribute Datatype Description
    status String Current status of the gift card order
    voucher Object has details of voucher code and pin
  • List Memberships
  • This API is used to fetch list of all memberships available

    GET /ps/external/memberships

    Sample Request

    Note:- Please contact PoshVine Team for your staging and production project_id.

    Request Attributes

    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

    Response Attributes

    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
        personalized_voucher - Personalized voucher will be issued on purchase
        no_voucher - no voucher is required
    live String status of membership availability
  • Redeem Membership
  • API used to make membership redemption

    POST /ps/external/redemptions

    Sample Request

    Request Attributes

    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

    Response Attributes

    Attribute Datatype Description
    redemption_id String ID of redemption
    voucher Object has details of voucher code and pin
  • Redemption History
  • 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

    Request Attributes

    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

    Response Attributes

    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

    PointsPay Suite

    These APIs allows you to integrate with PoshVine PointsPay Suite. PointsPay Suite has 8 APIs i.e

    • Create Booking
    • Update Payment Details
    • Confirm Booking or Make Purchase
    • Booking Details
    • User Booking History

    Please check the data flow diagram for better understanding

  • Create Booking API
  • 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

    Note:- Please contact PoshVine Team for your staging and production project_id.

    Request Attributes

    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

    Response Attributes

    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
  • Update Payment Details
  • This API is used to collect the payment informations related to the purchase

    GET /pa/external/payments

    Sample Request

    Note:- Please contact PoshVine Team for your staging and production project_id.

    Request Attributes

    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

    Response Attributes

    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
  • Fetch Booking Details
  • This API is used to collect the payment informations related to the purchase

    GET /bs/external/bookings/:booking_id

    Sample Request

    Request Attributes

    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

    Response Attributes

    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
  • Fetch User Booking History
  • This API is used to collect the payment informations related to the purchase

    GET /bs/external/bookings/

    Sample Request

    Request Attributes

    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

    Response Attributes

    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

    Error Codes

    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.

    Note:- Please contact PoshVine Team in case you receive errors not listed below.
    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