# 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."}}},"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."}}},"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"}}}}}
```