Link Search Menu Expand Document

Altering a 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 or application/json*
  • Response Content-Type: application/json
  • Auth required: yes
  • X-Spaaza-MyPrice-App-Hostname header requirement: mandatory when using privileged authentication

* In the case of a JSON payload (application/json) all parameters are top-level elements.

Introduction

This API call modifies information about an existing user.

Version-specific information

The following version-specific changes apply to this endpoint. See the versioning page for more details.

Version Change details
>= 1.4.10 Update gender parameter to support male, female, nonbinary, transgender, agender, genderqueer, genderfluid, bigender, twospirit, androgynous, pangender, neutrois, demigender and other.

Permissions and Authentication

  • User authentication: a session generated by an end-user login.
  • Admin authentication: the performing user needs to be logged in and have write access to the chain with which the user account is associated.
  • Privileged authentication: the use of privileged authentication is permitted for this endpoint.

HTTP Parameters

In this section the parameters which can be passed to the API are divided into “User identification parameters,” i.e. those required in order to identify the user account to be altered, and “Other parameters,” i.e. general parameters which can be altered.

User identification parameters

When using user authentication the user account to be altered is already identified by the login session. However, when using admin or privileged authentication, one of five identification parameters must be passed in order to identify which user account is to be altered:

  • user_id
  • authentication_point_identifier
  • member_number
  • username
  • referral_code

Critically, whilst the user_id parameter is immutable, it is possible to alter the other three user identification parameters if they are passed and are not being used to identify the user account.

For example, if the user_id and username parameters are passed in a call, and the user_id parameter is used to identify the user account, the username (email address) associated with the account will be altered if the username parameter is different than the account’s current username.

Note also that if parameters are in use by two or more different existing user accounts, an error will be returned. For example, if both user_id and username parameters are passed in a call, the user_id already belongs to one existing account, and the username to another existing account, it is not possible to ascertain which account is to be altered, so an error will be returned.

The four user identification parameters are shown below:

Parameter Description
user_id (integer, mandatory when not using username, member_number or authentication_point_identifier to identify the user) The ID of the user whose details are to be altered. This parameter can be used to identify the user.
authentication_point_identifier (string, mandatory when not using user_id, username or member_number to identify the user) The id of the user in a third-party identity system such as a webstore. Highly recommended in the case that e.g. an update to the member’s email address will be made by the source of identity if that source is not Spaaza - in this case the authentication_point_identifier can be used as a unique identifier for the customer.
member_number (string, mandatory when not using user_id, username or authentication_point_identifier to identify the user) The unique membership number or code for the shopper within the membership or loyalty programme. In most cases this is numeric, but string values are allowed
username (string, mandatory when not using member_number, user_id or authentication_point_identifier to identify the user) The username of the user in email address format. This parameter can be used to identify the user.
referral_code (string, mandatory when not using username, member_number, user_id or authentication_point_identifier to identify the user). The referral_code of the user, this paramters can be used to identify the user.

Additionally, the following parameter is also required in the case of admin authentication in order to identify which Spaaza chain the user account is tied to:

Parameter Description
chain_id (integer, mandatory when using admin authentication) The id of the chain (retailer) to which the user is connected.

Other parameters

This section lists the other parameters which are properties of a user account, and which can be altered, but are not used to identify the account.

Parameter Description
address_housenumber (string, optional) The street number or house name of the user’s postal address.
address_housenumber_extension (string, optional) The extension of the street number of the user’s postal address, for example “Apartment 21”
address_line_2 (string, optional) The second line of the user’s postal address, which can be used to denote e.g. a neighbourhood or village.
address_line_3 (string, optional) The third line of the user’s postal address, which can be used to denote e.g. a village or borough
address_postalcode (string, optional) The user’s postal or zipcode.
address_regionstate (string, optional) The region or state of the user’s postal address.
address_streetname (string, optional) The street name of the user’s postal address.
address_towncity (string, optional) The user’s postal city.
auxiliary_identifier (string, optional) An auxiliary identifier string used by the retailer or other organisation. This value is returned in displays and is searchable in Spaaza analytics, but is not generally used as a primary identifier in API endpoints.
birthday (string, mandatory or optional depending on the setup of the member programme) The birth date of the user. ISO 8601 (YYYY-MM-DD) or ISO 8601 extended (e.g. 1983-07-27T00:00:00+00:00 or 1983-07-27T00:00:00Z) are the default allowed formats. Dates in other formats (“D/M/YYYY”, “DD/MM/YYYY”, “D-M-YYYY” and “DD-MM-YYYY” can be used instead - see the birthday_field_format parameter). If the birthday parameter is supplied in ISO 8601 extended format any timezone offset will be converted to UTC.
birthday_field_format (string, mandatory if supplying birthday parameter in a format other than ISO 8601 or ISO 8601 extended) The format of the birthday parameter supplied if not in ISO 8601 or ISO 8601 extended format. Allowed values are “DD-MM-YYYY”, “D-M-YYYY”, “DD/MM/YYYY” and “D/M/YYYY”. Any other value implies ISO 8601/ISO 8601 extended format.
branch_business_owner_code (string, optional) A retailer-specific branch code used by the retailer to identify the individual branch in a chain in which the new account is being created, if it is being created in a branch. If the store_id value is also supplied, then store_id takes precedence. In order to use the branch_business_owner_code field there must be a record of the branch code in the Spaaza database.
country_code (string, optional) The ISO ALPHA-2 country code of the user.
first_name (string, optional) The first name of the user.
gender (string, optional) The gender of the user. Allowed values are male, female, nonbinary, transgender, agender, genderqueer, genderfluid, bigender, twospirit, androgynous, pangender, neutrois, demigender and other.
home_store_id (integer, optional) Home store id in the Spaaza system for which the new account was created
language (string, optional) The preferred IETF BCP 47 language code (eg. en-GB, nl, nl-BE, etc.) for a user. The language code should consist of an ISO 639 language tag (e.g. nl) followed by optional subtags (e.g. BE), using hyphens as separators, for example nl-BE.
last_name (string, mandatory unless the user is being added on the basis of their Facebook account details) The last name of the user.
mailing_list_sub_offered (boolean, optional) Whether a subscription to the mailing list was offered to the user. If this parameter is not supplied a default value of false is applied.
mailing_list_subscribed (boolean, optional) Whether the user is subscribed to the mailing list. If this parameter is not supplied a default value of false is applied.
opt_in_secondary (boolean, optional) Generic opt in field to be used by the retailers, for recording opt ins that the standard fields don’t allow.
password (string, optional) The password of the user. In some systems it is not possible to update the customer password in remote authentication systems via the Spaaza API.
phone_number (string, optional) The contact number for a user.
printed_mailing_list_subscribed (boolean) Whether the user is subscribed to the mailing list for printed mail such as catalogues.
programme_opted_in (boolean) The programme subscription status of the user. Note that if this chain requires a user to be opted into a programme, the programme will only work for the user if this is set to true.
registered (boolean, optional) Whether the user is registered. The definition of the term ‘registered’ is flexible. The default value if this parameter is not supplied is true.
is_employee (boolean, optional) Whether the user is an employee of a chain. The defualt value if this paramter is not supplied is false.
store_id (integer, optional) Spaaza ID of the branch in which the new account was created (the “signup store”), assuming it was created in a branch. NOTE that this parameter should only be used if you know the Spaaza ID of the branch - in most cases the branch_business_owner_code parameter is used. NOTE this parameter takes precedence over the branch_business_owner_code parameter (even if sent as blank) - see above.

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.

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": {
            "address_housenumber": "46",
            "address_housenumber_extension": "B",
            "address_latitude": null,
            "address_line_2": "Apartment #416",
            "address_line_3": null,
            "address_longitude": null,
            "address_postalcode": "1015CB",
            "address_regionstate": "Any State",
            "address_streetname": "Any Street",
            "address_towncity": "Amsterdam",
            "authentication_point": null,
            "authentication_point_identifier": "99911166488945",
            "auxiliary_identifier": null,
            "average_basket_value": "0.00",
            "birthday": "1981-07-21",
            "business_group": null,
            "country_code": "NL",
            "created_date": "2024-01-31 15:15:43",
            "days_since_last_purchase": null,
            "entity_code": {
                "code": "3935159",
                "type": "regular"
            },
            "favorite_store": null,
            "first_name": "Josephine",
            "frequency": 1,
            "gender": "M",
            "id": 3935159,
            "is_employee": false,
            "is_influencer": false,
            "language": null,
            "last_modified_date": "2024-01-31 15:15:44",
            "last_name": "Bloggs",
            "loyalty_status": {
                "date_reached": null,
                "last_review_date": "2024-01-31T15:15:43+00:00",
                "loyalty_level_id": null,
                "monetary_balance_current": 0,
                "next_review_date": null,
                "points_balance_current": 5,
                "points_to_proceed_next_level": null,
                "points_to_remain_current_level": null
            },
            "mailing_list": {
                "mailing_list_sub_offered": false,
                "mailing_list_subscribed": true,
                "printed_mailing_list_subscribed": true
            },
            "member_number": "3935159",
            "monetary": 2,
            "number_of_purchases": 0,
            "obfuscated": false,
            "offline_shopper": false,
            "online_shopper": false,
            "opt_in_programme": {
                "join_date": "2024-01-31T15:15:43+00:00",
                "programme_opted_in": true
            },
            "opt_in_secondary": false,
            "overall": 3,
            "phone_number": "+31655222555",
            "points_wallet_total": 5,
            "push_notification_subscription": {
                "subscribed": false,
                "subscriptions": []
            },
            "recency": 5,
            "referral_channel": null,
            "referral_code": "gzo85d",
            "referred": true,
            "referring_user": {
                "authentication_point_identifier": null,
                "campaign_id": 2539,
                "id": 3930871,
                "referral_channel": null,
                "referral_code": "4t38p9"
            },
            "registered": true,
            "signup_channel": null,
            "signup_store": {
                "signup_store_id": 1383,
                "signup_store_name": "MOCO Museum store"
            },
            "stores": "",
            "total_cashback_balance": 0,
            "user_id": 3935159,
            "user_type": "registered",
            "username": "somedude0.11073246009398896@spaaza.com"
        },
        "result_type": "alter-user"
    }
}