Link Search Menu Expand Document

Get all vouchers for a user

An example output is shown below

{
    "result": {
        "code": 1,
        "status": "ok"
    },
    "results": {
        "basket_vouchers": [
            {
                "campaign_id": 136,
                "campaign_title": "Earn €5 on signup",
                "campaign_type": "signup",
                "redeeming_basket": null,
                "voucher_amount": 5,
                "voucher_amount_original": 5,
                "voucher_amount_redeemed": 0,
                "voucher_currency_id": 2,
                "voucher_currency_symbol": "€",
                "voucher_description": "Redeem this voucher in store to get €5 off your purchase.",
                "voucher_expiry_datetime_utc": "2050-01-01 00:00:00",
                "voucher_expiry_seconds_remaining": 996901179,
                "voucher_honour_code": "honour0004",
                "voucher_id": 35735,
                "voucher_image_url": "https://www.example.com/voucher-image.jpg",
                "voucher_key": "13918dc12e44bc183cb168fa10684d0714115ff37132d4c265f4a8ab6678a741",
                "voucher_locked": false,
                "voucher_notes": "Terms and conditions apply to the redemption of this voucher. Franchise owners may request proof of identity.",
                "voucher_status": "generated",
                "voucher_text": "Your new voucher, enjoy!",
                "voucher_title": "€5 Signup Voucher",
                "voucher_type": "basket"
            },
            {
                "campaign_id": 140,
                "campaign_title": "ACME Loyalty Campaign",
                "campaign_type": "loyalty",
                "creating_user": {
                    "full_name": "John Doe",
                    "user_id": 21
                },
                "redeeming_basket": null,
                "voucher_amount": 5,
                "voucher_amount_original": 5,
                "voucher_amount_redeemed": 0,
                "voucher_currency_id": 2,
                "voucher_currency_symbol": "€",
                "voucher_description": null,
                "voucher_expiry_datetime_utc": "2018-07-30 00:00:00",
                "voucher_expiry_seconds_remaining": 5201979,
                "voucher_honour_code": "honour004",
                "voucher_id": 30880,
                "voucher_image_url": null,
                "voucher_key": "2ea66c08e3f0fa2d45bf62f382bb9fbff237a86fea79e45ede2b1b1328be56f0",
                "voucher_locked": false,
                "voucher_notes": "Text on how to use a voucher or other notes go here.",
                "voucher_status": "generated",
                "voucher_text": "Thanks for being a great customer",
                "voucher_title": null,
                "voucher_type": "basket"
            },
            {
                "campaign_id": 140,
                "campaign_title": "ACME Loyalty Campaign",
                "campaign_type": "loyalty",
                "creating_user": {
                    "full_name": "John Doe",
                    "user_id": 21
                },
                "voucher_amount": 5,
                "voucher_amount_original": 5,
                "voucher_amount_redeemed": 0,
                "voucher_currency_id": 2,
                "voucher_currency_symbol": "€",
                "voucher_description": null,
                "voucher_expiry_datetime_utc": "2018-07-30 00:00:00",
                "voucher_expiry_seconds_remaining": 5201979,
                "voucher_id": 94231,
                "voucher_image_url": null,
                "voucher_key": "4b900509eab95909e2cfcd74a9d039dce1dbbcba40d3463163b965ec1bbfdace",
                "voucher_locked": false,
                "voucher_notes": null,
                "voucher_status": "claimed",
                "voucher_text": "Thanks for being a great customer",
                "voucher_title": null,
                "voucher_type": "basket"
            }
        ],
        "honour_vouchers": [
            {
                "campaign_id": 140,
                "campaign_title": "ACME Loyalty Campaign",
                "campaign_type": "loyalty",
                "creating_user": {
                    "full_name": "John Doe",
                    "user_id": 21
                },
                "voucher_amount": 5,
                "voucher_amount_original": 5,
                "voucher_amount_redeemed": 4,
                "voucher_currency_id": 2,
                "voucher_currency_symbol": "€",
                "voucher_description": "Redeem this voucher online for a free item.",
                "voucher_expiry_datetime_utc": "2018-07-30 00:00:00",
                "voucher_expiry_seconds_remaining": 5201979,
                "voucher_honour_code": "HON00421",
                "voucher_id": 94697,
                "voucher_image_url": null,
                "voucher_key": "138406421b611051c953a620c5f958348bbb045fdf4a7e92c8e9f53ccd04144e",
                "voucher_locked": false,
                "voucher_notes": null,
                "voucher_status": "claimed",
                "voucher_text": "Thanks for being a great customer",
                "voucher_title": null,
                "voucher_type": "honour"
            }
        ],
        "promotions": {
            "affiliate": [],
            "basket": [],
            "birthday": [
                {
                    "actions": [],
                    "campaign_id": 142,
                    "currency": "EUR",
                    "currency_symbol": "€",
                    "days_before": 7,
                    "description": "",
                    "gift_amount": 50,
                    "is_contributor": true,
                    "recipient_campaign_id": 117,
                    "reward_money": 50,
                    "supports_contribution": true,
                    "title": "50 points on your birthday",
                    "type": "birthday"
                }
            ],
            "limited_cashback_contribution": [],
            "loyalty": [
                {
                    "active": true,
                    "chain_id": 1743,
                    "created_date": "2018-02-06T08:26:02+00:00",
                    "created_voucher_claimed_by_default": false,
                    "currency_id": 2,
                    "description": "The best fashion loyalty programme",
                    "id": 140,
                    "is_active": true,
                    "last_modified_date": "2018-02-06T08:26:02+00:00",
                    "loyalty_levels": [],
                    "loyalty_rules": [],
                    "myprice_app_id": 5,
                    "recipient_campaign_id": null,
                    "supports_user_segments": false,
                    "title": "ACME Loyalty Campaign",
                    "type": "loyalty",
                    "user_segment_id": null,
                    "voucher_text": "Your ACME loyalty voucher"
                }
            ],
            "product": [],
            "progress": [
                {
                    "actions": [],
                    "campaign_id": 143,
                    "currency": "EUR",
                    "currency_symbol": "€",
                    "description": "",
                    "earn_percentage": 5,
                    "is_contributor": true,
                    "recipient_campaign_id": 117,
                    "saved_amount": 0,
                    "saved_amount_currency": "EUR",
                    "saved_amount_currency_symbol": "€",
                    "supports_contribution": true,
                    "title": "Get extra points at our Amsterdam store",
                    "total_amount": 0,
                    "type": "cashback",
                    "unlocked_amount": 0
                },
                {
                    "actions": [],
                    "campaign_id": 120,
                    "currency": "EUR",
                    "currency_symbol": "€",
                    "description": "Get €10 on your wallet when you spend €100",
                    "is_contributor": true,
                    "progress": {
                        "achieved": 50,
                        "percentage": 50,
                        "target": 100
                    },
                    "recipient_campaign_id": 116,
                    "reward_money": 10,
                    "supports_contribution": true,
                    "title": "Earn €10 when you spend €100",
                    "type": "simple"
                },
                {
                    "actions": [],
                    "campaign_id": 118,
                    "currency": "PTN",
                    "currency_symbol": "PTN",
                    "description": "3 punten voor iedere €1 aankoop",
                    "earn_percentage": 300,
                    "is_contributor": true,
                    "recipient_campaign_id": 117,
                    "saved_amount": 0,
                    "saved_amount_currency": "PTN",
                    "saved_amount_currency_symbol": "PTN",
                    "supports_contribution": true,
                    "title": "ACME Cashback Contributor",
                    "total_amount": 0,
                    "type": "cashback",
                    "unlocked_amount": 0
                }
            ],
            "signup": [
                {
                    "actions": [],
                    "campaign_id": 136,
                    "currency": "EUR",
                    "currency_symbol": "€",
                    "description": "",
                    "is_contributor": false,
                    "reward_money": 5,
                    "signup_amount": 5,
                    "supports_contribution": true,
                    "title": "Earn €5 on signup",
                    "type": "signup"
                },
                {
                    "actions": [],
                    "campaign_id": 121,
                    "currency": "EUR",
                    "currency_symbol": "€",
                    "description": "",
                    "is_contributor": true,
                    "recipient_campaign_id": 117,
                    "reward_money": 1000,
                    "signup_amount": 1000,
                    "supports_contribution": true,
                    "title": "Get 1000 points when you signup",
                    "type": "signup"
                }
            ]
        },
        "result_type": "get-user-vouchers",
        "var_price_vouchers": [],
        "wallet": {
            "active": true,
            "balance_can_subzero": true,
            "chain_id": 1743,
            "created_date": "2017-10-18T09:39:43+00:00",
            "currency": "EUR",
            "currency_symbol": "€",
            "description": "Converted wallet points come here",
            "id": 116,
            "is_active": true,
            "is_redeemable": true,
            "last_modified_date": "2017-10-18T09:39:43+00:00",
            "max_manual_daily_amount": "200.00",
            "parameters": [],
            "rounding_precision": 2,
            "rounding_strategy": "neutral",
            "saved_amount": 170,
            "spend_on_promotional_items": true,
            "title": "ACME Wallet",
            "total_amount": 170,
            "type": "wallet",
            "voucher_expiry_days": 0
        }
    }
}

Overview

  • Call name: get-user-vouchers
  • Endpoint URL: https://api0.spaaza.com/get-user-vouchers
  • Request methods: GET
  • Response Content-Type: application/json
  • Auth required: yes

The get-user-vouchers API retrieves the applicable vouchers for a user, given the user’s ID or entity card (member) number and the chain ID.

It will return:

  • basket_vouchers, which are vouchers that are available for use in the next purchase.

  • honour_vouchers, which are vouchers that are used to redeem rewards offers in 3rd party systems

  • var_price_vouchers, which are vouchers for a specific product (Personal Pricing)

  • promotions, which are hints to the user that certain types of discount are available.

  • wallet, wallet information for users where the retailer has a wallet enabled.

Permissions and Authentication

This API call requires valid Spaaza authentication. The authentication 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 read access to the entity (chain) to which the user is connected.
  • Privileged authentication: the use of privileged authentication is permitted for this endpoint.

HTTP Parameters

The following HTTP parameters can be passed to the API:

Parameter Description
chain_id required for admin and privileged authentication The id of the chain for which the information is being requested.
user_id or member_number required for admin and privileged authentication The id or member_number (user code) of the user for whom the voucher details are being requested.
filter optional all when set to all redeemed or ‘used’ vouchers will also be returned in the response together with expired vouchers that were not used.

Output

The promotions section contain hints to the user that a certain voucher or reward is available, for instance when buying this product in combination with another product.

The voucher_key (or voucher_id) parameter needs to be sent to Spaaza in an add-basket post in order to redeem the voucher. Note that only vouchers with a status of claimed can be redeemed. To claim a voucher use the claim-voucher endpoint (and to unclaim use the unclaim-voucher endpoint).

Use filter:all to get vouchers back that have already been redeemed or expired. If this parameter is not included only available vouchers are returned.