Welcome

Spaaza’s API allows developers to create their own applications on top of the Spaaza platform. All Spaaza’s in-house apps and other services make use of the API endpoints described in this documentation.

Please get in touch with us using the chat button at spaaza.com if you have any more questions.

Other resources

POSTMAN collection

POSTMAN is a great application for helping test API calls - configure and view all details of requests and responses to most APIs. You can use environment files to configure parameters passed and it provides code snippets so you can recreate the calls in your own project.

Spaaza has its own POSTMAN “collection” - a grouping of calls configured for the Spaaza API endpoints. Just import the Spaaza collection and environment file into POSTMAN, fill in your Spaaza API authentication and configuration details in the environment file and you can start making calls straight away.

You can download the Spaaza POSTMAN collection from our repo:

Spaaza POSTMAN collection

Check back frequently for updates.

YouTube channel

There are some videos on the Spaaza YouTube channel including the following:

Getting started with the Spaaza API

More of these are coming soon - we’re adding guides and videos frequently.

Concepts

This section of the documentation explains some of the core concepts used by Spaaza, and vocabulary used to describe them. We highly recommend reading this to provide some background which will help understand what our API endpoints aim to do, and how they work.

User

In the Spaaza data model, a ‘user’ is an object representing an individual person with an account.

User Types

Spaaza has two types of users: end-users and administrative (“admin”) users. These are described below.

End-User

An end-user is an end-customer consuming a Spaaza service - that’s to say a real-life person with an account. Examples might be:

• An identified shopper ordering an item in a webshop
• A customer in a retailer’s physical store
• Someone using a Spaaza white-label retailer or customer organisation app at home
• A member of a digitally-provided service such as a car-sharing network who’s making use of incentives available when they drive a car

End-users are always associated with a particular Spaaza retailer or customer organisation, and are often a member of a loyalty or incentive marketing programme run by Spaaza, and hence have a ‘member number’ (sometimes referred to as a ‘customer number’). It is also possible for end-users to have other identifiers, such as an ‘auxiliary identifier’ or an ‘authentication point identifier’.

Many Spaaza API endpoints are available for adding end-users, viewing and updating their properties, carrying out actions on their behalf, and deleting their accounts.

End-users are often referred to as “customers” or “members.”

Administrative (“Admin”) User

An administrative (“admin”) user is an employee or other administrative account associated with a Spaaza retailer or customer organisation. Admin users have rights to view data and carry out actions on behalf of a retailer, or on behalf of an end-user associated with the retailer. Every admin user has permissions allowing them to carry out specific actions in administrative apps Spaaza provides, such as our “Console” site, and in the Spaaza API.

Examples of admin users are:

• A store employee logging into a Spaaza-provided “Store” site to create an end-user account for a customer
• A head office employee logging into the “Console” admin portal to configure campaigns and check analytics for a Spaaza promotional campaign
• A POS device in a store uploading transaction information

Admin users are treated separately from end-users. They do not take part in any campaign- or transaction-related incentive activities such as earning points, redeeming vouchers, or uploading transactions.

A Spaaza retailer normally has one or more admin users with “super user” permissions, who have the power to add, update and delete other admin user accounts.

Basket

In the Spaaza data model, a ‘basket’ represents an end-user or customer transaction stored in the backend. Each basket is associated with a Spaaza retailer or customer organisation and is sent to Spaaza either via Spaaza’s add-basket API endpoint or imported in bulk by Spaaza using one of our operations import scripts.

It is also possible to send the contents of a provisional basket to Spaaza via our get-basket-price API endpoint and Spaaza will respond with any adjustments to that basket. See the ‘Provisional or adjusted Basket’ section below.

When purchased items are returned, this is not seen by Spaaza as an adjustment to a confirmed basket (see below for the distinction between confirmed and provisional baskets), but as a new basket with returned items which are linked to an original purchase basket. For more information, please see our documentation on ‘Processing a return inline’.

Please see the documentation below for more information about types of basket in the Spaaza model, and some of the important properties and concepts associated with baskets.

Types of basket

Spaaza has two types of basket. These are explained below.

Confirmed basket

When a basket is sent to Spaaza using our add-basket API endpoint, it is stored in the Spaaza database. Unlike in some e-commerce systems, a confirmed basket stored in Spaaza is immutable and cannot be updated once it has been transmitted - this includes payment and tax details.

Spaaza retailers and customer organisations also make use of the facility to import large numbers of transactions in bulk. This is performed on a custom basis by Spaaza using our internally-available bulk import scripts and is usually carried out to import large numbers of historical baskets.

Provisional or adjusted basket

Spaaza’s data model has the concept of an adjusted or provisional basket. This is not a basket which is stored in the Spaaza backend, but is designed to return adjustments to a basket which apply to an individual end-user, and which can be applied to the confirmed basket or transaction when it is sent by the API client. It’s possible to request an adjusted basket multiple times and receive a different response each time.

Spaaza’s provisional basket API endpoint, (get-basket-price)[#requesting-an-adjusted-basket], is used to request adjustments to the supplied basket, which may include vouchers the end-user (customer) is entitled to use, and discounts at the item or basket level.

A good example of how a provisional basket works is as follows:

• Customer logs into e-commerce site and is opted into the site’s loyalty programme
• Customer adds items to cart in e-commerce site
• E-ecommerce site makes a request to Spaaza’s (get-basket-price endpoint)[#requesting-an-adjusted-basket], including information about the customer, items in the basket, prices and total order value
• Spaaza responds with an adjusted basket, including vouchers the customer has indicated they would like to spend and an adjusted total order amount
• E-commerce site adjusts total amount the customer pays based on the response received from Spaaza
• Customer pays for the order in the e-commerce site
• E-ecommerce site sends confirmed basket with adjusted values

Campaign

In the Spaaza data model, a ‘campaign’ does not only describe a traditional “promotional campaign” or “advertising campaign,” but has a much broader definition. A Spaaza ‘campaign’ represents a set of logic and actions which can be applied to end-users across the whole of the domain associated with a retailer or customer organisation. Spaaza has a set of API endpoints which can be used to add, view, manage or delete campaigns and their properties in order to affect the end-user experience. Additionally, a broad suite of analytics tools is provided to track performance of campaigns and the customers who make use of them.

For example, each of the following examples is managed as a campaign in Spaaza:

• Points wallet - using a ‘wallet campaign’ is it possible to give each customer a points wallet and add points to or remove them from the wallet when events occur such as signing up for membership, or making a purchase. Fine-grained actions are possible using customer segments, such as “double points between 2 PM and 6 PM on a Tuesday in Anytown branch store for customers who previously bought ACME-branded products.”
• Referral rewards - it is possible to configure a ‘referral campaign’ which rewards both a customer and their friend with a voucher when the customer signs their friend up and the friend makes a purchase.
• Order-level discount - a ‘basket campaign’ can be used to give opted-in customers a percentage- or monetary-based discount on one or multiple baskets
• Loyalty programme - a loyalty campaign and associated loyalty rules can be used to configure an entire loyalty programme with loyalty levels and rewards based on status and actions within the programme

Managing campaigns and monitoring performance

In almost all cases, campaigns are managed using the Spaaza Console portal. Performance is also tracked via the Spaaza console using our realtime analytics and graphing tools.

Campaign types

It is possible to configure and manage multiple types of campaign through the Spaaza API. A brief explanation of each campaign type is provided below:

• Basket (Discount) - a basket (discount) campaign is used to apply a percentage discount to qualifying baskets, based on combinations of items in the basket, total basket value, end-user (customer) segment or other parameters.
• Birthday - a birthday campaign allows the issuing of rewards such as points or vouchers to registered customers on or around their birthday.
• Content - content and mobile content campaigns are used to manage content appearing in media properties associated with a retailer or customer organisation, such as white-label mobile apps.
• Interaction - interaction campaigns are used to carry out defined actions when an end-user (customer) interacts with a retailer. Usually in this case the Spaaza backend is notified of an interaction via the interact-campaign API endpoint and then, for example, a reward such as a voucher, discount, free product or points amount is granted to the end-user.
• Login - a login campaign is used to reward the customer, or carry out another action, when a registered end-user (customer) first logs in to a retailer property via the Spaaza login endpoint. The campaign can be filtered so this only applies when the login request is sent by specific types of client.
• Loyalty - a loyalty campaign is used to manage all aspects of a loyalty campaign, such as status levels, associated discounts, points awards and status review cycles. Concepts associated with loyalty campaigns can include loyalty rules and loyalty status levels configurable via the Spaaza Console portal.
• Points Wallet - a points wallet is a ledger-based campaign which assigns a points wallet to individual end-users (customers) and can have amounts added to or removed from it, such as when a customer makes a purchase or interacts with an ‘Interaction’ campaign. Amounts in the points wallet can be converted into rewards and achieving a certain balance can be used as a trigger for ‘Loyalty’ campaign actions, such as changes in status level. Contributor campaigns, such as ‘Spend and Earn,’ can be configured to add amounts to the wallet when certain actions occur.
• Product (Discount) - product (discount) campaigns are used to provide personalised, item-level discounts on individual purchase items in a basket.
• Profile Completion - a profile completion campaign is used to reward an end-user (customer) on completion of their profile. It is possible to configure which profile parameters are required before a reward is issued.
• Purchase Count (Purchase Number) - a purchase count campaign is used to reward an end-user (customer) on their _N_th purchase. It is possible to filter basket value to a minimum limit and rewards are configurable.
• Referral - a referral campaign rewards an end-user (customer) for inviting their friends and contacts to register. It is possible to reward both invitee and inviter with differing rewards and also restrict the moment of reward to the moment the invitee makes their first purchase.
• Signup - a signup campaign rewards an end-user (customer) when they first create an account and opt-in to the associated incentive or loyalty programme.
• Spend & Earn - a spend and earn campaign is a type of “contributor” campaign which contributes points or wallet balance to an end-user’s (customer’s) (points) wallet at a defined percentage of basket value, or for a certain amount, when a purchase is made.
• Spend Target (Progress) - a spend target, or progress, campaign is used to reward an end-user (customer) when they reach a certain level of spending. Filters can be configured on spending, such as whether the target only applies to in-store or online purchases, and rewards are also configurable.
• Wallet - a (monetary) wallet is a ledger-based campaign which assigns a wallet to individual end-users (customers) and can have amounts added to or removed from it, such as when a customer makes a purchase or interacts with an ‘Interaction’ campaign. Amounts in the wallet can be redeemed as a discount on baskets by converting a specified amount of the balance into a wallet voucher. “Contributor” campaigns, such as ‘Spend and Earn,’ can be configured to add amounts to the wallet when certain actions occur.

Voucher

In the Spaaza data model, a ‘voucher’ does not only describe a “coupon” concept of a reserved right to a monetary discount on a retailer or customer organisation’s products and services, or a free product. Spaaza’s definition of a voucher broadly means a “title” or “right” which an end-user (customer) can exchange with a retailer or customer organisation against a defined item, reward or other object. In Spaaza, a voucher can be a title to a monetary or percentage discount, a free item, an experience or even an action taken by a third party.

A Spaaza voucher is always tied to a campaign configured in the Spaaza backend. What a voucher entitles an end-user (customer) to depends on the configuration details of the campaign and the type and configuration of the voucher itself.

Some examples of what vouchers are used to represent in the Spaaza data model:

• A fixed percentage discount on a purchase in a participating store or e-commerce site
• A free product when ordering a particular other item on an e-commerce site
• A monetary wallet amount converted into a discount on a purchase
• 10 minutes of free driving when you join a car-sharing service
• A personalised percentage discount on an individual item
• Free branded items in third-party stores
• Invitations to events
• The planting a specified number of trees by a charity when a customer has purchased certain items or services

Issuing vouchers and monitoring voucher redemption

Vouchers can be issued automatically when certain events occur, such as when an end-user (customer) registers for an account or makes a purchase above a certain value, in bulk using Spaaza tasks, or individually using Spaaza’s voucher creation endpoint.

In almost all cases, how vouchers are issued is managed using the campaigns configuration section in the Spaaza Console portal. Redemption analytics can be tracked via the Spaaza console using our realtime analytics and graphing tools.

Voucher types

It is possible to configure and manage multiple types of voucher through the Spaaza API. A brief explanation of each voucher type is provided below:

• Basket - a basket voucher provides a monetary discount at order level on a basket.
• Honour - an honour voucher provides a title to “honour” a third-party promotion and is usually configured with a specific “honour code” which is used to identify the promotion in the third-party system. This is often used to issue free items or provide discounts in third-party locations. Honour vouchers can be used anonymously or tied to individual end-users (customers).
• Percentage Basket - a percentage basket voucher provides a percentage discount at order level on a basket.
• Variable Price (Product) - a variable price or product voucher denotes the right to a personalised percentage or monetary discount on a product at item level in a basket.
• Variable Price Meta (Product Meta) - a variable price metavoucher denotes the right to variable prices on one of a range of products in a basket. During the basket process, a variable price metavoucher is converted into a variable price voucher which is redeemed in a confirmed basket.

Important properties of a voucher

The following is a list of some of the key properties of a voucher:

• Campaign - every voucher is tied to a campaign. A voucher’s campaign dictates its behaviour including when it can be awarded, how it can be redeemed, what happens if it is deleted or redeemed, whether a replacement is generated after a return, and many other aspects of its existence.
• Currency - a currency associated with a voucher. This field is not always populated. For example, in the case of an honour voucher, a currency may not be necessary.
• Description - a longer-form text field which can be displayed in a user interface.
• Discount Ratio - a percentage discount which applies to a “percentage basket” voucher, represented as a decimal.
• Expiry Date - a date and time beyond which it is no longer possible to change details of, or redeem, a voucher
• Image URL - the URL of an image which can be displayed in a user interface in association with a voucher.
• Key - every voucher has a unique key which can be used to identify it when retrieving details about it or carrying out actions on it such as claiming or redeeming it (see “Voucher status” section).
• Locking - to prevent fraud, a voucher can and should be locked during a transaction - see “Voucher locking” section below.
• Parent Voucher - in the case that a voucher has been redeemed in a transaction, and items purchased in that transaction are subsequently returned, a new voucher is created which represents the value of the voucher originally redeemed on the item(s) in the purchase transaction. The original voucher is listed as the “parent” of the new voucher.
• Status - see “Voucher status” section below.
• Title - a title or text string which can be displayed in a user interface.
• Value - a monetary value assigned to a voucher. This field is not always populated, for example in the case of an honour voucher, which may be redeemed in exchange for a free item.

Voucher status

Each voucher in Spaaza has a status. A voucher’s status dictates which properties a voucher can exhibit and which actions can be carried out on a voucher. The statuses are as follows:

• generated - a voucher exists in the Spaaza data store and may have been assigned to an end-user (customer), but cannot yet be redeemed or exchanged (until it has “claimed” status).
• claimed - an end-user (customer) who “owns” the voucher or an admin user or system has flagged the voucher as being ready to be redeemed in a transaction or other event. In order to be redeemed, a voucher must have this status.
• redeemed - a voucher has been redeemed (used) in a transaction or other event. The voucher can no longer be used or be altered in any way.

The following points regarding voucher status are also to be noted:

• A voucher is normally created with a status of ‘generated,’ but it is possible to configure a campaign to “auto-claim” vouchers when they are created, meaning they will be created with status ‘claimed’.
• It is possible to claim or unclaim a voucher using the claim-voucher and unclaim-voucher endpoints. It is not possible for an end-user (customer) to unclaim a voucher which is “locked” (see “Voucher locking” section).

Voucher locking

To prevent fraud a voucher should be locked before it is redeemed. This prevents an end-user (customer) making adjustments to a voucher when, for example, the value of the voucher is being used as a discount on a transaction. During the time a voucher is locked, it can only be adjusted by an administrative user or using privileged authentication.

A voucher has the following properties related to locking:

• Locked status - if a voucher is locked it will show "locked": true in API responses
• Locking period - a voucher is locked for a period of time. This is shown by the voucher_locked_until field in API responses for a locked voucher, a field representing a date and time until which the voucher is locked
• Exclusive retailer basket code - if a voucher is locked and can only be redeemed by a transaction with a specific retailer_basket_code, this is shown in the voucher_retailer_basket_code_exclusive field.
• Locking code - it is also possible to lock a voucher using a specific code which must also be supplied to redeem the voucher - this is shown in the voucher_locking_code field.

There are 3 ways a voucher can be locked:

• Automatically - during a transaction, when a call is made to the get-basket-price API endpoint, claimed vouchers are automatically locked for the default locking period (usually 5 minutes). If the basket_voucher_lock_exclusively parameter is also supplied, vouchers are locked so that they can only be redeemed by a call to the add-basket API endpoint with the same retailer_basket_code value. It is also possible to specify a different voucher_locking_code using this method, should retailer_basket_code not be a predictable value.
• On Creation - when using the create-voucher API endpoint it is possible to specify a voucher_lock_period to lock the voucher.
• Voucher Locking API Endpoint - the lock-voucher API endpoint can be used to explicitly lock a voucher.

When used with admin or privileged authentication, the unlock-voucher API endpoint can be used to unlock a voucher should that be necessary.

Voucher redemption

There is currently only one possible way to redeem a voucher:

• Transaction - when a claimed, unexpired voucher is added to the payload of a call to the add-basket API endpoint, the voucher is redeemed. Should it not be possible to redeem the voucher, the API call will not error, but will return a warning inline in the response.

Associated API endpoints:

Versioning

Introduction

Occasionally Spaaza makes changes to the payload sent to or response received from an API endpoint. In order to maintain backwards compatibility with existing API clients a versioning policy is put in place. The aim of this policy is to make using endpoint features as simple as possible.

Usually a Spaaza API endpoint maintains backward compatibility without requiring special flags, but in the case that a specific version is required, the API documentation for that endpoint will show clearly what is needed. If there is no information about versioning in the documentation for a specific endpoint, then there is no need to do anything. Spaaza recommends sending an appropriate version header with all API requests.

Occasionally version-specific changes become available in the Spaaza API which affect multiple, or all, endpoints. This kind of change is described in the section API-wide version information below. Again, this kind of change is designed to be non-breaking and as backwards-compatible as possible.

Using a specific endpoint version

With certain Spaaza API endpoints specific versions are implemented. In order to the latest version of an API endpoint, a version header is sent along with the request to the API endpoint. The documentation for a specific endpoint will always contain information about which version number should be used.

The following header is used for specifying a version:

• X-Spaaza-API-version:

Spaaza uses standard semantic numeric major.minor.fix version numbering, for example:

• X-Spaaza-API-version: 1.2.2

API-wide version information

This section includes information about version-specific changes which affect multiple, or all, endpoints in the Spaaza API. In the case that these changes affect all endpoints, for example a change in the way error responses are handled between different versions, a description of the change is not usually included in the documentation for any specific individual endpoints.

A description of each of this kind of version-specific change is shown below.

1.4.1 - Remove URL format requirements

• Remove requirement for .json or .php suffixes at the end of API endpoint URLs
• Remove requirement for v1/ in API endpoint URLs

1.4.0 - Updates to formatting of JSON error responses

• Error responses for all API endpoints updated to reflect semantic correction of errors -> error where only a single error is returned.

API clients using a version number less than 1.4.0 will receive the previous error formatting in the JSON returned in the error response. Documentation for older clients is available on request.

1.1.8 - Updates to formatting of JSON in get-basket-price and add-basket endpoints.

• get-basket-price endpoint request and response JSON updated to change parameter names
• add-basket endpoint request and response JSON updated to change parameter names
• lock-voucher endpoint parameters and response JSON updated to change parameter names

API clients using the above endpoints should use a version number greater than or equal to 1.1.8. Documentation for older clients is available on request.

Responses

Response Format

Unless otherwise indicated in the documentation for individual endpoints the Spaaza API responds with JSON - Content-Type: application/json.

Success

JSON showing a success response to a request:

{
    "result": {
        "code": 1,
        "status": "ok"
    },
    "results": {}
}

If the HTTP request is successful the API will respond with a HTTP response code 200 and a “result” object in JSON showing a status of “ok”. This will be followed by a “results” section showing the results of the request.

Warnings

JSON showing an example warning inline in a success response

{
    "result": {
        "code": 1,
        "status": "ok"
    },
    "warnings": [
        {
            "code": 183,
            "name": "voucher_not_found",
            "description": "No voucher has been found matching this voucher_key or voucher_id.",
            "message": {
                "key": "0886407851fc56c6211f01abe1b4eab1fb1b48640efb73b1169c1d7a50e9467b"
            }
        }
    ],
    "results": {
    }
}

On some occasions a single or multiple warnings are returned as extra information supplementary to the main “results” in a 200 “ok” response, when the issue is not deemed to be of critical severity or when it is not desirable to interrupt the flow of the client. Warnings are returned in their own “warnings” array.

For example, when a transaction is being uploaded by a POS using the add-basket endpoint, but a voucher supplied is not recognised, it is still desirable to record the transaction in the Spaaza database because it has been paid for by the customer. In that case, a warning is added to the 200 “ok” response showing details of the unrecognised voucher.

A list of possible warning codes is found in the “Error and Warning Codes” section below.

Errors

JSON showing a sample error response to a request:

{
    "result": {
        "code": 2,
        "status": "error"
    },
    "error": {
        "code": 5,
        "name": "password_error_or_non_existent",
        "description": "Gebruikersnaam / wachtwoord zijn onbekend"
    }
}

If the response is an error, the API responds with an HTTP error response code and a “result” object showing a status of “error” - the call to the API endpoint is discontinued on generation of the error. This is followed by an “error” object in the response JSON showing the error response - there is only a single error returned.

In the case of an “error” response, no warnings are returned.

See the “error codes” section below for information on individual error codes.

In some cases more information may be supplied with the error to help identify the possible cause, such as a list of which characters are not allowed, or a hint on the format of a postal code.

Note that versions of the API previous to 1.4.0 returned a slightly different error structure. See the ‘Versioning’ section of the documentation. Documentation for older clients is available on request.

Error and Warning Codes

The following is a list of possible error/warning codes:

Authentication

Introduction

Spaaza supports three different authentication methods, with one sub-method. These allow users, admin users and privileged clients such as trusted 3rd parties to consume the Spaaza API.

User Authentication

End user authentication is available for various API endpoints. User authentication uses HTTP headers containing user ID and session key values obtained from the login API endpoint. The following headers must be passed to any API endpoint using user authentication:

• session-user_id: user ID of the user obtained from the login endpoint
• session-key: session key of the session obtained from the login endpoint
• X-MyPrice-App-Hostname: hostname of the Spaaza app the user is affiliated with

Admin Authentication

Admin user authentication is available for various API endpoints. An admin user is a user with permissions to create, update, delete or assign information for a particular Spaaza app or retailer. Admin authentication uses HTTP headers containing user ID and session key values obtained from the login API endpoint. Each time admin authentication is used, the permissions of the user role are checked for validity for the particular endpoint.

The following HTTP headers must be passed to any API endpoint using admin authentication:

• session-user-id: user ID of the user obtained from the login endpoint
• session-key: session key of the session obtained from the login endpoint

Additionally the following HTTP header is often required:

• X-MyPrice-App-Hostname: hostname of the Spaaza app the user wishes to apply the change to

Privileged Authentication

Privileged authentication is available for certain trusted third party systems using various API endpoints. Key exchange is used to supply the API consumer with the correct credentials, which are checked during each use of the endpoint.

The following HTTP authentication header is used to present the API with credentials:

• Authorization: Bearer access token ID:access token secret

Additionally the following HTTP header is often required:

• X-MyPrice-App-Hostname: hostname of the Spaaza app the user wishes to apply the change to

Users

Adding a user

Returns an OK code and a JSON for the user. A sample is shown below:

{ 
   "result":{ 
      "code":1,
      "status":"ok"
   },
   "results":{ 
      "user_info":{ 
         "id":123123,
         "user_id":123123,
         "authentication_point_identifier":"10555454555",
         "first_name":"Foo",
         "last_name":"Bar",
         "gender":"M",
         "birthday":"1986-01-30T00:00:00+00:00",
         "country_code":"NL",
         "address_streetname":"Herengracht",
         "address_housenumber":"504",
         "address_housenumber_extension":"II",
         "address_line_2":"Grachtengordel",
         "address_line_3":"Centrum",
         "address_towncity":"Amsterdam",
         "address_regionstate":"Noord-Holland",
         "address_postalcode":"1017 CB",
         "username":"foo@bar.com",
         "phone_number":"+31-220445641",
         "member_number":"178546",
         "language":"en-GB",
         "opt_in_secondary":true,
         "mailing_list":{ 
            "mailing_list_sub_offered":true,
            "mailing_list_subscribed":false,
            "printed_mailing_list_subscribed":true
         },
         "entity_code":{ 
            "type":"custom",
            "code":"123123"
         },
         "opt_in_programme":{ 
            "programme_opted_in":true,
            "join_date":"2019-04-02T03:05:42+00:00"
         },
         "signup_store":{ 
            "signup_store_id":1383,
            "signup_store_name":"ACME Inc"
         },
         "home_store":{ 
            "home_store_id":2774,
            "home_store_name":"Herengracht HQ"
         },
         "registered":true,
         "is_employee": false,
         "user_type":"new",
         "updated_existing_user":false,
         "loyalty_status":{ 
            "campaign_id":2095,
            "name":"Level 1",
            "description":"Level 1 in the Programme",
            "loyalty_level_id":2,
            "points_to_proceed_next_level":500,
            "points_to_remain_current_level":220,
            "maintenance_points_level":200,
            "last_review_date":"2019-04-04T00:05:22+00:00",
            "next_review_date":"2020-04-04T00:05:22+00:00",
            "date_reached":"2019-06-06T08:06:14+00:00"
         },
         "frequency":3,
         "recency":5,
         "monetary":2,
         "overall":532,
         "stores":null,
         "online_shopper":true,
         "offline_shopper":false,
         "average_basket_value":"119.30",
         "days_since_last_purchase":6,
         "number_of_purchases":4,
         "referring_user":{ 
            "id":3593704,
            "referral_code":"gizyvl"
         },
         "referral_code":"ptola9"
      },
      "result_type":"add-user"
   }
}

Overview

• Call name: add-user
• Endpoint URL: https://api0.spaaza.com/internal/add-user
• Request methods: POST
• Request Content-Type: multipart/form-data or application/x-www-form-urlencoded
• Response Content-Type: application/json
• Auth required: yes
• X-MyPrice-App-Hostname header requirement: mandatory when using privileged authentication
• X-Spaaza-Request header: optional and can be used for to record signup channel (see below)

Introduction

This API call adds information about a new user.

HTTP Parameters

The following HTTP parameters can be passed to the API:

Permissions and Authentication

Admin authentication: the performing user needs to be logged in and have assign 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.

Recording Signup Channel

It is possible to set a header to record the “signup channel” of the user:

Example header:

{"client_channel":"pos"}

Updating an existing user

If the add-user endpoint finds there is already an existing user with the same username, member_number or authentication_point_identifier value, the default behaviour is to return a user_already_exists error with a HTTP 400 response code. When using admin or privileged authentication it is possible to override the default behaviour and update the user account using the parameters supplied in the HTTP POST to add-user.

In order to update an existing user either privileged authentication or admin authentication with assign access must be used.

When a user has been updated instead of created the updated_existing_user flag in the response is set to true and the user_type attribute returns as registered instead of new.

The following points should be noted when using the update_if_exists functionality:

• The functionality detects existing user accounts which have the same username, member_number or authentication_point_identifier attributes as the parameters supplied.
• It is possible to use any of the username, member_number or authentication_point_identifier parameters to update an existing user. Therefore developers coding clients should take care not to update attributes which should be immutable in e.g. a remote system.
• If multiple different existing customers are found based on the username, member_number or authentication_point_identifier parameters supplied, the endpoint returns a too_many_duplicate_objects error.
• Using the update_if_exists parameter also executes updates on remote authentication points such as a webstore, where applicable, and assuming the add-user request does not originate from the remote authentication point.

Possible error responses

The following represents a list of possible error responses for the add-user endpoint:

Altering a user

Returns an OK code and a JSON for the user. A sample is shown below:

{
  "result": {
      "code": 1,
      "status": "ok"
  },
  "results": {
      "user_info": {
          "id": 123123,
          "user_id": 123123,
          "authentication_point_identifier": "10555454555",
          "auxiliary_identifier": "peba4318xel",
          "first_name": "Foo",
          "last_name": "Bar",
          "country_code": "NL",
          "address_streetname": "Herengracht",
          "address_housenumber": "504",
          "address_housenumber_extension": "II",
          "address_line_2": "Grachtengordel",
          "address_line_3": "Centrum",
          "address_towncity": "Amsterdam",
          "address_regionstate": "Noord-Holland",
          "address_postalcode": "1017 CB",
          "lang_code": "en",
          "gender": "F",
          "birthday": "1986-01-30T00:00:00+00:00",
          "username": "foo@bar.com",
          "phone_number": "+31-220445641",
          "member_number": "178546",
          "language": "nl-BE",
          "opt_in_secondary": false,
          "user_facebook_id": "321321",
          "user_facebook_access_token": "dAw2ISsd6asd67ASDLBJKd...",
          "mailing_list": {
              "mailing_list_sub_offered": true,
              "mailing_list_subscribed": false,
              "printed_mailing_list_subscribed": true
          },
          "entity_code": null,
          "opt_in_programme": {
              "programme_opted_in": true,
              "join_date": "2019-06-06T08:06:14+00:00"
          },
          "signup_store": {
              "signup_store_id": 1383,
              "signup_store_name": "ACME Inc"
              },
          "home_store": {
              "home_store_id": 2774,
              "home_store_name": "Herengracht HQ"
          },
          "registered": true,
          "is_employee": true
          "user_type": "registered",
          "loyalty_status": {
              "campaign_id": 2095,
              "name": "Level 1",
              "description": "Level 1 in the Programme",
              "loyalty_level_id": 2,
              "points_to_proceed_next_level": 500,
              "points_to_remain_current_level": 220,
              "maintenance_points_level": 200,
              "last_review_date": "2019-04-04T00:05:22+00:00",
              "next_review_date": "2020-04-04T00:05:22+00:00",
              "date_reached": "2019-06-06T08:06:14+00:00"
          }
      },
      "result_type": "alter-user"
  }
}

Overview

• Call name: alter-user
• Endpoint URL: https://api0.spaaza.com/internal/alter-user
• Request methods: PUT
• Request Content-Type: multipart/form-data or application/x-www-form-urlencoded
• Response Content-Type: application/json
• Auth required: yes
• X-MyPrice-App-Hostname header requirement: mandatory when using privileged authentication

Introduction

This API call modifies information about an existing user.

HTTP Parameters

The following HTTP parameters can be passed to the API:

* In the case of admin authentication, the user whose details are to be altered must be identified by at least one of the parameters user_id, username or authentication_point_identifier.

Note that, in order to remove values such as ‘address_housenumber_extension’ from a user record, it is necessary to send their parameters as empty values.

Permissions and Authentication

Admin authentication: The performing user needs to be logged in and have assign 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.

Retrieving a user

Returns an OK code and a JSON for the user. A sample is shown below:

{ 
   "result":{ 
      "code":1,
      "status":"ok"
   },
   "results":{ 
      "user_info":{ 
         "id":123123,
         "user_id":123123,
         "authentication_point_identifier":"1055550795",
         "auxiliary_identifier":"pevau533xar",
         "first_name":"Foo",
         "last_name":"Bar",
         "country_code":"NL",
         "address_streetname":"Herengracht",
         "address_housenumber":"504",
         "address_housenumber_extension":"II",
         "address_line_2":"Grachtengordel",
         "address_line_3":"Centrum",
         "address_towncity":"Amsterdam",
         "address_regionstate":"Noord-Holland",
         "address_postalcode":"1017 CB",
         "lang_code":"en",
         "gender":"M",
         "birthday":"1900-01-30T00:00:00+00:00",
         "username":"foo@bar.com",
         "phone_number":"+31-220445641",
         "user_facebook_id":"321321",
         "user_facebook_access_token":"dAw2ISsd6asd67ASDLBJKd...",
         "mailing_list":{ 
            "mailing_list_sub_offered":true,
            "mailing_list_subscribed":false,
            "printed_mailing_list_subscribed":false
         },
         "entity_code":{ 
            "type":"regular",
            "code":"3593791"
         },
         "opt_in_programme":{ 
            "programme_opted_in":true,
            "join_date":"2019-06-06T08:06:14+00:00"
         },
         "registered":false,
         "is_employee": false,
         "loyalty_status":{ 
            "campaign_id":2095,
            "name":"Level 1",
            "description":"Level 1 in the Programme",
            "loyalty_level_id":2,
            "points_balance_current":220,
            "points_to_proceed_next_level":500,
            "points_to_remain_current_level":0,
            "last_review_date":"2019-04-04T00:05:22+00:00",
            "next_review_date":"2020-04-04T00:05:22+00:00",
            "date_reached":"2018-04-21T10:00:10+00:00"
         },
         "frequency":3,
         "recency":5,
         "monetary":2,
         "overall":532,
         "stores":null,
         "online_shopper":true,
         "offline_shopper":false,
         "average_basket_value":"119.30",
         "days_since_last_purchase":6,
         "number_of_purchases":4,
         "referring_user":{ 
            "id":4,
            "referral_code": "56uepf"
         },
         "referral_code" : "uyamct"
      },
      "result_type":"get-user"
   }
}

Overview

• Call name: get-user
• Endpoint URL: https://api0.spaaza.com/internal/get-user
• Request methods: GET
• Response Content-Type: application/json
• Auth required: yes
• X-MyPrice-App-Hostname header requirement: mandatory when using privileged authentication or when using the username parameter to look up a user with admin authentication

This API call retrieves information about an existing user.

HTTP Parameters

The following HTTP parameters can be passed to the API:

Permissions

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. This API endpoint allows delegated authentication.

Setting the loyalty level of a user

Returns an OK code and a JSON for the user. A sample is shown below:

{
  "result": {
      "code": 1,
      "status": "ok"
  },
  "results": {
      "loyalty_level": {
          "id": 123,
          "campaign_id": 123123,
          "name": "VIP",
          "description": "VIP level in the Loyalty Programme",
          "automated_level_logic": "0"
          }
      },
      "result_type": "alter-user-loyalty-level"
  }

Overview

• Call name: alter-user-loyalty-level
• Endpoint URL: https://api0.spaaza.com/auth/alter-loyalty-level
• Request methods: PUT
• Auth required: yes
• X-MyPrice-App-Hostname header requirement: mandatory when using privileged authentication
• X-Spaaza-Request header: optional and can be used for to record signup channel (see below)

Introduction

This API call changes the loyalty level of a user to that supplied.

HTTP Parameters

The following HTTP parameters can be passed to the API:

Permissions and Authentication

Admin authentication: the performing user needs to be logged in and have write access to the entity (business or chain) to which the user is connected.

Privileged authentication: the use of privileged authentication is not permitted for this endpoint.

Exporting users (bulk)

curl "-XPOST -v -k \
-H 'X-MyPrice-App-Hostname: retailername.spaaza.com’ \
-H 'Authorization: Bearer <your key>:<your secret>’ \
-d 'export_entity=user’
'https://api0.spaaza.com/auth/export'"

That API end-point will respond with a download link for the CSV file. The link can only be used once and is time limited (currently 48 hours).

[
{
    "result": {
        "code": 1,
        "status": "ok"
    },
    "results": {
        "download_url": "https://services.spaaza.com/export/user?Nonce=2018-03-11T16%3A37%3A21ZAxagGQ9ZmaWBVyFLQZdYsCPWxcmlXoGSWzhCjqKaChA%3D&ChainId=1748&Segment=all",
        "result_type": "spaaza\\api\\auth\\export"
    }
}
]

POST to the API with the post data form encoded and the appropriate headers to specify the app hostname and your credentials.

You can make a GET request to the download link to get the CSV. The link contains a nonce which is signed with a secret known by our API and the download service.

At the moment the download service streams the CSV file over HTTP and it will contain all of the users. A future version will allow you to name a segment of users from the console.

User webhook

An example of a user webhook

{
    "created": "2016-01-08T10:20:35Z",
    "data": {
        "birthday": "1975-07-30",
        "chain_id": 1750,
        "channel": "spaaza-mobile-web",
        "contact_email": "james+nnlive1119@spaaza.com",
        "created": "2016-01-08T10:20:29Z",
        "did_opt_in": true,
        "registered": false,
        "entity_code": "XXX",
        "firstname": "J",
        "gender": "M",
        "lastname": "B",
        "object": "shopper",
        "spaaza_id": 394261,
        "username": "james+nnlive1119@spaaza.com",
        "phone_number": "+31-220445641",
        "address_streetname": "Nieuwe Nieuwstraat",
        "address_housenumber": "104",
        "address_housenumber_extension": "II",
        "address_line_2": "Kleine Buurt",
        "address_line_3": "Centrum",
        "address_towncity": "Hoek van Holland",
        "address_regionstate": "Zuid-Holland",
        "address_postalcode": "1005 AT"
    },
    "id": "568f8d73669bc",
    "object": "event",
    "type": "shopper.opted-in"
}

Spaaza can call external webhooks for certain events, including:

• when the opt-in status of a user changes
• when the user is created

We can configure a webhook URL that you provide. Whenever the event occurs we send a simple POST request to the URL. The body of the POST is JSON that includes details of the event and the shopper that triggered it. So that you can verify that the POST really originates from Spaaza we provide a signature in a request header (X-Spaaza-Hmac-SHA256).

The value of the header is a base 64 encoded HMAC-SHA256 of the whole body of the request with a shared secret that we would provide. Your code to handle the event would need to recreate the signature using the shared secret and compare it to the value in the header.

Status level webhook

An example of a loyalty status level webhook

{
    "type": "shopper.loyalty-level-changed",
    "id": "5b69c11f4bf8c",
    "chain_id": 1743,
    "created": "2018-08-07T15:56:15Z",
    "data": {
        "campaign_id": 201,
        "created_date": "2018-08-07T15:56:15+00:00",
        "id": 80007,
        "log_message": "Manual level change",
        "loyalty_level": {
            "automated_level_logic": true,
            "campaign_id": 201,
            "description": "Silver level in the ACME Programme",
            "id": 4,
            "name": "member"
        },
        "loyalty_level_previous": {
            "automated_level_logic": true
            "campaign_id": 201,
            "description": "Bronze level in the ACME Programme",
            "id": 18,
            "name": "Bronze",
        },
        "mutation_owner_id": 1,
        "user": {
            "address_housenumber": null,
            "address_housenumber_extension": null,
            "address_line_2": null,
            "address_line_3": null,
            "address_postalcode": null,
            "address_regionstate": null,
            "address_streetname": null,
            "address_towncity": null,
            "authentication_point_identifier": "66141993",
            "auxiliary_identifier": "peb209883x",
            "birthday": "1988-05-06T00:00:00+00:00",
            "country_code": "NL",
            "first_name": "Sam",
            "gender": "M",
            "id": 34348394,
            "language": "nl-NL",
            "last_name": "Critchley",
            "loyalty_status": {
                "campaign_id": 201,
                "name": "Silver",
                "description": "Silver level in the ACME Programme",
                "loyalty_level_id": 4,
                "points_balance_current": 340,
                "points_to_proceed_next_level": 410,
                "points_to_remain_current_level": 60,
                "last_review_date": "2019-06-28T09:30:40+00:00",
                "next_review_date": "2020-06-28T09:30:40+00:00",
                "date_reached": "2019-08-23T13:33:15+00:00"
            },
            "mailing_list": {
                "mailing_list_sub_offered": false,
                "mailing_list_subscribed": true,
                "printed_mailing_list_subscribed": false
            },
            "member_number": {
                "code": "30359901",
                "type": "custom"
            },
            "opt_in_programme": {
                "programme_opted_in": true,
                "join_date": "2019-06-06T08:06:14+00:00"
            },
            "opt_in_secondary": false,
            "push_notification_subscription": {
                "subscribed": false,
                "subscriptions": []
            },
            "registered": true,
            "signup_channel": "webshop",
            "user_id": 34348394,
            "username": "acmestage691228534@cowcam.com"
        },

    }
}

Spaaza can call an external webhook when there is a change in a customer’s loyalty level.

We can configure a webhook URL that you provide. Whenever the voucher-issued event occurs we send a simple POST request to the URL. The body of the POST is JSON that includes details of the event and the voucher that triggered it. So that you can verify that the POST really originates from Spaaza we provide a signature in a request header (X-Spaaza-Hmac-SHA256).

The value of the header is a base 64 encoded HMAC-SHA256 of the whole body of the request with a shared secret that we would provide. Your code to handle the event should recreate the signature using the shared secret and compare it to the value in the header.

Note that the ‘data’ section of the webhook payload includes information about the user whose status has changed and about the new level:

Logging users in

If the session is valid, the login call returns information about the user and the session, including: key, length of validity in hours and the authentication method used to establish the key. An example is shown below:

[
  {
    "result": {
        "code": 1,
        "status": "ok"
    },
    "results": {
        "result_type": "login",
        "session_info": {
            "session_key": "acc5cf311f4bce26feaa80de400e2f294ff6168f49da765f0a4d6a798900460f",
            "session_key_validity": "336",
            "session_auth_method": "password",
            "session_user_id": 114521,
            "session_username": "test56767@spaaza.com",
            "session_expires_date": "2020-04-06 11:19:10"
        },
        "user_info": {
            "id": 114521,
            "user_id": 114521,
            "first_name": "Sam",
            "last_name": "Critchley",
            "gender": "M",
            "birthday": "2014-10-21T00:00:00+00:00",
            "username": "test56767@spaaza.com",
            "mailing_list": {
                "mailing_list_sub_offered": "true",
                "mailing_list_subscribed": false,
                "printed_mailing_list_subscribed": false
            },
            "entity_code": {
                "type": "custom",
                "code": "3021879"
            },
            "opt_in_programme": {
                "programme_opted_in": true,
                "join_date": "2016-01-30T14:37:22+00:00"
            },
            "registered": true,
            "loyalty_status": {
                "campaign_id": 2095,
                "name": "Level 1",
                "description": "Level 1 in the Programme",
                "loyalty_level_id": 2,
                "points_to_proceed_next_level": 500,
                "points_to_remain_current_level": 220,
                "maintenance_points_level": 200,
                "last_review_date": "2019-04-04T00:05:22+00:00",
                "next_review_date": "2020-04-04T00:05:22+00:00",
                "date_reached": "2019-06-06T08:06:14+00:00"
            }
        }
    }
  }
]

• Call name: login
• Endpoint URL: https://api0.spaaza.com/auth/login
• Request methods: POST
• Request Content-Type: multipart/form-data or application/x-www-form-urlencoded
• Response Content-Type: application/json
• Auth required: no

When supplied with a username and password, this API checks whether the password is valid for the username. If it is valid, it deletes any existing sessions, and then creates a session with a session key in the database. It then returns session information in JSON. Note that the session_expires_date is returned in UTC date time format.

HTTP Parameters

The following HTTP POST parameters can be passed to the API:

Permissions

This API call requires no specific permissions.

Headers

The following headers can/must be passed to the API call:

X-MyPrice-App-Hostname (mandatory in some cases) The hostname of the app which the signup is for. This header is mandatory when authenticating an end user (shopper or programme member). When authenticating an admin user (including a webshop or POS) this header must be excluded.

Logging in on behalf of a user

Returns an OK code and a JSON for the user. A sample is shown below:

{
    "result": {
        "code": 1,
        "status": "ok"
    },
    "results": {
        "user_info": {
            "id": 3636813,
            "user_id": 3636813,
            "first_name": "Jane",
            "last_name": "Smith",
            "birthday": "1980-01-01T00:00:00+00:00",
            "signup_channel": "mobile:ios",
            "username": "jane.smith@example.com",
            "authentication_point_identifier": null,
            "auxiliary_identifier": null,
            "mailing_list": {
                "mailing_list_sub_offered": false,
                "mailing_list_subscribed": true,
                "printed_mailing_list_subscribed": true
            },
            "entity_code": {
                "type": "regular",
                "code": "3636813"
            },
            "opt_in_programme": {
                "programme_opted_in": false,
                "join_date": "2020-05-18T09:32:57+00:00"
            },
            "obfuscated": false,
            "country_code": null,
            "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,
            "member_number": "3636813",
            "language": "en-GB",
            "opt_in_secondary": null,
            "registered": true,
            "is_employee": false,
            "push_notification_subscription": {
                "subscribed": false,
                "subscriptions": []
            },
            "loyalty_status": null,
            "frequency": 0,
            "recency": 0,
            "monetary": 0,
            "overall": 0,
            "stores": "",
            "online_shopper": false,
            "offline_shopper": false,
            "average_basket_value": "0.00",
            "days_since_last_purchase": null,
            "number_of_purchases": 0,
            "referring_user": null,
            "referral_code": "lxzwvs"
        },
        "session_info": {
            "session_key": "84f895eda81892bacf53ac2538d96d14fda32a50889f55e85fa461e241e31f65",
            "session_auth_method": "password",
            "session_key_validity": "15552000",
            "session_user_id": 3636813,
            "session_username": "jane.smith@example.com",
            "session_expires_date": "2021-04-28 11:14:40"
        },
        "result_type": "session"
    }
}

Overview

• Call name: session
• Endpoint URL: https://api0.spaaza.com/auth/session
• Request methods: POST
• Request Content-Type: multipart/form-data or application/x-www-form-urlencoded
• Response Content-Type: application/json
• Auth required: yes
• X-MyPrice-App-Hostname header required: yes

This API call allows you to login on behalf of a user. This API call only works with privileged authentication.

HTTP Parameters

At least one of the below HTTP parameters must be passed to the API:

Permissions and Authentication

This API call requires a valid Spaaza session. The session can be as follows:

Headers

The following headers can/must be passed to the API call:

Getting user session status

If the session is valid, returns an ok signal. An example is below:

{
  "result": {
      "code": 1,
      "status": "ok"
  },
  "results": {
      "id": 114521,
      "user_id": 114521,
      "first_name": "Sam",
      "last_name": "test56767",
      "gender": "M",
      "birthday": "1982-05-21T00:00:00+00:00",
      "username": "test56767@cowcam.com",
      "mailing_list": {
          "mailing_list_sub_offered": false,
          "mailing_list_subscribed": false,
          "printed_mailing_list_subscribed": false
      },
      "entity_code": {
          "type": "custom",
          "code": "3021879"
      }
      "result_type": "get-login-status"
  }
}

If the session’s auth_method was “facebook”, extended information will be returned with the Facebook access token and detail about the expiry:

{
  "result": {
      "code": 1,
      "status": "ok"
  },
  "results": {
      "user_id": 68076,
      "username": null,
      "user_facebook_id": "100005264048981",
      "user_facebook_access_token": "AAADPxlzKZBy8BACux13ZCpass309BuPZA9tFpcVvZCP0zdzBlbyqTXwPnl7YpIbMLgqfoktUcaD4ZAOO1VS128bSx2tvuxDEgKCwjHxR6PkZCOCZAGLD7x7",
      "user_facebook_access_token_expires": 3600,
      "user_facebook_access_token_expires_timestamp_utc": "2017-03-08 00:14:40",
      [...]
      "mailing_list": {
          "mailing_list_sub_offered": false,
          "mailing_list_subscribed": false,
          "printed_mailing_list_subscribed": false
      },
      "entity_code": {
          "type": "custom",
          "code": "3024075"
      }
      "result_type": "get-login-status"
  }
}

• Call name: get-login-status
• Endpoint URL: https://api0.spaaza.com/auth/get-login-status
• Request methods: GET
• Auth required: no

When supplied with a username and session key, this API checks whether there’s a valid session for the username which has a matching session key. If there is a valid session, it returns code 1 (okay). If there is no valid session, it returns with an error.

The response also returns various details about the user, including email address (if present), date of birth and mailing-list subscription info.

HTTP Parameters

The following HTTP POST parameters can be passed to the API:

Permissions

This API call requires no specific permissions.

Headers

The following headers can/must be passed to the API call:

X-MyPrice-App-Hostname (mandatory for programme member/non-admin sessions) The hostname of the app which the login session is associated with. This header is mandatory when authenticating an end user (shopper or programme member). When authenticating an admin user, webshop or POS this header can be excluded.

Logging users out

If the session is valid, returns an ok signal. Ae example is below:

[
{
  "result": {
      "code": 1,
      "status": "ok"
  },
  "results": {
      "result_type": "logout",
      "username": "sam.critchley@spaaza.com"
  }
}
]

• Call name: logout
• Endpoint URL: http://api0.spaaza.com/auth/logout
• Request methods: DELETE
• Response Content-Type: application/json
• Auth required: yes

Calling this API with a valid session (in HTTP headers) causes the session for that user to be destroyed, effectively logging the user out.

HTTP Parameters

No specific parameters required.

Permissions

This API call requires no specific permissions. Unless there’s been a security failure, only the user or the backend user is in possession of the session key, which means the session can only be validated if the validator is in possession of the key.

Deleting user accounts

Returns an OK code and echoes the obfuscated user details. A sample is shown below:

{
  "result": {
      "code": 1,
      "status": "ok"
  },
  "results": {
      "user_info": {
          "id": 3354896,
          "user_id": 3354896,
          "first_name": "Deleted",
          "last_name": "Deleted",
          "country_code": "IT",
          "username": "3354896@deleted.spaaza.com",
          "authentication_point_identifier": null,
          "auxiliary_identifier": null,
          "mailing_list": {
              "mailing_list_sub_offered": false,
              "mailing_list_subscribed": false,
              "printed_mailing_list_subscribed": false
          },
          "entity_code": {
              "type": "custom",
              "code": "133791"
          },
          "opt_in_programme": {
              "programme_opted_in": false,
              "join_date": null
          },
          "registered": false,
          "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
      },
      "result_type": "delete-user"
  }
}

Overview

• Call name: delete-user
• Endpoint URL: https://api0.spaaza.com/delete-user
• Request methods: DELETE
• Response Content-Type: application/json
• Auth required: yes

Delete a user for legal purposes. This API endpoint obfuscates all personally-idenfiable user details such as first name, last name, email address, gender, date of birth and address details.

Permissions and Authentication

This API call requires a valid Spaaza session. The session can be as follows:

Note that if admin authentication is used and the admin user does not have sufficient permissions to delete the user, an error will be generated.

HTTP Parameters

The following HTTP parameters can be passed to the API:

Headers

The following headers can/must be passed to the API call:

Permissions

This API call requires delete permissions when using admin authentication.

Searching Users

curl "-XPOST -v -k \
-H 'Session-User-Id:<your user ID>' \
-H 'Session-Key:<your session key>' \
-H 'Session-Chain-Id:<your chain ID>' \
-d 'chain_id=<your chain ID>’ \
-d 'query=smith’ \
-d 'page=1 \
-d 'count=25 \
-d 'opted_in=1 \

'https://services-[API_ENVIRONMENT].spaaza.com/search/users'"

Example response

[
	{
		"id": 12345678,
		"entity_code": {
			"code": "100002"
		},
		"username": "john.smith@spaaza.com",
		"firstname": "John",
		"lastname": "Smith",
		"created_date": "2017-10-19T12:46:34Z",
		"gender": "M",
		"birthday": "1982-06-30T00:00:00Z",
		"spaaza_opted_in": true,
		"country_code": "NL",
		"store_id": ""
	},
	{
		"id": 12345679,
		"entity_code": {
			"code": "100003"
		},
		"username": "jane.smith@example.com",
		"firstname": "Jane",
		"lastname": "Smith",
		"created_date": "2017-10-29T13:24:33Z",
		"gender": "M",
		"birthday": "1979-04-29T00:00:00Z",
		"spaaza_opted_in": true,
		"country_code": "UK",
		"store_id": "12"
	}
]

Overview

• Call name: search
• Endpoint URL: https://services-[API_ENVIRONMENT].spaaza.com/search/users
• Request methods: HTTP POST
• Auth required: yes

You can use this API endpoint to search for users in Spaaza.

The API_ENVIRONMENT value varies according to whether the request is being made to Spaaza’s production or staging API:

Headers

The following headers are required:

The following authentication methods are permitted:

Query Parameters (application/x-www-form-urlencoded)

This API accepts the following parameters:

Note objects

You can use the Spaaza API to manage any notes attached to a given user. This can be used to provide useful details about a user’s purchase habits, or any other generic notes that neeed to be saved for a user.

Fields in the Note object

The following fields are returned in the note object.

Identifying a note

Details for a note

Viewing user notes

User notes do not currently have their own API endpoint for fetching data. They can be fetched as part of the user get-card api call

Adding a note to a user

Example response

{
  "id": 123456,
  "text": "Customer very happy with her latest dress purchase.",
  "created_date": "2017-07-03T11:56:04Z",
  "user_id": 123123,
  "creating_user_id": 321321
}

Overview

• Call name: add-user-note
• Endpoint URL: https://api0.spaaza.com/internal/add-user-note
• Request methods: POST
• Request Content-Type: multipart/form-data or application/x-www-form-urlencoded
• Response Content-Type: application/json
• Auth required: yes
• X-MyPrice-App-Hostname header requirement: mandatory when using privileged authentication

Introduction

This API call adds a new note record to an existing user.

HTTP parameters

The following HTTP parameters can be passed to the API:

Deleting a user note

Example response

{
  "id": 123456,
  "deleted": true
}

Overview

• Call name: delete-user-note
• Endpoint URL: https://api0.spaaza.com/internal/delete-user-note
• Request methods: DELETE
• Request Content-Type: multipart/form-data or application/x-www-form-urlencoded
• Response Content-Type: application/json
• Auth required: yes
• X-MyPrice-App-Hostname header requirement: mandatory when using privileged authentication

Introduction

This API call deletes a user’s note record.

HTTP parameters

The following HTTP parameters can be passed to the API:

Cross site authentication token

Used to facilitate seamless logins with third party site integrations. This API can be used to verify and login a user, without a user having to manually log in to several systems. Please check with Spaaza on availability of this API endpoint for the system you are attempting to integrate with.

The result output is a JSON array with its results section being something to the lines of the following:

{
    "token": "7edc5f1e534cad2454ea150904f261468b90d073e8dde875b2c",
    "expiry": "2019-04-04T00:00:00+00:00"
}

• Call name: get-cross-site-token
• Endpoint URL: https://api0.spaaza.com/auth/get-cross-site-token
• Request methods: POST
• Response Content-Type: application/json
• Auth required: yes

Get a token to do cross site authentication with the given app (see “Headers” section below).

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.

HTTP Parameters

This API endpoint has no required parameters - all necessary information is supplied in the session and app hostname headers.

Headers

The following headers can/must be passed to the API call in addition to any authentication headers:

Permissions

This API call requires no specific permissions.

Possible error responses

The following represents a list of possible error responses for the get-card endpoint:

Card, points and vouchers

Getting the “card” of a user

The result output is a JSON array with its results section being something to the lines of the following:

[ 
   { 
      "entity":{ 
         "id":1752,
         "name":"Big Chain Inc.",
         "type":"chain"
      },
      "entity_images":[ 

      ],
      "card_colour":{ 
         "id":1,
         "card_background":"#000000",
         "card_text":"#FFFFFF"
      },
      "user_entity_card":{ 
         "type":"custom",
         "id":33000114
      },
      "user_info":{ 
         "authentication_point_identifier":"SQ0057824",
         "auxiliary_identifier":"ge0axuf62",
         "birthday":"1983-09-09T00:00:00+00:00",
         "entity_code":{ 
            "code":"33000114",
            "type":"custom"
         },
         "first_name":"Jiminy",
         "gender":"M",
         "id":305281,
         "last_name":"Cricket",
         "country_code":"NL",
         "address_streetname":"Herengracht",
         "address_housenumber":"504",
         "address_housenumber_extension":"II",
         "address_line_2":"Grachtengordel",
         "address_line_3":"Centrum",
         "address_towncity":"Amsterdam",
         "address_regionstate":"Noord-Holland",
         "address_postalcode":"1017 CB",
         "phone_number":"+31-220445641",
         "language":"nl-NL",
         "opt_in_secondary":true,
         "mailing_list":{ 
            "mailing_list_sub_offered":true,
            "mailing_list_subscribed":false,
            "printed_mailing_list_subscribed":false
         },
         "opt_in_programme":{ 
            "programme_opted_in":"true",
            "join_date":"2019-06-06T08:06:14+00:00"
         },
         "registered":true,
         "is_employee": false,
         "user_id":3052761,
         "username":"jiminy@mail.com",
         "referring_user":{ 
            "id":3593732,
            "referral_code":"56uepf"
         },
         "referral_code":"uyamct"
      },
      "vouchers":[ 
         { 
            "voucher_key":"07d9acafd261dff2c013c6b09e3867d7fc55df5a39953c17c4c0f5380d4b71c2",
            "voucher_id":45657779,
            "voucher_status":"generated",
            "voucher_expiry_datetime_utc":"2014-01-13 18:04:01",
            "voucher_expiry_seconds_remaining":5626,
            "product_name":"QU HEADCOUNT",
            "product_price":299.95,
            "product_currency_id":1,
            "product_voucher_price":296.95,
            "product_original_price":299.95,
            "campaign_id":4,
            "campaign_title":"Test",
            "voucher_text":"Thanks for being a great customer",
            "voucher_notes":null,
            "voucher_title":null,
            "voucher_description":null,
            "voucher_image_url":null
         }
      ],
      "meta_vouchers":[ 

      ],
      "basket_vouchers":[ 
         { 
            "voucher_key":"da64e01d486a7cca40de5700240bbe9c01f18cbfc3a72096da979d8bc427b05d",
            "voucher_id":32455345,
            "voucher_created_datetime":"2019-09-02T15:18:52+00:00",
            "voucher_status":"generated",
            "campaign_id":66,
            "campaign_title":"Big Chain Invite-a-Friend",
            "campaign_type":"affiliate",
            "campaign_image_filename":null,
            "campaign_image_url":null,
            "campaign_image_link":null,
            "campaign_image_dimension_x":null,
            "campaign_image_dimension_y":null,
            "campaign_title_localised":"Vriend uitnodigen NL",
            "campaign_voucher_text_localised":"Big Chain bon NL",
            "redeeming_basket":null,
            "voucher_expiry_datetime_utc":"2024-12-27 10:20:50",
            "voucher_expiry_seconds_remaining":4319835,
            "creating_user":{ 
               "user_id":21,
               "full_name":"John Doe"
            },
            "voucher_currency_id":1,
            "voucher_currency_symbol":"R",
            "voucher_amount_original":50.00,
            "voucher_amount_redeemed":"",
            "voucher_amount":50.00,
            "voucher_text":"You got a voucher from your friend.",
            "voucher_notes":null,
            "voucher_title":"€50 Friends Voucher",
            "voucher_description":null,
            "voucher_image_url":"https://www.example.com/image.jpg",
            "voucher_honour_code":"honour004",
            "voucher_discount_ratio": 0,
            "voucher_type": "basket"
         },
         { 
            "voucher_key":"19361bbf9bf4a02b3d4fa413628768bb2096239cb9effa4fa60980b606bb33dc",
            "voucher_id":3964201,
            "voucher_created_datetime":"2020-03-02T16:43:52+00:00",
            "voucher_status":"claimed",
            "campaign_id":66,
            "campaign_title":"Big Chain Loyalty Campaign",
            "campaign_type":"loyalty",
            "campaign_image_filename":null,
            "campaign_image_url":null,
            "campaign_image_link":null,
            "campaign_image_dimension_x":null,
            "campaign_image_dimension_y":null,
            "campaign_title_localised": "Big winkelketen",
            "campaign_voucher_text_localised":"Big Chain voucher NL",
            "redeeming_basket":null,
            "voucher_expiry_datetime_utc":"2024-12-31 10:20:50",
            "voucher_expiry_seconds_remaining":4319835,
            "creating_user":{ 
               "user_id":21,
               "full_name":"John Doe"
            },
            "voucher_currency_id":1,
            "voucher_currency_symbol":"R",
            "voucher_amount_original": null,
            "voucher_amount_redeemed":"",
            "voucher_amount": null,
            "voucher_text":"You got a voucher from your friend.",
            "voucher_notes":null,
            "voucher_title":"€50 Friends Voucher",
            "voucher_description":null,
            "voucher_image_url":"https://www.example.com/image.jpg",
            "voucher_honour_code": null,
            "voucher_discount_ratio": 0.25,
            "voucher_type": "basket_pct"
         }
      ],
      "honour_vouchers":[ 
         { 
            "voucher_key":"138406421b611051c953a620c5f958348bbb045fdf4a7e92c8e9f53ccd04144e",
            "voucher_id":94697,
            "voucher_status":"claimed",
            "voucher_locked":false,
            "campaign_id":140,
            "campaign_type":"loyalty",
            "campaign_title":"ACME Loyalty Campaign",
            "voucher_expiry_datetime_utc":"2018-07-30 00:00:00",
            "voucher_expiry_seconds_remaining":5201979,
            "creating_user":{ 
               "user_id":21,
               "full_name":"John Doe"
            },
            "voucher_currency_id":2,
            "voucher_currency_symbol":"€",
            "voucher_amount_original":0,
            "voucher_amount_redeemed":0,
            "voucher_amount":5,
            "voucher_text":"Thanks for being a great customer",
            "voucher_notes":"The notes for a voucher such as instructions for use, go here",
            "voucher_title":"€5 Loyalty Campaign Voucher",
            "voucher_description":"If you redeem this voucher online or in store you will get a free item.",
            "voucher_type":"honour",
            "voucher_honour_code":"HON00421"
         }
      ],
      "promotions":{ 
         "progress":[ 
            { 
               "type":"simple",
               "title":"Big Chain Hit The Target Campaign",
               "description":"Spend R200 and earn R25",
               "actions":[ 

               ],
               "progress":{ 
                  "target":200,
                  "achieved":0,
                  "percentage":0
               },
               "supports_contribution":true,
               "is_contributor":true,
               "currency":"ZAR",
               "currency_symbol":"R",
               "campaign_id":90,
               "reward_money":25,
               "image_filename":null,
               "image_url":null,
               "image_link":null,
               "image_dimension_x":null,
               "image_dimension_y":null,
               "field_localisations":"{\"title\":{\"en\":{\"default\":\"Big Chain Hit The Target Campaign\",\"en-UK\":\"Big Chain Hit The Target Campaign UK\",\"en-US\":\"Big Chain Hit The Target Campaign US\"},\"nl\":{\"default\":\"Big Chain Bereiken Campagne\",\"nl-NL\":\"Big Chain Bereiken Campagne NL\",\"nl-BE\":\"Big Chain Bereiken Campagne BE\"}}",
               "title_localised":"Big Chain Bereiken Campagne NL"
            },
            { 
               "type":"cashback",
               "title":"Big Chain Rewards Programme",
               "description":"Earn 5% rewards points every time you spend at Big Chain",
               "actions":[ 

               ],
               "earn_percentage":5,
               "is_contributor":false,
               "saved_amount":10.00,
               "saved_amount_currency":"ZAR",
               "saved_amount_currency_symbol":"R",
               "supports_contribution":true,
               "total_amount":10.00,
               "campaign_id":60,
               "unlocked_amount":0,
               "image_filename":null,
               "image_url":null,
               "image_link":null,
               "image_dimension_x":null,
               "image_dimension_y":null,
               "field_localisations":"{\"title\":{\"en\":{\"default\":\"Big Chain Rewards Campaign\",\"en-UK\":\"Big Chain Rewards Campaign UK\",\"en-US\":\"Big Chain Rewards Campaign US\"},\"nl\":{\"default\":\"Big Chain Rewards Campagne\",\"nl-NL\":\"Big Chain Rewards Campagne NL\",\"nl-BE\":\"Big Chain Rewards Campagne BE\"}}",
               "title_localised":"Big Chain Rewards Campagne NL"
            }
         ],
         "basket":[ 

         ],
         "product":[ 

         ],
         "referral":[ 
            { 
               "type":"referral",
               "campaign_id":451,
               "title":"Invite Friends!",
               "description":"Invite friends and you will both earn rewards.",
               "currency":"EUR",
               "currency_symbol":"€",
               "supports_contribution":false,
               "is_contributor":false,
               "image_url":"https://s3.eu-west-1.amazonaws.com/campaign-images-test01.spaaza.com/451/4.png",
               "actions":[ 

               ],
               "code":"uyamct"
            }
         ],
         "signup":[ 
            { 
               "type":"signup",
               "title":"Big Chain Signup Bonus",
               "description":"Receive a R100 voucher to spend when you join.",
               "actions":[ 

               ],
               "signup_amount":100.00,
               "title_localised":"Big Chain Inschrijfbonus",
               "voucher_text_localised":"Uw R11 bonusvoucher"
            }
         ],
         "loyalty":[ 
            { 
               "id":198,
               "chain_id":1752,
               "title":"Big Chain Loyalty",
               "description":"The best loyalty programme",
               "active":true,
               "created_date":"2017-08-02T15:18:52+00:00",
               "last_modified_date":"2017-08-02T15:18:52+00:00",
               "currency_id":2,
               "voucher_text":"Your Big Chain loyalty voucher",
               "myprice_app_id":21,
               "loyalty_rules":[ 
                  { 
                     "id":5,
                     "campaign_id":198,
                     "title":"Points tracker rule for creating basket voucher",
                     "action":"createBasketVoucher",
                     "direction":"up",
                     "points_threshold":100.00,
                     "action_amount":5.00,
                     "action_is_repeatable":true,
                     "action_expiry_unit":"month",
                     "action_expiry_quantity":2,
                     "operand_campaign_id":140,
                     "type":"points_tracker"
                  },
                  { 
                     "id":7,
                     "campaign_id":198,
                     "title":"Set level rule for joining programme",
                     "level":"bronze",
                     "loyalty_level_id":1,
                     "action":"setLevel",
                     "action_is_repeatable":false,
                     "type":"initial",
                     "loyalty_level_name":"bronze"
                  },
                  { 
                     "id":8,
                     "campaign_id":198,
                     "title":"Rule for levelling up to silver in the programme",
                     "level":"silver",
                     "loyalty_level_id":2,
                     "action":"setLevel",
                     "direction":"up",
                     "points_threshold":250,
                     "action_is_repeatable":false,
                     "type":"points_tracker",
                     "loyalty_level_name":"silver"
                  },
                  { 
                     "id":26,
                     "campaign_id":392,
                     "title":"ACME Wallet Review",
                     "description":"Subtract points threshold current level if balance above",
                     "action":"addPointsToWallet",
                     "direction":"down",
                     "action_is_repeatable":false,
                     "operand_campaign_id":140,
                     "type":"review"
                  }
               ],
               "loyalty_levels":[ 
                  { 
                     "id":1,
                     "campaign_id":159,
                     "name":"bronze",
                     "description":"Initial level in programme"
                  },
                  { 
                     "id":2,
                     "campaign_id":159,
                     "name":"silver",
                     "description":"Second level in programme"
                  }
               ],
               "is_active":true,
               "type":"loyalty",
               "created_voucher_claimed_by_default":false,
               "supports_user_segments":false,
               "user_segment_id":null,
               "field_localisations":"{\"title\":{\"en\":{\"default\":\"Big Chain Loyalty Campaign\",\"en-UK\":\"Big Chain Loyalty Campaign UK\",\"en-US\":\"Big Chain Loyalty Campaign US\"},\"nl\":{\"default\":\"Big Chain Loyaliteitscampagne\",\"nl-NL\":\"Big Chain Loyaliteitscampagne NL\",\"nl-BE\":\"Big Chain Loyaliteitscampagne BE\"}}",
               "title_localised":"Big Chain Loyaliteitscampagne NL",
               "voucher_text_localised":"Uw Big Chain loyaltiteitsvoucher"
            }
         ]
      },
      "points":{ 
         "id":140,
         "chain_id":1752,
         "title":"Big Chain Points Wallet",
         "description":"Points wallet the ultimate",
         "active":true,
         "operator_type":"or",
         "created_date":"2017-08-02T14:32:22+00:00",
         "last_modified_date":"2017-08-02T14:32:22+00:00",
         "currency_id":5,
         "max_manual_daily_amount":200.00,
         "spend_on_promotional_items":true,
         "balance_can_subzero":true,
         "is_active":true,
         "type":"points_wallet",
         "parameters":[ 

         ],
         "rounding_strategy":"round_down",
         "rounding_precision":2,
         "secondary_display_currency":"PTN",
         "secondary_display_currency_symbol":"PTN",
         "secondary_display_multiplication_factor":40,
         "secondary_display_rounding_precision":0,
         "created_voucher_claimed_by_default":false,
         "is_redeemable":false,
         "saved_amount":442,
         "total_amount":442,
         "currency":"PTS",
         "currency_symbol":"pts",
         "field_localisations":"{\"title\":{\"en\":{\"default\":\"Big Chain Points Wallet\",\"en-UK\":\"Big Chain Points Wallet UK\",\"en-US\":\"Big Chain Points Wallet US\"},\"nl\":{\"default\":\"Big Chain Puntenwallet\",\"nl-NL\":\"Big Chain Puntenwallet NL\",\"nl-BE\":\"Big Chain Puntenwallet BE\"}}",
         "title_localised":"Big Chain Puntenwallet NL"
      },
      "wallet":{ 
         "id":81,
         "chain_id":1752,
         "title":"Big Chain Money Wallet",
         "description":"This is where your Big Chain rewards end up.",
         "notes":"",
         "active":true,
         "created_date":"2017-05-18T13:31:38+00:00",
         "last_modified_date":"2017-05-20T13:06:28+00:00",
         "voucher_text":"",
         "voucher_expiry_days":0,
         "balance_can_subzero":true,
         "spend_on_promotional_items":false,
         "max_manual_daily_amount":200.00,
         "is_active":true,
         "type":"wallet",
         "parameters":[ 

         ],
         "rounding_strategy":"neutral",
         "rounding_precision":2,
         "secondary_display_currency":"PTN",
         "secondary_display_currency_symbol":"PTN",
         "secondary_display_multiplication_factor":40,
         "secondary_display_rounding_precision":0,
         "created_voucher_claimed_by_default":true,
         "saved_amount":0,
         "total_amount":0,
         "currency":"ZAR",
         "currency_symbol":"R",
         "field_localisations":"{\"title\":{\"en\":{\"default\":\"Big Chain Money Wallet\",\"en-UK\":\"Big Chain Money Wallet UK\",\"en-US\":\"Big Chain Money Wallet US\"},\"nl\":{\"default\":\"Big Chain Monetairewallet\",\"nl-NL\":\"Big Chain Monetairewallet NL\",\"nl-BE\":\"Big Chain Monetairewallet BE\"}}",
         "title_localised":"Big Chain Monetairewallet NL",
         "voucher_text_localised":""
      },
      "loyalty_status":{ 
         "campaign_id":198,
         "name":"silver",
         "description":"Second level in programme",
         "loyalty_level_id":2,
         "points_balance_current":220,
         "points_to_proceed_next_level":30,
         "points_to_remain_current_level":0,
         "last_review_date":"2019-04-04T00:05:22+00:00",
         "next_review_date":"2020-04-04T00:05:22+00:00",
         "date_reached":"2018-04-21T10:00:10+00:00"
      },
      "frequency":3,
      "recency":5,
      "monetary":2,
      "overall":532,
      "stores":null,
      "online_shopper":true,
      "offline_shopper":false,
      "average_basket_value":"119.30",
      "days_since_last_purchase":6,
      "number_of_purchases":4,
      "referring_user":{ 
         "id":4
      },
      "notes":[ 
         { 
            "id":123456,
            "text":"Customer was very happy with the new jeans",
            "created_date":"2018-05-20T13:06:28+00:00",
            "user":{ 
               "user_id":65665
            },
            "creating_user":{ 
               "user_id":55776,
               "first_name":"John",
               "last_name":"Doe",
               "username":"john@email.com"
            }
         }
      ],
      "result_type":"get-user-entity-card"
   }
]