# Session management

## Retrieving a session context

> Retrieves a specified session context. A session context is created when a cart is created for that session; until then it does not exist.\
> Recommended for performing calls on the management side.

```json
{"openapi":"3.0.0","info":{"title":"Session Context Service","version":"0.0.1"},"tags":[{"name":"Session management"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["sessioncontext.context_manage"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"sessioncontext.context_manage":"Manage session context"}}}}},"responses":{"200_get_session":{"description":"The request was successful. Session context details are returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionContext_GET"}}}},"404_session":{"description":"A session context with the provided ID was not found.","content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"sessionId":{"type":"string","description":"Unique identifier of the session."}}},{"$ref":"#/components/schemas/ErrorMessage"}]}}}},"500_common":{"description":"A server-side error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}},"schemas":{"SessionContext_GET":{"allOf":[{"$ref":"#/components/schemas/SessionContextBase"},{"type":"object","properties":{"context":{"$ref":"#/components/schemas/Context"}}},{"type":"object","properties":{"metadata":{"$ref":"#/components/schemas/Metadata"}}}]},"SessionContextBase":{"title":"SessionContextBase","type":"object","properties":{"sessionId":{"type":"string","description":"Unique identifier of the customer's session."},"customerId":{"type":"string","description":"Customer unique identifier.\n\n**Note**: This field is only applicable to logged-in customers."},"siteCode":{"type":"string","description":"Code of the site, as defined in the Site Settings Service.\n\n**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":{"type":"string","description":"Three-letter currency code, as defined in the Currency Service.\n\n**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":{"type":"string","description":"Unique identifier of the active customer cart, generated when the cart is created through the Cart Service."},"targetLocation":{"type":"string","description":"The country code, as defined in the country service.\n\n\n**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."},"language":{"type":"string","description":"Language associated with the session."}}},"Context":{"title":"Context","type":"object","additionalProperties":{"type":"object"}},"Metadata":{"allOf":[{"$ref":"#/components/schemas/MetadataUpdate"},{"type":"object","properties":{"createdAt":{"type":"string","description":"Date and time when the object was created."},"modifiedAt":{"type":"string","description":"Date and time when the object was last modified."}}}]},"MetadataUpdate":{"title":"Metadata","type":"object","properties":{"version":{"type":"integer","description":"Version of the session context object."}}},"ErrorMessage":{"type":"object","properties":{"code":{"type":"integer","description":"HTTP Status Code"},"message":{"type":"string","description":"Detailed error message"}}}}},"paths":{"/session-context/{tenant}/context/{sessionId}":{"get":{"tags":["Session management"],"summary":"Retrieving a session context","operationId":"GET-session-context-retrieve-session-context","description":"Retrieves a specified session context. A session context is created when a cart is created for that session; until then it does not exist.\nRecommended for performing calls on the management side.","responses":{"200":{"$ref":"#/components/responses/200_get_session"},"404":{"$ref":"#/components/responses/404_session"},"500":{"$ref":"#/components/responses/500_common"}}}}}}
```

## 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.

```json
{"openapi":"3.0.0","info":{"title":"Session Context Service","version":"0.0.1"},"tags":[{"name":"Session management"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["sessioncontext.context_manage"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"sessioncontext.context_manage":"Manage session context"}}}}},"parameters":{"query_upsert":{"name":"upsert","in":"query","required":false,"schema":{"type":"string"},"description":"* If set to `true` and the session with the specified id does not exist, the session will be created.\n* If set to `false` or not specified, a standard update will be performed.\n"},"header_saas-token":{"name":"saas-token","in":"header","required":false,"schema":{"type":"string"},"description":"Customer access token. \n\n**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.\n"}},"responses":{"204_update_session":{"description":"The request was successful. The session context has been updated."},"404_session":{"description":"A session context with the provided ID was not found.","content":{"application/json":{"schema":{"allOf":[{"type":"object","properties":{"sessionId":{"type":"string","description":"Unique identifier of the session."}}},{"$ref":"#/components/schemas/ErrorMessage"}]}}}},"500_common":{"description":"A server-side error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}},"schemas":{"ErrorMessage":{"type":"object","properties":{"code":{"type":"integer","description":"HTTP Status Code"},"message":{"type":"string","description":"Detailed error message"}}},"SessionContext_PUT":{"title":"SessionContextUpdateRequest","description":"Request body for updating a session context (PUT).\nYou can send any of the session fields returned in the GET response, including `context` (custom attributes key-value map).\nThe `metadata.version` is required for optimistic locking.\n","allOf":[{"$ref":"#/components/schemas/SessionContextBase"},{"type":"object","properties":{"context":{"$ref":"#/components/schemas/Context","description":"Custom session attributes. Same structure as returned in the response."},"metadata":{"$ref":"#/components/schemas/MetadataUpdate"}},"required":["metadata"]}]},"SessionContextBase":{"title":"SessionContextBase","type":"object","properties":{"sessionId":{"type":"string","description":"Unique identifier of the customer's session."},"customerId":{"type":"string","description":"Customer unique identifier.\n\n**Note**: This field is only applicable to logged-in customers."},"siteCode":{"type":"string","description":"Code of the site, as defined in the Site Settings Service.\n\n**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":{"type":"string","description":"Three-letter currency code, as defined in the Currency Service.\n\n**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":{"type":"string","description":"Unique identifier of the active customer cart, generated when the cart is created through the Cart Service."},"targetLocation":{"type":"string","description":"The country code, as defined in the country service.\n\n\n**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."},"language":{"type":"string","description":"Language associated with the session."}}},"Context":{"title":"Context","type":"object","additionalProperties":{"type":"object"}},"MetadataUpdate":{"title":"Metadata","type":"object","properties":{"version":{"type":"integer","description":"Version of the session context object."}}}},"requestBodies":{"sessionId_PUT":{"description":"Session context update. Include `context` to update custom attributes; `metadata.version` is required for optimistic locking.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionContext_PUT"}}}}}},"paths":{"/session-context/{tenant}/context/{sessionId}":{"put":{"tags":["Session management"],"summary":"Updating a session context","operationId":"PUT-session-context-update-session-context","description":"Updates a specified session context.\nRecommended for performing calls on the management side.\n\n**Note**: To update a session context, you need to provide its current `metadata.version` value in the request body.","parameters":[{"$ref":"#/components/parameters/query_upsert"},{"$ref":"#/components/parameters/header_saas-token"}],"responses":{"204":{"$ref":"#/components/responses/204_update_session"},"404":{"$ref":"#/components/responses/404_session"},"500":{"$ref":"#/components/responses/500_common"}},"requestBody":{"$ref":"#/components/requestBodies/sessionId_PUT"}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.emporix.io/api-references/api-guides/users-and-permissions/session-context/api-reference/session-management.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.