Session Context Service

Download OpenAPI specification:Download

E-mail: documentation@emporix.com

Manage the customers' browser session context.

Key Features:

  • Stores properties matched with provided session ID, such as target location, preferred currency, or preferred site.
  • Allows to retrieve and manage current session properties.
  • Allows to manage custom attributes for particular sessions.

Key Benefits:

  • Contextual pricing based on a user's session.

Session management

Retrieving a session context

Retrieves a specified session context. Recommended for performing calls on the management side.

Required scopes

  • session_context.context_manage
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: The tenant name should always be provided in lowercase.

sessionId
required
string

Customer's session ID.

Responses
200

The request was successful. Session context details are returned.

404

A session context with the provided ID was not found.

500

A server-side error occurred.

get/{tenant}/context/{sessionId}
Request samples 
Response samples 
application/json
{
  • "sessionId": "62528895-b561-4518-bfdc-2cbf52a07845",
  • "customerId": "C87362407845",
  • "siteCode": "main",
  • "currency": "EUR",
  • "targetLocation": "DE",
  • "cartId": "61079711ce0eb90861357045",
  • "context": {
    },
  • "metadata": {
    }
}
Updating a session context
Updates a specified session context.
Recommended for performing calls on the management side.


Note: To update a session context, you need to provide its current metadata.version value in the request body.




Required scopes


    

  • session_context.context_manage
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
Your Emporix tenant's name.


Note: The tenant name should always be provided in lowercase.


 
sessionId
required
string
Customer's session ID.


 
query Parameters
upsert
string
    

  • If set to true and the session with the specified id does not exist, the session will be created.
    • 

  • If set to false or not specified, a standard update will be performed.
    • 



 
header Parameters
saas-token
string
Customer access token. 


Note: This header is only required if the session context belongs to a logged-in customer. In that case, the value of the token and the customerId in the request body must belong to the same customer.


 
Request Body schema: application/json
sessionId
string
Unique identifier of the customer's session.


 
customerId
string
Customer's unique identifier.


Note: This field is only applicable to logged-in customers.


 
siteCode
string
Code of the site, as defined in the Site Settings Service.


Note: The default country code for anonymous sessions is based on the home base address country of the default site. In the case of a logged-in customer session, the country code is derived from the customer's shipping address, with the billing address being used as a fallback if the former is not available. If both addresses are not set, the home base address country code from the default site is used.


 
currency
string
Three-letter currency code, as defined in the Currency Service.


Note: During an anonymous session, the default currency of the site serves as the initial currency. Whereas, for a user session, the customer's preferred currency is set as the initial currency.


 
cartId
string
Unique identifier of the active customer cart, generated when the cart is created through the Cart Service.


 
targetLocation
string
The country code, as defined in the country service.


Note: The default country code for anonymous sessions is based on the home base address country of the default site. In the case of a logged-in customer session, the country code is derived from the customer's shipping address, with the billing address being used as a fallback if the former is not available. If both addresses are not set, the home base address country code from the default site is used.


 
required
object (Metadata) 
 
Responses 
204
The request was successful. The session context has been updated.


404
A session context with the provided ID was not found.


500
A server-side error occurred.


put/{tenant}/context/{sessionId}
Request samples 
application/json
{
  • "sessionId": "62528895-b561-4518-bfdc-2cbf52a07845",
  • "customerId": "C87362407845",
  • "siteCode": "main",
  • "currency": "EUR",
  • "cartId": "512950192-b561-4518-bfdc-2cbf52a07845",
  • "targetLocation": "DE",
  • "metadata": {
    }
}
Response samples 
application/json
{
  • "sessionId": "62528895-b561-4518-bfdc-2cbf52a07845",
  • "code": 404,
  • "message": "Session not found"
}
Session context modification
Deleting an attribute from a session context
Removes a particular attribute from a specified session context.
Recommended for performing calls on the management side. 


Note: Optimistic locking is not taken into account here.




Required scopes


    

  • session_context.context_manage
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
Your Emporix tenant's name.


Note: The tenant name should always be provided in lowercase.


 
sessionId
required
string
Customer's session ID.


 
attributeName
required
string
Name of the attribute that should be deleted from the session context.


 
Responses 
204
The request was successful. The attribute has been deleted from the session context.


404
A session context with the provided ID was not found.


500
A server-side error occurred.


delete/{tenant}/context/{sessionId}/attributes/{attributeName}
Request samples 
Response samples 
application/json
{
  • "sessionId": "62528895-b561-4518-bfdc-2cbf52a07845",
  • "code": 404,
  • "message": "Session not found"
}
Adding a new attribute to a session context
Adds an attribute to a session context file for a session with a given sessionId. 
Recommended for performing calls on the management side.


Note: Optimistic locking is not taken into account here.




Required scopes


    

  • session_context.context_manage
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
Your Emporix tenant's name.


Note: The tenant name should always be provided in lowercase.


 
sessionId
required
string
Customer's session ID.


 
Request Body schema: application/json
key
required
string
Additional context information key


 
required
object or string
Additional context information value


 
Responses 
204
The request was successful. The attribute was added to the session context.


404
A session context with the provided ID was not found.


500
A server-side error occurred.


post/{tenant}/context/{sessionId}/attributes
Request samples 
application/json
{
  • "key": "additional attribute name",
  • "value": "61079711ce0eb90861357045"
}
Response samples 
application/json
{
  • "sessionId": "62528895-b561-4518-bfdc-2cbf52a07845",
  • "code": 404,
  • "message": "Session not found"
}
Own session management
Retrieving own session context
Retrieves a session context associated with the sessionId derived from the Authorization token used in the call.
Recommended for performing calls on the storefront.


SecurityOAuthNoScopes 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
Your Emporix tenant's name.


Note: The tenant name should always be provided in lowercase.


 
Responses 
200
The request was successful. Session context details are returned.


404
A session context with the provided ID was not found.


500
A server-side error occurred.


get/{tenant}/me/context
Request samples 
Response samples 
application/json
{
  • "sessionId": "62528895-b561-4518-bfdc-2cbf52a07845",
  • "customerId": "C87362407845",
  • "siteCode": "main",
  • "currency": "EUR",
  • "targetLocation": "DE",
  • "cartId": "61079711ce0eb90861357045",
  • "context": {
    },
  • "metadata": {
    }
}
Partially updating own session context
Partially updates a session context associated with the sessionId derived from the Authorization token used in the call.
Recommended for performing calls on the storefront.


Note: To update a session context, you need to provide its current metadata.version value in the request body.


Note: Only specific fields can be updated this way, and the rest is ignored. The fields allowed to be updated: siteCode, currency, targetLocation, context.


SecurityOAuthNoScopes 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
Your Emporix tenant's name.


Note: The tenant name should always be provided in lowercase.


 
Request Body schema: application/json
sessionId
string
Unique identifier of the customer's session.


 
customerId
string
Customer's unique identifier.


Note: This field is only applicable to logged-in customers.


 
siteCode
string
Code of the site, as defined in the Site Settings Service.


Note: The default country code for anonymous sessions is based on the home base address country of the default site. In the case of a logged-in customer session, the country code is derived from the customer's shipping address, with the billing address being used as a fallback if the former is not available. If both addresses are not set, the home base address country code from the default site is used.


 
currency
string
Three-letter currency code, as defined in the Currency Service.


Note: During an anonymous session, the default currency of the site serves as the initial currency. Whereas, for a user session, the customer's preferred currency is set as the initial currency.


 
cartId
string
Unique identifier of the active customer cart, generated when the cart is created through the Cart Service.


 
targetLocation
string
The country code, as defined in the country service.


Note: The default country code for anonymous sessions is based on the home base address country of the default site. In the case of a logged-in customer session, the country code is derived from the customer's shipping address, with the billing address being used as a fallback if the former is not available. If both addresses are not set, the home base address country code from the default site is used.


 
required
object (Metadata) 
 
Responses 
204
The request was successful. The session context has been updated.


404
A session context with the provided ID was not found.


500
A server-side error occurred.


patch/{tenant}/me/context
Request samples 
application/json
{
  • "siteCode": "main",
  • "currency": "EUR",
  • "targetLocation": "DE",
  • "metadata": {
    }
}
Response samples 
application/json
{
  • "sessionId": "62528895-b561-4518-bfdc-2cbf52a07845",
  • "code": 404,
  • "message": "Session not found"
}
Own session context modification
Deleting an attribute from own session context
Removes a specified attribute from a session context associated with the sessionId derived from the Authorization token used in the call.
Recommended for performing calls from the storefront.


Note: Optimistic locking is not taken into account here.


SecurityOAuthNoScopes 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
Your Emporix tenant's name.


Note: The tenant name should always be provided in lowercase.


 
attributeName
required
string
Name of the attribute that should be deleted from the session context.


 
Responses 
204
The request was successful. The attribute has been deleted from the session context.


404
A session context with the provided ID was not found.


500
A server-side error occurred.


delete/{tenant}/me/context/attributes/{attributeName}
Request samples 
Response samples 
application/json
{
  • "sessionId": "62528895-b561-4518-bfdc-2cbf52a07845",
  • "code": 404,
  • "message": "Session not found"
}
Adding a new attribute to a session context
Adds an attribute to a session context associated with the session-id derived from the Authorization token used in the call.
Recommended for performing calls from the storefront.


Note: Optimistic locking is not taken into account here.


SecurityOAuthNoScopes 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
Your Emporix tenant's name.


Note: The tenant name should always be provided in lowercase.


 
Request Body schema: application/json
key
required
string
Additional context information key


 
required
object or string
Additional context information value


 
Responses 
201
The request was successful. The attribute was added to the session context.


404
A session context with the provided ID was not found.


500
A server-side error occurred.


post/{tenant}/me/context/attributes
Request samples 
application/json
{
  • "key": "additional attribute name",
  • "value": "61079711ce0eb90861357045"
}
Response samples 
application/json
"attr1"