Link Search Menu Expand Document

Wallet history

Contents

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 ledger entries for that user in the wallet specified. 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 of entries is returned in reverse chronological order.

The endpoint can be used to return ledger entries for the following wallet/campaign types:

  • Wallet (monetary)
  • Points Wallet
  • Entries Wallet
  • Progress Campaign
  • Item Purchase Count Campaign

Version-specific information

The following version-specific changes apply to this endpoint.

Version Change details
>= 1.5.4 Privileged authentication no longer allows passing a chain_id parameter and an X-Spaaza-MyPrice-App-Hostname header must be used instead
>= 1.5.4 Progress and Item Purchase Count campaign entries can now be returned
>= 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 access to 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 with admin authentication, must not be passed in privileged or user authentication) The id of the chain for which the information is being requested.
user_id OR member_number OR username OR referral_code OR authentication_point_identifier OR auxiliary_identifier (mixed, one required with admin or privileged authentication) The Spaaza unique ID (user_id, integer), member number (member_number, string), email address (username, valid email address), or identity in a third-party authentication system (authentication_point_identifier/auxiliary_identifier, string) of the user for whom the wallet ledger is being requested.
type (string, optional) By default all contributions are returned for Wallet, Points Wallet, Entries Wallet, Progress and Item Purchase Count campaigns. 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 (integer, optional) 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 and privileged 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.

Request & Response Information

Request (#request)

Example curl request:

curl --location 'https://api0.spaaza.com/user-wallet-ledger?chain_id=1743&user_id=843382423' \
--header 'X-Spaaza-API-version: 1.4.8' \
--header 'X-MyPrice-App-Hostname: acme.spaaza.com' \
--header 'X-Spaaza-Session-User-Id: 1' \
--header 'X-Spaaza-Session-Key: 6e5ff45a634201f2c8b596a2fff633471f301c49b9d26bf4517c82efa57a163b' \
--header 'Accept-Language: en-US'

Response (#response)

The response can contain the following fields:

It will return each wallet ledger entry 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’.

Example response:

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"
    }
}

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