Link Search Menu Expand Document

Claiming vouchers

Contents

Overview

  • Call name: claim-voucher
  • Endpoint URL: https://api0.spaaza.com/claim-voucher
  • Request methods: POST or PUT
  • Request Content-Type: multipart/form-data or application/x-www-form-urlencoded
  • Response Content-Type: application/json
  • Auth required: yes

Claims a voucher (variable price or other kind of voucher) which has been offered to a user.

The claim-voucher API allows a user to claim a voucher which has been earned through campaign rewards or through other voucher generation mechanisms. It uses the voucher identifier values supplied to claim the voucher. Once the voucher has been claimed it can be redeemed.

Please see the vouchers page for more information on vouchers and how they work in Spaaza.

Version-specific information

The following version-specific changes apply to this endpoint. See the versioning page for more details.

Version Change details
>= 1.5.3 chain_id parameter now mandatory with admin authentication
  Endpoint extended to allow member_number, username, authentication_point_identifier or auxiliary_identifier as end-user identifiers

Permissions and Authentication

This API call requires a valid Spaaza session. The session can be as follows:

  • User authentication: a session generated by an end-user login.
  • Admin authentication: the performing user needs to be logged in and have write access to the chain to which the user is connected.
  • Privileged authentication: the use of privileged authentication is permitted for this endpoint.

If the campaign has allows_end_user_to_claim_voucher set to false then only a user with privileged or admin authentication can claim the voucher.

Headers

The following headers can/must be passed to the API call:

Parameter Description
X-Spaaza-MyPrice-App-Hostname (mandatory in the case of user and privileged authentication, do not use otherwise) The hostname of the app for which the user is requesting the card.

HTTP Parameters

The following HTTP parameters can be passed to the API:

Parameter Description
chain_id (integer, mandatory when using admin authentication) The id of the chain for which the information is being requested.
user_id OR member_number OR username OR authentication_point_identifier OR auxiliary_identifier (mandatory when using admin or privileged authentication) The Spaaza unique ID (user_id, integer), member number (member_number, string), email address (username, valid email address), or identity in a third-party authentication system (authentication_point_identifier/auxiliary_identifier, string) of the end-user associated with the voucher.
voucher_key (string, mandatory if voucher_id or third_party_id not used to identify voucher) The unique voucher key generated for the voucher. This is a string, for instance c4bc4a3115e21e228936f4223dd89b22c238847c935514e1fdcb96f3c75118ac.
voucher_id (integer, mandatory if voucher_key or third_party_id not used to identify voucher) The unique id generated for the voucher. This is an integer, for instance 4064783. It is recommended to use the voucher_key parameter if possible.
third_party_id (integer, mandatory if voucher_id or voucher_key not used to identify voucher) The unique id generated for a voucher whill be generated when the chain has uses_third_party_voucher_id set true.

At least one of the parameters voucher_key, voucher_id or third_party_id must be used to identify the voucher.

Sample request

The endpoint returns JSON showing the details associated with the voucher including the new value of the voucher_status field. An example is shown below:

{
    "result": {
        "code": 1,
        "status": "ok"
    },
    "results": {
        "voucher_key": "13918dc12e44bc183cb168fa10684d0714115ff37132d4c265f4a8ab6678a741",
        "voucher_id": 35735,
        "voucher_status": "claimed",
        "voucher_locked": false,
        "campaign_id": 136,
        "campaign_type": "signup",
        "campaign_title": "Earn €5 on signup",
        "voucher_expiry_datetime_utc": "2050-01-01 00:00:00",
        "voucher_expiry_seconds_remaining": 996899028,
        "voucher_currency_id": 2,
        "voucher_currency_symbol": "€",
        "voucher_amount_original": 5,
        "voucher_amount_redeemed": 0,
        "voucher_amount": 5,
        "voucher_text": null,
        "voucher_third_party_id": 3914599659,
        "user_id": 1107604,
        "user_entity_card": {
            "type": "custom",
            "code": "404064"
        },
        "result_type": "claim-voucher"
    }
}