API Reference

Merge Guest and Logged in Sessions

sync a guest regid with an email address.

Suggest Edits

Introduction

The Lists REST API accommodates both authenticated and guest sessions. When a user logs into the platform, there is a need to consolidate these sessions into a single account. This is because the authenticated user is no longer considered a guest, and all their wishlist activities must be carried forward. To address this situation, this API has been implemented that merges the two sessions, enabling a seamless user experience.

guest-validate-sync

The guest-validate-sync API merges two sessions together using the provided information. An email address and a guest regid are linked at the endpoint /guest-validate-sync.

This process necessitates the user's prior regid, which is generated from a UUID. It allows for the merging of sessions and the transfer of wishlist data to a new regid when a user logs in again.

📘

This API changes the regid and returns a new regid which can be used for logged in sessions.

Endpoint

Endpointrequest typeAPI Type
/storeadmin/v3/user/guest-validate-syncPOSTStore Admin

Returns

A new regid is created that combines all the session data from the old regid associating it with the provided useremail.

Request headers

Parameter / fieldDescriptioncontent-typerequired
regidunique token assigned to the guest user generated from a uuid.application/x-www-form-urlencodedYes
useremailemail address of the user.application/x-www-form-urlencodedYes
useragenttypea string to identify user agent that is requesting the regid generationapplication/x-www-form-urlencodedYes

Use Cases

When implementing the Store Admin API, there are two key instances where the authentication process should be executed:

  1. When a user logs into your storefront for the first time.
  2. When you need to merge a non-authenticated session (UUID-based) with an email-based session.
  3. When you want to obtain a logged-in user's regid, and synchronize it with the guest regid.

Example Curl

curl --location --request POST '{{Swym API Endpoint}}/storeadmin/v3/user/guest-validate-sync' \
--header 'Authorization: Basic {{BASE64-ENCODING-OF-"pid:apikey"}}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'useragenttype=mobileApp' \
--data-urlencode 'regid={{regid}}' \
--data-urlencode 'useremail={{useremail}}'

var axios = require('axios');
var qs = require('qs');
var data = qs.stringify({
  'useragenttype': 'mobileApp',
  'regid': '{{regid}}',
  'useremail': '[email protected]' 
});
var config = {
  method: 'post',
  url: '{{Swym API Endpoint}}/storeadmin/v3/user/guest-validate-sync',
  headers: { 
    'Authorization': 'Basic {{BASE64-ENCODING-OF-"pid:apikey"}}',
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  data : data
};

axios(config)
.then(function (response) {
  console.log(JSON.stringify(response.data));
})
.catch(function (error) {
  console.log(error);
});

Success Response

{
    "message": "Sync successful. We updated the provided regid with the email address!",
    "regid": "{{new regid}}",
    "email": "[email protected]"
}

Error Responses

{
    "message": "Sync failed. We found that the provided regid has an associated email address.",
    "regid": "Mpnqyw_kLlc8MBTwyOf20-dZcZHyLFe81Xs_p7culX8xHBFGTjiI7MX1vKG5i0g9ehe-zLf03p8NPd26IhF-8xg3uQrt2KySVnZgXcugweTMfIMezRf_K12h9LiUHiwOUbKtXay7j7FCWlqrRa2YVce4n0l3sTLP5_tpUeTh4_kTM3-RRM0luJhZVlR_kpO94UPAp2O49ellgkV-HmEkAAK7SQ0X4VUNyCCwnfEAz3M",
    "email": "[email protected]"
}

{
    "schema": "{#schema.core.OptionalKey{:k :useragenttype} java.lang.String, :regid java.lang.String, :useremail (pred Email)}",
    "errors": {
        "regid": "missing-required-key"
    },
    "type": "compojure.api.exception/request-validation",
    "coercion": "schema",
    "value": {
        "useragenttype": "mobileApp",
        "useremail": "[email protected]"
    },
    "in": [
        "request",
        "form-params"
    ]
}

🚧

The synchronization will fail if the old regid is already associated with an existing user email.

Sample flow Diagram

Error Status Codes:

If the request is unsuccessful, the API will return a JSON response with an error message and an HTTP status code indicating the type of error that occurred.

Status CodeTypeDescription
400Bad RequestYour request is invalid, change your request params and query and try again.
401UnauthorisedYou are performing an action on a resource that is not granted to the current logged-in user. Additionally, for REST APIs, this could mean your API key is wrong.
403ForbiddenYou are not allowed to request this data.
404Not FoundThe specified requested data could not be found.
429Too Many RequestsYou're raising too many requests! Slow down!
500Internal Server ErrorWe had a problem with our server. Try again later.
503Service UnavailableWe're temporarily offline for maintenance. Please try again later.

Updated over 1 year ago