Wallet history
An example response with the wallet history for a customer (“type” parameter is “wallet”)
{
"result": {
"code": 1,
"status": "ok"
},
"results": {
"ledger": [
{
"amount": 1.5,
"branch_business_id": 2774,
"contributing_campaign_field_localisations": null,
"contributing_campaign_id": 123,
"contributing_campaign_title": "Earn as you spend",
"contributing_campaign_type": "cashback",
"currency_symbol": "€",
"date": "2021-05-05T09:28:53+00:00",
"kind": "campaignContribution",
"mutator_id": null,
"mutator_name": null,
"receipt_id": 477939,
"retailer_basket_code": "19_04_2021_1",
"return_transaction_receipt_id": null,
"return_transaction_retailer_basket_code": null,
"wallet_campaign_id": 149,
"wallet_campaign_title": "Acme wallet",
"wallet_campaign_type": "wallet"
},
{
"amount": 10,
"branch_business_id": null,
"contributing_campaign_field_localisations": null,
"contributing_campaign_id": null,
"contributing_campaign_title": "Thanks for influencing",
"contributing_campaign_type": "manual",
"currency_symbol": "€",
"date": "2021-04-19T13:46:51+00:00",
"kind": "manual",
"mutator_id": 21,
"mutator_name": "Dave Sevenoaks",
"receipt_id": null,
"retailer_basket_code": null,
"return_transaction_receipt_id": null,
"return_transaction_retailer_basket_code": null,
"wallet_campaign_id": 150,
"wallet_campaign_title": "Jeans Center store credit",
"wallet_campaign_type": "wallet"
}
],
"type": "wallet",
"result_type": "user-wallet-ledger"
}
}
An example response with the points history for a customer (“type” parameter is “points”)
{
"result": {
"code": 1,
"status": "ok"
},
"results": {
"ledger": [
{
"amount": 20,
"branch_business_id": null,
"contributing_campaign_field_localisations": null,
"contributing_campaign_id": null,
"contributing_campaign_title": "Enjoy 10 points on us!",
"contributing_campaign_type": "manual",
"currency_symbol": "PTN",
"date": "2021-04-19T12:30:44+00:00",
"kind": "manual",
"mutator_id": 21,
"mutator_name": "Dave Sevenoaks",
"receipt_id": null,
"retailer_basket_code": null,
"return_transaction_receipt_id": null,
"return_transaction_retailer_basket_code": null,
"wallet_campaign_id": 149,
"wallet_campaign_title": "ACME points",
"wallet_campaign_type": "points_wallet"
},
{
"amount": 5,
"branch_business_id": null,
"contributing_campaign_field_localisations": null,
"contributing_campaign_id": 1408,
"contributing_campaign_title": "Earn 1 point on every €",
"contributing_campaign_type": "cashback",
"currency_symbol": "PTN",
"date": "2021-04-19T12:29:36+00:00",
"kind": "campaignContribution",
"mutator_id": null,
"mutator_name": null,
"receipt_id": 477259,
"retailer_basket_code": "19_04_2021_1",
"return_transaction_receipt_id": null,
"return_transaction_retailer_basket_code": null,
"wallet_campaign_id": 149,
"wallet_campaign_title": "ACME points",
"wallet_campaign_type": "points_wallet"
}
],
"result_type": "user-wallet-ledger",
"type": "points_wallet"
}
}
An example response showing points and wallet contributions (no type parameter passed)
{
"result": {
"code": 1,
"status": "ok"
},
"results": {
"ledger": [
{
"amount": 1.5,
"branch_business_id": 2774,
"contributing_campaign_field_localisations": null,
"contributing_campaign_id": 123,
"contributing_campaign_title": "Earn as you spend",
"contributing_campaign_type": "cashback",
"currency_symbol": "€",
"date": "2021-05-05T09:28:53+00:00",
"kind": "campaignContribution",
"mutator_id": null,
"mutator_name": null,
"receipt_id": 477939,
"retailer_basket_code": "19_04_2021_1",
"return_transaction_receipt_id": null,
"return_transaction_retailer_basket_code": null,
"wallet_campaign_id": 149,
"wallet_campaign_title": "Acme wallet",
"wallet_campaign_type": "wallet"
},
{
"amount": 10,
"branch_business_id": null,
"contributing_campaign_field_localisations": null,
"contributing_campaign_id": null,
"contributing_campaign_title": "Thanks for influencing",
"contributing_campaign_type": "manual",
"currency_symbol": "€",
"date": "2021-04-19T13:46:51+00:00",
"kind": "manual",
"mutator_id": 21,
"mutator_name": "Dave Sevenoaks",
"receipt_id": null,
"retailer_basket_code": null,
"return_transaction_receipt_id": null,
"return_transaction_retailer_basket_code": null,
"wallet_campaign_id": 150,
"wallet_campaign_title": "Jeans Center store credit",
"wallet_campaign_type": "wallet"
},
{
"amount": 20,
"branch_business_id": null,
"contributing_campaign_field_localisations": null,
"contributing_campaign_id": null,
"contributing_campaign_title": "Enjoy 10 points on us!",
"contributing_campaign_type": "manual",
"currency_symbol": "PTN",
"date": "2021-04-19T12:30:44+00:00",
"kind": "manual",
"mutator_id": 21,
"mutator_name": "Dave Sevenoaks",
"receipt_id": null,
"retailer_basket_code": null,
"return_transaction_receipt_id": null,
"return_transaction_retailer_basket_code": null,
"wallet_campaign_id": 149,
"wallet_campaign_title": "ACME points",
"wallet_campaign_type": "points_wallet"
},
{
"amount": 5,
"branch_business_id": 2774,
"contributing_campaign_field_localisations": null,
"contributing_campaign_id": 1408,
"contributing_campaign_title": "Earn 1 point on every €",
"contributing_campaign_type": "cashback",
"currency_symbol": "PTN",
"date": "2021-04-19T12:29:36+00:00",
"kind": "campaignContribution",
"mutator_id": null,
"mutator_name": null,
"receipt_id": 477259,
"retailer_basket_code": "19_04_2021_1",
"return_transaction_receipt_id": null,
"return_transaction_retailer_basket_code": null,
"wallet_campaign_id": 149,
"wallet_campaign_title": "ACME points",
"wallet_campaign_type": "points_wallet"
}
],
"result_type": "user-wallet-ledger",
"type": "wallet"
}
}
Overview
- Call name: user-wallet-ledger
- Endpoint URL: https://api0.spaaza.com/user-wallet-ledger
- Request methods: GET
- Response Content-Type: application/json
- Auth required: yes
The user-wallet-ledger API retrieves the contributions that have been made to that user’s Spaaza Points balance and/or Spaaza Wallet. Points or Wallet contributions can happen as a result of a campaign in Spaaza, a manual adjustment by a staff member or as a result of the user spending a portion of a saved wallet amount. The list is returned in reverse chronological order.
It will return each “contribution” with the following data:
-
date, the date and time the contribution was made in ISO8601 format including timezone offset from UTC. -
currency_symbol, the currency symbol for the contribution. -
amount, the value of the contribution (can be positive or negative). -
receipt_id, the id of the transaction that resulted in the contribution (can also be null if the contribution was not as a result of a transaction). -
retailer_basket_code, the identifier in the retailer’s system of the transaction that resulted in the contribution (can also be null if the contribution was not as a result of a transaction). -
contributing_campaign_id, the id of the campaign that caused the contribution. -
contributing_campaign_type, the type of campaign that caused the contribution, this will be one of ‘cashback’, ‘wallet’ or ‘manual’. -
contributing_campaign_title, the name of the campaign that caused the contribution or the reason for a manual change to a wallet. -
wallet_campaign_id, the id of the wallet or points wallet campaign. -
wallet_campaign_type, the type of wallet campaign, this will be one of ‘wallet’, ‘points_wallet’ or ‘entries_wallet’. -
wallet_campaign_title, the title of the wallet campaign. -
mutator_id, the id of the user that created a manual points or wallet mutation. -
mutator_name, the full name of the user that created a manual points or wallet mutation. -
kind, the type of event that caused the contribution, this will be one of ‘campaignContribution’, ‘voucherRedemption’ or ‘manual’.
Versioning-specific information
The following version-specific changes apply to this endpoint.
| Version | Change details |
|---|---|
| >= 1.5.1 | entries_wallet ledger entries are now returned and it is possible to filter by type to entries |
| >= 1.4.1 | date fields in the response are returned in ISO8601 format including timezone offset from UTC instead of the former YYYY-MM-DD HH:MM:SS format. |
| >= 1.4.4 | campaign_type and campaign_title are now returned as contributing_campaign_type and contributing_campaign_title. |
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
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 required for admin authentication | The id of the chain for which the information is being requested. |
| user_id OR member_number OR authentication_point_identifier required with admin or privileged authentication | The Spaaza unique ID (user_id), member_number (user code) or identity in a third-party authentication system (authentication_point_identifier) of the user for whom the wallet ledger is being requested. |
| type | By default all contributions are returned for both the Wallet, Points and Entries Wallet balance. If you only want wallet contributions use ‘wallet’. If you only want points contributions use ‘points’. If you only want entries wallet contributions use ‘entries’ |
| wallet_campaign_id (int) | The campaign_id of a specific points or monetary wallet. Providing a campaign_id in the request params will filter results in the response to only include progress contributed to this particular points or monetary wallet. |
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 authentication) The hostname of the app for which the user is requesting the card. |
| Accept-Language | (optional) A standard RFC 2616 header defining the ordered language preferences for the request. In the case that this is provided, localised versions of field names are also returned in the response where these are defined. The presence of localised fields is dynamic. If they are not defined in the field_localisations field for the specific object, then localised fields are not returned. |
Possible error responses
The following represents a list of possible error responses for the user-wallet-ledger endpoint:
| Code | Name and Description | HTTP Status Code |
|---|---|---|
| 6 | no_valid_session The user needs to be logged in and a valid session key needs to be sent | 401 |
| 68 | permission_denied_or_non_existent This user has insufficient permissions for this object or the object does not exist. | 500 |
| 154 | user_id_invalid The user_id passed must be an integer up to 10 digits long | 400 |
| 217 | chain_id_not_found No record has been found for that chain_id | 400 |
| 228 | auth_method_invalid The given auth_method parameter has an invalid value. | 500 |
| 264 | myprice_app_without_entity The requested MyPrice app does not have an entity associated with it. | 400 |
| 265 | authorization_invalid The given authorization header is invalid. | 400 |
| 266 | access_token_invalid The given access token is invalid. | 401 |
| 267 | no_valid_user A valid username needs to be specified | 401 |
| 269 | no_myprice_app Myprice app is required | 400 |
| 270 | user_not_found No user was found | 404 |
| 328 | wallet_not_found No wallet was found for this chain | 400 |
| 405 | entity_mismatch The entities or chains supplied do not match | 400 |
| 416 | multiple_parameter_mismatch Multiple parameters supplied when fewer are required | 400 |
| 464 | entity_code_mismatch The campaign_id does not match entity_id | 400 |
| 470 | wallet_award_mismatch The wallet type is inconsistent with request type | 400 |