Emporix Own session management API

openapi: 3.2.0
info:
  title: Emporix Own session management API
  version: ''
  contact:
    email: documentation@emporix.com
  description: 'Operations tagged Own session management across 2 of this provider''s published API definitions: emporix-session-context-openapi.yml, emporix-session-context-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.emporix.io
security:
- OAuth2: []
tags:
- name: Own session management
paths:
  /session-context/{tenant}/me/context:
    description: The session-context resource for own session management.
    parameters:
    - $ref: '#/components/parameters/path_tenant'
    get:
      tags:
      - Own session management
      summary: Retrieving own session context
      operationId: GET-session-context-retrieve-session-context-by-sessionId
      description: 'Retrieves a session context associated with the `sessionId` derived from the Authorization token used in the call. The session context is created when a cart is created; if none exists yet, the response is 404.

        Recommended for performing calls on the storefront.'
      responses:
        '200':
          $ref: '#/components/responses/200_get_session'
        '404':
          $ref: '#/components/responses/404_session'
        '500':
          $ref: '#/components/responses/500_common'
      security:
      - CustomerAccessToken: []
    patch:
      tags:
      - Own session management
      summary: Partially updating own session context
      operationId: PATCH-session-context-update-attribute-sessionId-storefront
      description: '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`, `language`, `context`.'
      responses:
        '204':
          $ref: '#/components/responses/204_update_session'
        '404':
          $ref: '#/components/responses/404_session'
        '500':
          $ref: '#/components/responses/500_common'
      security:
      - CustomerAccessToken: []
      requestBody:
        $ref: '#/components/requestBodies/sessionId_PATCH'
    servers:
    - url: https://api.emporix.io
components:
  schemas:
    MetadataUpdate:
      title: Metadata
      type: object
      properties:
        version:
          type: integer
          description: Version of the session context object.
          example: 1
    ErrorMessage:
      type: object
      properties:
        code:
          type: integer
          description: HTTP Status Code
          example: 404
        message:
          type: string
          description: Detailed error message
    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.
    SessionContextBase:
      title: SessionContextBase
      type: object
      properties:
        sessionId:
          type: string
          description: Unique identifier of the customer's session.
          example: 62528895-b561-4518-bfdc-2cbf52a07845
        customerId:
          type: string
          description: 'Customer unique identifier.


            **Note**: This field is only applicable to logged-in customers.'
          example: C87362407845
        siteCode:
          type: string
          description: '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.'
          example: main
        currency:
          type: string
          description: '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.'
          example: EUR
        cartId:
          type: string
          description: Unique identifier of the active customer cart, generated when the cart is created through the Cart Service.
          example: 61079711ce0eb90861357045
        targetLocation:
          type: string
          example: DE
          description: '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.'
        language:
          type: string
          example: DE
          description: Language associated with the session.
    SessionContext_GET:
      allOf:
      - $ref: '#/components/schemas/SessionContextBase'
      - type: object
        properties:
          context:
            $ref: '#/components/schemas/Context'
      - type: object
        properties:
          metadata:
            $ref: '#/components/schemas/Metadata'
    SessionContext_PATCH:
      title: SessionContextPartialUpdateRequest
      description: 'Request body for partially updating own session context (PATCH /me/context).

        Only the following fields can be updated; all other fields are ignored.

        '
      type: object
      properties:
        siteCode:
          type: string
          description: Code of the site, as defined in the Site Settings Service.
          example: main
        currency:
          type: string
          description: Three-letter currency code, as defined in the Currency Service.
          example: EUR
        targetLocation:
          type: string
          description: The country code, as defined in the country service.
          example: DE
        language:
          type: string
          description: Language associated with the session.
          example: DE
        context:
          $ref: '#/components/schemas/Context'
          description: Custom session attributes. Same structure as returned in the response.
        metadata:
          $ref: '#/components/schemas/MetadataUpdate'
      required:
      - metadata
    Context:
      title: Context
      type: object
      additionalProperties:
        type: object
      example:
        customObject:
          property1: value1
          property2: value2
        customProperty: customValue
  responses:
    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'
          examples:
            404 example:
              value:
                sessionId: 62528895-b561-4518-bfdc-2cbf52a07845
                code: 404
                message: Session not found
    200_get_session:
      description: The request was successful. Session context details are returned.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SessionContext_GET'
    500_common:
      description: A server-side error occurred.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            Internal server error:
              value:
                code: 500
                message: Problem encountered while trying to connect to the database.
    204_update_session:
      description: The request was successful. The session context has been updated.
  parameters:
    path_tenant:
      name: tenant
      in: path
      description: 'Your Emporix tenant name.


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

        '
      schema:
        pattern: ^[a-z][a-z0-9]+$
        minLength: 3
        maxLength: 16
        type: string
      required: true
  requestBodies:
    sessionId_PATCH:
      description: Partial update. Only `siteCode`, `currency`, `targetLocation`, `language`, and `context` are accepted; include `metadata.version` for optimistic locking.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SessionContext_PATCH'
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.emporix.io/oauth/token
          scopes:
            sessioncontext.context_manage: Manage session context
    CustomerAccessToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Customer or anonymous access token. Use the token obtained from the storefront session (e.g. [Requesting an anonymous token](https://developer.emporix.io/api-documentation/api-guides/companies-and-customers/customer-management/api-reference/authentication-and-authorization#get-customerlogin-auth-anonymous-login) or [Logging in a customer](https://developer.emporix.io/api-documentation/api-guides/companies-and-customers/customer-management/api-reference/authentication-and-authorization#post-customer-tenant-login)).

        '
x-refined-from:
- emporix-session-context-openapi.yml
- emporix-session-context-openapi.yml