Bulk Claiming vouchers
Contents
- Overview
- Version-specific information
- Permissions and Authentication
- Headers
- HTTP Parameters
- Sample request
Overview
- Call name: claim-vouchers
- Endpoint URL: https://api0.spaaza.com/claim-vouchers
- Request methods: POST
- Request Content-Type: application/json
- Response Content-Type: application/json
- Auth required: yes
This endpoint allows a user with admin or privileged access to claim one or multiple vouchers on behalf of a user. Optionally, it is also possible to lock the vouchers for a specific period.
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 |
|---|---|
| N/A | N/A |
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
write accessto the chain to which the user is connected. - Privileged authentication: the use of privileged authentication is permitted for this endpoint. For privileged authentication, the
X-Spaaza-MyPrice-App-Hostnameheader must be passed in the request.
Headers
The following headers can/must be passed to the API call:
| Parameter | Description |
|---|---|
| X-Spaaza-MyPrice-App-Hostname | (mandatory in the case of privileged authenticaiton) The hostname of the app which the user is associated with. |
HTTP Parameters
The following HTTP parameters can be passed to the API:
| Parameter | Description |
|---|---|
| entity | (string, mandatory) Details of the retailer which is submitting the request. |
| chain_id | (integer) The Spaaza Chain ID of the retailer entity. |
| user | (string) Details of the user who is submitting the request. At least one of user_id, username, member_number, authentication_point_identifier, auxiliary_identifier, referral_code are required to identify the user. |
| vouchers | *(string, There is a limit of 10 vouchers per API call. At least one of voucher_key, voucher_id and voucher_third_party_id are required identify the voucher that will be claimed. |
| locking | (string, optional) This field is optional it possible to claim multiple vouchers without locking them. The maximum allowed voucher_lock_period is 3600 seconds (1 hour), the minimum is 120 seconds (2 minutes). If the voucher_lock_period is not provided the default locking period is 300 seconds (5 minutes). Either retailer_basket_code or voucher_locking_code must be provided if the voucher is only to be redeemed by a transaction or redemption action with a matching code. |
Sample request
{
"user": {
"user_id": 4232324
},
"entity": {
"chain_id": 1799
},
"vouchers": [
{
"voucher_key": "1b2bb233bbhhb21b1b1b1212121b21ubiu3243299"
}
],
"locking": {
"retailer_basket_code": "20240462148435877",
"voucher_lock_period": 3600
}
}
Returns an OK code and a JSON information of the claimed vouchers.:
{
"result": {
"code": 1,
"status": "ok"
},
"results": {
"vouchers": [
{
"campaign_id": 1,
"campaign_image_dimension_x": null,
"campaign_image_dimension_y": null,
"campaign_image_filename": null,
"campaign_image_link": null,
"campaign_image_url": null,
"campaign_owner_code": null,
"campaign_product_promotion_type": null,
"campaign_title": "Loyalty campaign for FOO Chain, inc.",
"campaign_type": "loyalty",
"creating_user": {
"full_name": "Admin Spaaza",
"user_id": 2
},
"generating_return_transaction": null,
"parent_voucher": null,
"redeeming_basket": null,
"user_entity_card": {
"code": "20000000001",
"type": "custom"
},
"user_id": 4,
"voucher_amount": 20,
"voucher_amount_original": 20,
"voucher_amount_redeemed": 0,
"voucher_created_datetime": "2024-04-24T15:37:06+00:00",
"voucher_currency_code": "EUR",
"voucher_currency_id": 2,
"voucher_currency_symbol": "\u20ac",
"voucher_description": null,
"voucher_discount_ratio": 0,
"voucher_expiry_datetime_utc": "2024-07-23T15:37:06+00:00",
"voucher_expiry_seconds_remaining": 7775999,
"voucher_honour_code": null,
"voucher_id": 1,
"voucher_image_url": null,
"voucher_key": "d333a0b891b473c9ddede5543043c01d5339a074ce19e0b2671e877fa33b990b",
"voucher_locked": false,
"voucher_notes": null,
"voucher_redeemed_datetime": null,
"voucher_status": "claimed",
"voucher_text": null,
"voucher_third_party_id": null,
"voucher_title": null,
"voucher_type": "basket"
},
{
"campaign_id": 1,
"campaign_image_dimension_x": null,
"campaign_image_dimension_y": null,
"campaign_image_filename": null,
"campaign_image_link": null,
"campaign_image_url": null,
"campaign_owner_code": null,
"campaign_product_promotion_type": null,
"campaign_title": "Loyalty campaign for FOO Chain, inc.",
"campaign_type": "loyalty",
"creating_user": {
"full_name": "Admin Spaaza",
"user_id": 2
},
"generating_return_transaction": null,
"parent_voucher": null,
"redeeming_basket": null,
"user_entity_card": {
"code": "20000000001",
"type": "custom"
},
"user_id": 4,
"voucher_amount": 20,
"voucher_amount_original": 20,
"voucher_amount_redeemed": 0,
"voucher_created_datetime": "2024-04-24T15:37:06+00:00",
"voucher_currency_code": "EUR",
"voucher_currency_id": 2,
"voucher_currency_symbol": "\u20ac",
"voucher_description": null,
"voucher_discount_ratio": 0,
"voucher_expiry_datetime_utc": "2024-07-23T15:37:06+00:00",
"voucher_expiry_seconds_remaining": 7775999,
"voucher_honour_code": null,
"voucher_id": 2,
"voucher_image_url": null,
"voucher_key": "f7a59feb4393c73f717ac863320c008f96ba6221e3fa3ab3d0e90a21cf79619f",
"voucher_locked": false,
"voucher_notes": null,
"voucher_redeemed_datetime": null,
"voucher_status": "claimed",
"voucher_text": null,
"voucher_third_party_id": null,
"voucher_title": null,
"voucher_type": "basket"
},
{
"campaign_id": 1,
"campaign_image_dimension_x": null,
"campaign_image_dimension_y": null,
"campaign_image_filename": null,
"campaign_image_link": null,
"campaign_image_url": null,
"campaign_owner_code": null,
"campaign_product_promotion_type": null,
"campaign_title": "Loyalty campaign for FOO Chain, inc.",
"campaign_type": "loyalty",
"creating_user": {
"full_name": "Admin Spaaza",
"user_id": 2
},
"generating_return_transaction": null,
"parent_voucher": null,
"redeeming_basket": null,
"user_entity_card": {
"code": "20000000001",
"type": "custom"
},
"user_id": 4,
"voucher_amount": 20,
"voucher_amount_original": 20,
"voucher_amount_redeemed": 0,
"voucher_created_datetime": "2024-04-24T15:37:06+00:00",
"voucher_currency_code": "EUR",
"voucher_currency_id": 2,
"voucher_currency_symbol": "\u20ac",
"voucher_description": null,
"voucher_discount_ratio": 0,
"voucher_expiry_datetime_utc": "2024-07-23T15:37:06+00:00",
"voucher_expiry_seconds_remaining": 7775999,
"voucher_honour_code": null,
"voucher_id": 3,
"voucher_image_url": null,
"voucher_key": "26fd293d39d9c621a6fb937faa1ee033de3a049fffdff1e11d914589a3788cf4",
"voucher_locked": false,
"voucher_notes": null,
"voucher_redeemed_datetime": null,
"voucher_status": "claimed",
"voucher_text": null,
"voucher_third_party_id": null,
"voucher_title": null,
"voucher_type": "basket"
},
{
"campaign_id": 1,
"campaign_image_dimension_x": null,
"campaign_image_dimension_y": null,
"campaign_image_filename": null,
"campaign_image_link": null,
"campaign_image_url": null,
"campaign_owner_code": null,
"campaign_product_promotion_type": null,
"campaign_title": "Loyalty campaign for FOO Chain, inc.",
"campaign_type": "loyalty",
"creating_user": {
"full_name": "Admin Spaaza",
"user_id": 2
},
"generating_return_transaction": null,
"parent_voucher": null,
"redeeming_basket": null,
"user_entity_card": {
"code": "20000000001",
"type": "custom"
},
"user_id": 4,
"voucher_amount": 20,
"voucher_amount_original": 20,
"voucher_amount_redeemed": 0,
"voucher_created_datetime": "2024-04-24T15:37:06+00:00",
"voucher_currency_code": "EUR",
"voucher_currency_id": 2,
"voucher_currency_symbol": "\u20ac",
"voucher_description": null,
"voucher_discount_ratio": 0,
"voucher_expiry_datetime_utc": "2024-07-23T15:37:06+00:00",
"voucher_expiry_seconds_remaining": 7775999,
"voucher_honour_code": null,
"voucher_id": 4,
"voucher_image_url": null,
"voucher_key": "72f781ddd8a8ab121103de7a00243c50091344b47fcbff167afae09699066d72",
"voucher_locked": false,
"voucher_notes": null,
"voucher_redeemed_datetime": null,
"voucher_status": "claimed",
"voucher_text": null,
"voucher_third_party_id": null,
"voucher_title": null,
"voucher_type": "basket"
},
{
"campaign_id": 1,
"campaign_image_dimension_x": null,
"campaign_image_dimension_y": null,
"campaign_image_filename": null,
"campaign_image_link": null,
"campaign_image_url": null,
"campaign_owner_code": null,
"campaign_product_promotion_type": null,
"campaign_title": "Loyalty campaign for FOO Chain, inc.",
"campaign_type": "loyalty",
"creating_user": {
"full_name": "Admin Spaaza",
"user_id": 2
},
"generating_return_transaction": null,
"parent_voucher": null,
"redeeming_basket": null,
"user_entity_card": {
"code": "20000000001",
"type": "custom"
},
"user_id": 4,
"voucher_amount": 20,
"voucher_amount_original": 20,
"voucher_amount_redeemed": 0,
"voucher_created_datetime": "2024-04-24T15:37:06+00:00",
"voucher_currency_code": "EUR",
"voucher_currency_id": 2,
"voucher_currency_symbol": "\u20ac",
"voucher_description": null,
"voucher_discount_ratio": 0,
"voucher_expiry_datetime_utc": "2024-07-23T15:37:06+00:00",
"voucher_expiry_seconds_remaining": 7775999,
"voucher_honour_code": null,
"voucher_id": 5,
"voucher_image_url": null,
"voucher_key": "41a2eb41409dc7fa028100b6cede593effaf2bb520b1c1dbb7283327df9a86bd",
"voucher_locked": false,
"voucher_notes": null,
"voucher_redeemed_datetime": null,
"voucher_status": "claimed",
"voucher_text": null,
"voucher_third_party_id": null,
"voucher_title": null,
"voucher_type": "basket"
}
],
"result_type": "claim-vouchers"
}
}