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

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.