Get all vouchers for a chain
Sample JSON output is shown below:
{
"result": {
"code": 1,
"status": "ok"
},
"results": {
"results_count_total": 654,
"vouchers": [
{
"voucher_key": "bb1e45cbd6d174164b77a58047779e8d0323fa9c61ac994d84223343c531334e",
"voucher_id": 5,
"voucher_created_datetime": "2019-08-02T15:18:52+00:00",
"voucher_status": "claimed",
"voucher_locked": false,
"campaign_id": 3,
"campaign_type": "birthday",
"campaign_title": "ACME birthday campaign",
"redeeming_basket": null,
"voucher_expiry_datetime_utc": "2050-01-01 00:00:00",
"voucher_expiry_seconds_remaining": 990857543,
"voucher_currency_id": 2,
"voucher_currency_symbol": "€",
"voucher_amount_original": 33,
"voucher_amount_redeemed": 0,
"voucher_amount": 33,
"voucher_text": null,
"voucher_honour_code": null,
"voucher_title": "ACME birthday voucher",
"voucher_description": "This voucher deserves a good length of description, but not too long",
"voucher_notes": "Terms and conditions: this voucher is issued within a few days before your recorded birthday, and can be used in any participating store or online within one week after issue.",
"voucher_image_url": "https://acme.example.com/images/voucher_image_birthday.jpg",
"type": "basket",
"user": {
"id": 6,
"user_id": 6,
"first_name": "Chewy",
"last_name": "Bacca",
"username": "chewy@bacca.example.com",
"authentication_point_identifier": null,
"auxiliary_identifier": "peb402xar",
"mailing_list": null,
"entity_code": {
"type": "custom",
"code": null
},
"opt_in_programme": {
"programme_opted_in": true,
"join_date": "2018-04-01T18:22:31+00:00"
},
"signup_channel": null,
"country_code": "US",
"language": "en-US",
"address_streetname": null,
"address_housenumber": null,
"address_housenumber_extension": null,
"address_line_2": null,
"address_line_3": null,
"address_towncity": null,
"address_regionstate": null,
"address_postalcode": null
}
},
{
"voucher_key": "8422190c7d04e8a06b15abacb710dae654c2387f22fc3eacfdb5d0724a4e49f1",
"voucher_id": 4,
"voucher_created_datetime": "2019-09-02T15:18:52+00:00",
"voucher_status": "claimed",
"voucher_locked": false,
"campaign_id": 3,
"campaign_type": "loyalty",
"campaign_title": "ACME loyalty campaign",
"redeeming_basket": null,
"voucher_expiry_datetime_utc": "2050-01-01 00:00:00",
"voucher_expiry_seconds_remaining": 990857543,
"voucher_currency_id": null,
"voucher_currency_symbol": null,
"voucher_amount_original": null,
"voucher_amount_redeemed": 0,
"voucher_amount": null,
"voucher_text": null,
"voucher_honour_code": "HON00432",
"type": "honour",
"voucher_title": "ACME loyalty honour voucher",
"voucher_description": "This voucher has a fairly long description, not too long though",
"voucher_notes": "Terms and conditions: this voucher is issued when you make your first purchase, and can be redeemed in store for a free tee-shirt.",
"voucher_image_url": "https://acme.example.com/images/voucher_image_honour.jpg",
"user": null
}
],
"result_type": "get-vouchers"
}
}
Sample CSV file output is shown below:
voucher_id,voucher_key,voucher_status,type,voucher_created_datetime,voucher_expiry_datetime,voucher_redeemed_datetime,voucher_locked,voucher_locked_until_datetime,voucher_retailer_basket_code_exclusive,voucher_amount,voucher_amount_redeemed,voucher_text,voucher_currency_code,voucher_currency_symbol,campaign_id,campaign_type,campaign_title,customer_spaaza_user_id,customer_member_number,customer_username,customer_first_name,customer_last_name,customer_mailing_list_subscribed,customer_printed_mailing_list_subscribed,voucher_redeeming_basket_id,voucher_redeeming_basket_retailer_basket_code,voucher_redeeming_basket_platform_type,voucher_redeeming_basket_branch_business_id,voucher_redeeming_basket_branch_business_owner_code,voucher_redeeming_basket_total_value,voucher_locking_code,voucher_honour_code,voucher_title,voucher_description,voucher_image_url,voucher_discount_ratio,customer_country_code,customer_language
4,8422190c7d04e8a06b15abacb710dae654c2387f22fc3eacfdb5d0724a4e49f1,generated,basket,2018-05-05T17:59:11+00:00,2018-07-09T17:59:11+00:00,,0,,,5.00,0,Your voucher,EUR,€,219,signup,"Signup voucher",3355122,134014,georgina@cheeky.example.com,Georgina,Goodhope,1,,,,,,,,,,"Loyalty Signup Voucher","Thanks for signing up","https://acme.example.com/images/signup_voucher.jpg",,"NL",
5,bb1e45cbd6d174164b77a58047779e8d0323fa9c61ac994d84223343c531334e,generated,basket,2018-05-05T17:44:36+00:00,2018-07-09T17:44:36+00:00,,0,,,5.00,0,Your voucher,EUR,€,219,signup,"Signup voucher",3354924,133816,chewy@bacca.example.com,Chewy,Bacca,1,,,,,,,,,,,,,,"US","en-US"
6,8e4efe3f4afc0d26d69235c931b0f374c1a7b30d3ba043cd4332f689efccce77,generated,honour,2018-05-05T17:44:36+00:00,2018-07-09T17:44:36+00:00,,0,,,,0,Your voucher,EUR,,,loyalty,"Signup voucher",3354924,133816,chewy@bacca.example.com,Chewy,Bacca,1,,,,,,,,,"HONOUR004","Loyalty Honour Voucher","Voucher issued after two purchases","https://acme.example.com/images/honour_voucher.jpg",,"US","en-US"
Overview
- Call name: get-vouchers
- Endpoint URL: https://api0.spaaza.com/get-vouchers or https://api0.spaaza.com/get-vouchers.csv
- Request methods: GET
- Response Content-Type: application/json OR application/force-download with CSV file download
- Auth required: yes
The get-vouchers API endpoint returns all unredeemed basket vouchers for a chain, given the chain ID. It is possible to pass parameters to the endpoint so that it shows all redeemed vouchers, all vouchers for a particular campaign or vouchers matching various other parameters (see below).
When called without a suffix at the end of the URL or with a .json suffix the endpoint will return:
vouchers, which are vouchers that are used for a basket-level discount.
When called via the endpoint URL ending in .csv the endpoint will automatically set the response content-type to application/force-download and respond with a downloadable CSV file. Please see the section entitled “CSV Response Fields” below.
Note that the response is streamed, the API server does not buffer vouchers and wait until all are processed before sending.
Version-specific information
The following version-specific changes apply to this endpoint.
| Version | Change details |
|---|---|
| >= 1.4.2 | Previous name of basket_vouchers array in response JSON changed to vouchers. |
Permissions and Authentication
This API call requires a valid Spaaza session. The session can be as follows:
- Admin authentication: the performing user needs to be logged in and have
read accessto the entity (business or 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 (integer) required | The id of the chain for which the information is being requested. |
| campaign_id (integer) optional | The Spaaza ID of a campaign. If supplied only vouchers will be returned which are associated with the specified campaign. |
| user_id or username or member_number or authentication_point_identifier (varied) optional | The ID in the Spaaza system (user_id - integer), email address (username - email address), member number (member_number - string, normally numeric) or identity in a third-party authentication system (authentication_point_identifier - string) of an individual user. Adding this parameter returns only vouchers associated with that user. |
| voucher_id (integer) optional | Return only a single voucher with a matching ID. |
| exclude_regenerated (boolean) optional | If this flag is set to true, no vouchers are returned if they have been automatically generated when a purchased item is returned and the value of an original voucher redeemed on the item is regenerated into a new voucher. |
| show_redeemed (boolean) optional | Return only vouchers which have been redeemed. The default is to show only unredeemed vouchers (status claimed and status generated). Note that searching for redeemed vouchers causes the show_expired parameter and any expiry_datetime parameters to be overridden - all vouchers are shown, regardless of whether (un)expired. |
| max_redeemed_datetime (ISO-8601 extended timestamp) optional, requires show_redeemed | The ISO-8601 extended datetime of the latest date/time for which redeemed vouchers are to be shown. This includes the offset from GMT/UTC in hours (and minutes). Valid examples: “2018-09-19T14:05:20+00:00”, “2018-09-19T08:05:20-06:00”, “2018-09-19T14:05:20Z” |
| min_redeemed_datetime (ISO-8601 extended timestamp) optional, requires show_redeemed | The ISO-8601 extended datetime of the earliest date/time for which redeemed vouchers are to be shown. This includes the offset from GMT/UTC in hours (and minutes). Valid examples: “2018-09-19T13:27:56+00:00”, “2018-09-19T07:27:56-06:00”, “2018-09-19T13:27:56Z” |
| show_all_statuses (boolean) optional | Return vouchers which are in any status, either generated, claimed or redeemed. This parameter overrides the show_redeemed, min_redeemed_datetime and max_redeemed_datetime parameters. |
| show_expired (boolean) optional | Return only vouchers which have expired. The default is to show only unexpired vouchers (vouchers where the expiry date/time is greater than the current moment in time). Note that using the show_redeemed parameter causes this parameter to be ignored and the endpoint to return both expired and unexpired vouchers which are redeemed. This is because the expiry date of a voucher may be after the voucher was redeemed. |
| min_created_datetime (ISO-8601 extended timestamp) optional | The ISO-8601 extended datetime of the earliest date/time of creation for which vouchers are to be shown. This includes the offset from GMT/UTC in hours (and minutes). Valid examples: “2018-09-19T13:27:56+00:00”, “2018-09-19T07:27:56-06:00”, “2018-09-19T13:27:56Z” |
| min_created_datetime_relative (string) optional, overrides min_created_datetime | A string representing, relative to the current time, the earliest date/time of creation for which vouchers are to be shown. Includes (combinations of) integer numbers of months, days, hours and minutes. Valid examples: “7 days”, “-13 weeks”, “-6 months 5 days -2 minutes” |
| max_created_datetime (ISO-8601 extended timestamp) optional | The ISO-8601 extended datetime of the latest date/time of creation for which vouchers are to be shown. This includes the offset from GMT/UTC in hours (and minutes). Valid examples: “2018-09-19T14:05:20+00:00”, “2018-09-19T08:05:20-06:00”, “2018-09-19T14:05:20Z” |
| max_created_datetime_relative (string) optional, overrides max_created_datetime | A string representing, relative to the current time, the latest date/time of creation for which vouchers are to be shown. Includes (combinations of) integer numbers of months, days, hours and minutes. Valid examples: “+6 days”, “3 weeks”, “+6 months -5 days +2 minutes” |
| min_expiry_datetime (ISO-8601 extended timestamp) optional | The ISO-8601 extended datetime of the earliest expiry date/time for which vouchers are to be shown. This includes the offset from GMT/UTC in hours (and minutes). Valid examples: “2018-09-19T13:27:56+00:00”, “2018-09-19T07:27:56-06:00”, “2018-09-19T13:27:56Z” |
| min_expiry_datetime_relative (string) optional, overrides min_expiry_datetime | A string representing, relative to the current time, the earliest expiry date/time for which vouchers are to be shown. Includes (combinations of) integer numbers of months, days, hours and minutes. Valid examples: “7 days”, “-13 weeks”, “-6 months 5 days -2 minutes” |
| max_expiry_datetime (ISO-8601 extended timestamp) optional | The ISO-8601 extended datetime of the latest expiry date/time for which vouchers are to be shown. This includes the offset from GMT/UTC in hours (and minutes). Valid examples: “2018-09-19T14:05:20+00:00”, “2018-09-19T08:05:20-06:00”, “2018-09-19T14:05:20Z” |
| max_expiry_datetime_relative (string) optional, overrides max_expiry_datetime | A string representing, relative to the current time, the latest expiry date/time for which vouchers are to be shown. Includes (combinations of) integer numbers of months, days, hours and minutes. Valid examples: “+6 days”, “3 weeks”, “+6 months -5 days +2 minutes” |
| number_results (integer) optional | The (maximum) number of results required in the response. The default action for CSV output is to return all possible vouchers. For JSON output the maximum number of results returned for a single request is 500. |
| results_offset (integer) optional | The result number at which to start. For example, if there are 1000 vouchers, giving a results_offset of 500 will start at voucher 500. Numbering starts at 0. |
Output
The output contains information about vouchers and the users they are associated with.
JSON Response Fields
In addition to an object representing each voucher, the JSON response contains a field entitled results_count_total which returns the number of vouchers matching the query parameters regardless of the number_results or results_offset values used.
CSV Response Fields
When called via the endpoint URL ending in .csv the endpoint returns a downloadable CSV file named vouchers.csv. The CSV file contains a header row in the first line followed by a single line per voucher.
The fields shown below are represented in the CSV file in the order shown. Unpopulated fields follow CSV convention and are left blank. Fields containing special characters are surrounded by double quotes - e.g. "String with spaces" - following CSV convention. Other fields may be added to the CSV file in future, and these will be added at the end of each line.
| Field | Description |
|---|---|
| voucher_id (integer) | The unique ID of the voucher in the Spaaza system. |
| voucher_key (string) | The unique voucher key of the voucher. |
| voucher_status (string) | The status of the voucher. Possible values are “generated”, “claimed” or “redeemed”. |
| type (string) | The type of voucher. Currently this endpoint only returns vouchers of type “basket” and “basket_pct”. |
| voucher_created_datetime (ISO-8601 timestamp) | The date and time the voucher was created. |
| voucher_expiry_datetime (ISO-8601 timestamp) | The date and time the voucher is set to expire. |
| voucher_redeemed_datetime (ISO-8601 timestamp) | The date and time the voucher was redeemed (if the voucher has status “redeemed”). |
| voucher_locked (boolean) | Whether the voucher is currently locked. |
| voucher_locked_until_datetime (ISO-8601 timestamp) | The date and time the voucher lock period expires if the voucher is locked. This field remains populated even when a lock period has expired and the voucher is no longer locked. |
| voucher_retailer_basket_code_exclusive (string) | Any text string which has been chosen by the retailer in order to identity individual promotions or vouchers in an external system. |
| voucher_amount (float) | The monetary value of the voucher. This remains unchanged even in cases where the voucher is only partially redeemed. |
| voucher_amount_redeemed (float) | The monetary amount of the voucher which was redeemed. |
| voucher_text (string) | Any text describing the voucher. |
| voucher_currency_code (string, ISO-4217 currency code) | The ISO-4217 three-letter currency code of the voucher currency, e.g. “EUR” or “ZAR”. |
| voucher_currency_symbol (string, ISO-4217 currency symbol) | The ISO-4217 three-letter currency code of the voucher currency, e.g. “EUR” or “ZAR”. |
| campaign_id (integer) | The unique ID in the Spaaza system of the Spaaza campaign associated with the voucher. |
| campaign_type (string) | The type of Spaaza campaign associated with the voucher, e.g. “wallet”, “basket” or “loyalty” |
| campaign_title (string) | The title of the Spaaza campaign associated with the voucher. |
| customer_spaaza_user_id (integer) | The unique ID in the Spaaza system of the |
| customer_member_number (string) | The unique membership number or code for the shopper within the membership or loyalty programme. In most cases this is numeric, but string values are allowed. |
| customer_authentication_point_identifier (string) | The ID of the user in a third party webshop or other identity system. |
| customer_username (string, email address) | The username (email address) of the user. |
| customer_first_name (string) | The first name of the customer. |
| customer_last_name (string) | The last name of the customer. |
| customer_mailing_list_subscribed (boolean) | Whether the user is subscribed to the mailing list if there is one. |
| customer_printed_mailing_list_subscribed (boolean) | Whether the user is subscribed to the printed mailing list if there is one. |
| voucher_redeeming_basket_id (integer) | The unique ID in the Spaaza system of the basket (transaction) with which the voucher was redeemed, in the case the voucher status is redeemed. |
| voucher_redeeming_basket_retailer_basket_code (string) | The identifier in the retailer’s system used to identify the particular basket/transaction with which the voucher was redeemed, in the case the voucher status is redeemed. This field usually represents a receipt or order number. |
| voucher_redeeming_basket_platform_type (string) | The type of platform of the particular basket/transaction with which the voucher was redeemed, in the case the voucher status is redeemed. This field is usually either “in_store” or “online”. |
| voucher_redeeming_basket_branch_business_id (integer) | The unique ID in the Spaaza system of the retail branch at which the purchase basket/transaction with which the voucher was redeemed happened, in the case the voucher status is redeemed. |
| voucher_redeeming_basket_branch_business_owner_code (string) | The retailer branch code of the retail branch at which the purchase basket/transaction with which the voucher was redeemed happened, in the case the voucher status is redeemed. |
| voucher_redeeming_basket_total_value (float) | The total cash value of the particular basket/transaction with which the voucher was redeemed, in the case the voucher status is redeemed. |
| voucher_locking_code (string) | Any locking code associated with a voucher. In the case that the voucher is in a claimed state, it can only be redeemed by a basket or redemption call supplying this locking code. |
| voucher_honour_code (string) | A third party code used to allow third parties such as POS devices or web stores to decide whether to redeem (“honour”) a voucher. For example, a voucher_honour_code could flag a promotion running on a POS in a store. |
| voucher_title (string) | A title used with the voucher. |
| voucher_description (string) | A longer-form description for the voucher. |
| voucher_image_url (string, URL) | The URL of an image associated with the voucher. |
| voucher_discount_ratio (float) | The discount ratio of the voucher, denoting the percentage discount it may offer on a purchase. |
| customer_country_code (string) | The ISO ALPHA-2 country code of the customer. |
| customer_language (string) | The IETF BCP 47 language code (eg. en-GB, nl, nl-BE, etc.) of the customer. |