Wallet history

An example response with the wallet history for a customer (“type” parameter is “wallet”)

{
  "result": {
    "code": 1,
    "status": "ok"
  },
  "results": {
    "type": "wallet",
    "ledger": [
      {
        "date": "2021-05-05T09:28:53+00:00",
        "currency_symbol": "€",
        "amount": 1.5,
        "receipt_id": 477939,
        "retailer_basket_code": "19_04_2021_1",
        "contributing_campaign_id": 123,
        "contributing_campaign_type": "cashback",
        "contributing_campaign_title": "Earn as you spend",
        "contributing_campaign_field_localisations": null,
        "wallet_campaign_id": 149,
        "wallet_campaign_type": "wallet",
        "wallet_campaign_title": "Acme wallet",
        "kind": "campaignContribution",
        "mutator_id": null,
        "mutator_name": null
      },
      {
        "date": "2021-04-19T13:46:51+00:00",
        "currency_symbol": "€",
        "amount": 10,
        "receipt_id": null,
        "retailer_basket_code": null,
        "contributing_campaign_id": null,
        "contributing_campaign_type": "manual",
        "contributing_campaign_title": "Thanks for influencing",
        "contributing_campaign_field_localisations": null,
        "wallet_campaign_id": 150,
        "wallet_campaign_type": "wallet",
        "wallet_campaign_title": "Jeans Center store credit",
        "kind": "manual",
        "mutator_id": 21,
        "mutator_name": "Dave Sevenoaks"
      }
    ],
    "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": {
    "type": "points_wallet",
    "ledger": [
      {
        "date": "2021-04-19T12:30:44+00:00",
        "currency_symbol": "PTN",
        "amount": 20,
        "receipt_id": null,
        "retailer_basket_code": null,
        "contributing_campaign_id": null,
        "contributing_campaign_type": "manual",
        "contributing_campaign_title": "Enjoy 10 points on us!",
        "contributing_campaign_field_localisations": null,
        "wallet_campaign_id": 149,
        "wallet_campaign_type": "points_wallet",
        "wallet_campaign_title": "ACME points",
        "kind": "manual",
        "mutator_id": 21,
        "mutator_name": "Dave Sevenoaks"
      },
      {
        "date": "2021-04-19T12:29:36+00:00",
        "currency_symbol": "PTN",
        "amount": 5,
        "receipt_id": 477259,
        "retailer_basket_code": "19_04_2021_1",
        "contributing_campaign_id": 1408,
        "contributing_campaign_type": "cashback",
        "contributing_campaign_title": "Earn 1 point on every €",
        "contributing_campaign_field_localisations": null,
        "wallet_campaign_id": 149,
        "wallet_campaign_type": "points_wallet",
        "wallet_campaign_title": "ACME points",
        "kind": "campaignContribution",
        "mutator_id": null,
        "mutator_name": null
      }
    ],
    "result_type": "user-wallet-ledger"
  }
}

An example response showing points and wallet contributions (no type parameter passed)

{
  "result": {
    "code": 1,
    "status": "ok"
  },
  "results": {
    "type": "wallet",
    "ledger": [
      {
        "date": "2021-05-05T09:28:53+00:00",
        "currency_symbol": "€",
        "amount": 1.5,
        "receipt_id": 477939,
        "retailer_basket_code": "19_04_2021_1",
        "contributing_campaign_id": 123,
        "contributing_campaign_type": "cashback",
        "contributing_campaign_title": "Earn as you spend",
        "contributing_campaign_field_localisations": null,
        "wallet_campaign_id": 149,
        "wallet_campaign_type": "wallet",
        "wallet_campaign_title": "Acme wallet",
        "kind": "campaignContribution",
        "mutator_id": null,
        "mutator_name": null
      },
      {
        "date": "2021-04-19T13:46:51+00:00",
        "currency_symbol": "€",
        "amount": 10,
        "receipt_id": null,
        "retailer_basket_code": null,
        "contributing_campaign_id": null,
        "contributing_campaign_type": "manual",
        "contributing_campaign_title": "Thanks for influencing",
        "contributing_campaign_field_localisations": null,
        "wallet_campaign_id": 150,
        "wallet_campaign_type": "wallet",
        "wallet_campaign_title": "Jeans Center store credit",
        "kind": "manual",
        "mutator_id": 21,
        "mutator_name": "Dave Sevenoaks"
      },
      {
        "date": "2021-04-19T12:30:44+00:00",
        "currency_symbol": "PTN",
        "amount": 20,
        "receipt_id": null,
        "retailer_basket_code": null,
        "contributing_campaign_id": null,
        "contributing_campaign_type": "manual",
        "contributing_campaign_title": "Enjoy 10 points on us!",
        "contributing_campaign_field_localisations": null,
        "wallet_campaign_id": 149,
        "wallet_campaign_type": "points_wallet",
        "wallet_campaign_title": "ACME points",
        "kind": "manual",
        "mutator_id": 21,
        "mutator_name": "Dave Sevenoaks"
      },
      {
        "date": "2021-04-19T12:29:36+00:00",
        "currency_symbol": "PTN",
        "amount": 5,
        "receipt_id": 477259,
        "retailer_basket_code": "19_04_2021_1",
        "contributing_campaign_id": 1408,
        "contributing_campaign_type": "cashback",
        "contributing_campaign_title": "Earn 1 point on every €",
        "contributing_campaign_field_localisations": null,
        "wallet_campaign_id": 149,
        "wallet_campaign_type": "points_wallet",
        "wallet_campaign_title": "ACME points",
        "kind": "campaignContribution",
        "mutator_id": null,
        "mutator_name": null
      }
    ],
    "result_type": "user-wallet-ledger"
  }
}

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’ or ‘points_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.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 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 and Points balance. If you only want wallet contributions use “wallet”. If you only want points contributions use “points”.
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