VTEX Session Manager API

openapi: 3.0.0
info:
  title: VTex Session Manager API
  description: "Session Manager tracks the current browsing sessions of all customers on the VTEX platform. Important session information is automatically captured and stored in a secure and easily accessible location. This includes data such as relevant cookies, query strings, authentication credentials, current profile and pricing information, if applicable. Session Manager API allows developers to retrieve and manage information about sessions. No authentication is required.\r\n\r\nFor more information, read the [Session Manager guide](https://developers.vtex.com/docs/guides/session-manager).\r\n\r\n## Index\r\n\r\n### Sessions\r\n\r\n- `POST` [Create new session](https://developers.vtex.com/docs/api-reference/session-manager-api#post-/api/sessions)\r\n- `GET` [Get session](https://developers.vtex.com/docs/api-reference/session-manager-api#get-/api/sessions)\r\n- `PATCH` [Edit session](https://developers.vtex.com/docs/api-reference/session-manager-api#patch-/api/sessions)\r\n\r\n### Segment\r\n\r\n- `GET` [Get segment](https://developers.vtex.com/docs/api-reference/session-manager-api#get-/api/segments)"
  contact: {}
  version: '1.0'
servers:
  - url: https://{accountName}.{environment}.com.br
    description: VTEX server URL.
    variables:
      accountName:
        description: Name of the VTEX account. Used as part of the URL
        default: apiexamples
      environment:
        description: Environment to use. Used as part of the URL.
        enum:
          - vtexcommercestable
        default: vtexcommercestable
paths:
  /api/sessions:
    post:
      tags:
        - Session
      summary: VTex Create new session
      description: "Creates a new session and returns a session token and a segment token. Also stores `vtex_session` and `vtex_segment` cookies, with the same values returned in the response.\n\r\n\rAll parameters in the body that are not within the public namespace will be ignored. Query string items will automatically be added to the public namespace.\n\r\n\rNo authentication is required.\n\r\n\r>⚠️ The Session Manager API uses the `vtex_session` and `vtex_segment` cookies to store the data required to identify the user and the session. These cookies are stored in the user's browser when the session is created and sent automatically in every request to that domain. You will have to reproduce that by sending these cookies as headers in other requests to Session Manager API in order for it to work outside of a browser environment."
      operationId: Createnewsession
      parameters: []
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEditSessionRequest'
            example:
              public:
                variable1:
                  value: value1
                variable2:
                  value: value2
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateEditSessionResponse'
              example:
                sessionToken: eyJhbGciOiJFUzI1NiIsImtpZCI6IjM5MEI4MTM1RDUzQ0MwMUY0RjA4N0YwMzA2RjhDODMzNzBDMjY4M0UiLCJ0eXAiOiJqd3QifQ.eyJhY2NvdW50LmlkIjoiYThiMjdmYjQtNjUxNi00Y2MwLTgyYjYtYTVmMmIwMTFlNmUyIiwiaWQiOiIyNmQyY2I2Yy0yMTNlLTQ5MzYtOWUyYS0xZDFlMjk5ZWMzM2IiLCJ2ZXJzaW9uIjoyLCJzdWIiOiJzZXNzaW9uIiwiYWNjb3VudCI6InNlc3Npb24iLCJleHAiOjE2OTM1Nzg5NzYsImlhdCI6MTY5Mjg4Nzc3NiwiaXNzIjoidG9rZW4tZW1pdHRlciIsImp0aSI6IjhiYWU2NzdmLWE0NTAtNGI0OC05YTBkLTViMzAwYjNiY2NkOCJ9.Ak1bn2xEA1A5dVN4qR6RI8vnZpSpLXyVxFCthMoVjmWn0HlP5BqMHEMYApDj8TPPhyxT0hGT0vkmvMQa2Mprrw
                segmentToken: eyJjYW1wYWlnbnMiOm51bGwsImNoYW5uZWwiOiIxIiwicHJpY2VUYWJsZXMiOm51bGwsInJlZ2lvbklkIjpudWxsLCJ1dG1fY2FtcGFpZ24iOm51bGwsInV0bV9zb3VyY2UiOm51bGwsInV0bWlfY2FtcGFpZ24iOm51bGwsImN1cnJlbmN5Q29kZSI6IkJSTCIsImN1cnJlbmN5U3ltYm9sIjoiUiQiLCJjb3VudHJ5Q29kZSI6IkJSQSIsImN1bHR1cmVJbmZvIjoiZW4tVVMiLCJjaGFubmVsUHJpdmFjeSI6InB1YmxpYyJ9
      deprecated: false
    get:
      tags:
        - Session
      summary: VTex Get session
      description: "Retrieves information from a previously created sesssion.\n\r\n\r>⚠️ The Session Manager API uses the `vtex_session` and `vtex_segment` cookies to store the data required to identify the user and the session. These cookies are stored in the user's browser when the session is created and sent automatically in every request to that domain. You will have to reproduce that by sending these cookies as headers to Session Manager API in order for it to work outside of a browser environment."
      operationId: GetSession
      parameters:
        - name: items
          in: query
          description: "Items are the keys of the values you wish to get. They follow the format `namespace1.key1,namespace2.key2`.\n\r\n\rIf you wish to recover the data sent on [Create new session](https://developers.vtex.com/docs/api-reference/session-manager-api#post-/api/sessions), it should be `public.{key}`, replacing `{key}` with the name of the custom property you created. Following the example request presented in [Create new session](https://developers.vtex.com/docs/api-reference/session-manager-api#post-/api/sessions), it would be `public.variable1,public.variable2`.\n\r\n\rIf you want to retrieve all keys from Session Manager, you can use the wildcard operator (`*`) as a value for this query parameter."
          required: true
          style: form
          explode: true
          schema:
            type: string
            example: '*'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSessionResponse'
              example:
                id: 26d2cb6c-213e-4936-9e2a-1d1e299ec33b
                namespaces:
                  account:
                    id:
                      value: a8b27fb4-6516-4cc0-82b6-a5f2b011e6e2
                      keepAlive: true
                    accountName:
                      value: apiexamples
                  store:
                    channel:
                      value: '1'
                    countryCode:
                      value: BRA
                    cultureInfo:
                      value: en-US
                    currencyCode:
                      value: BRL
                    currencySymbol:
                      value: R$
                    channelPrivacy:
                      value: public
                  public:
                    variable1:
                      value: value1
                    variable2:
                      value: value2
                  checkout:
                    regionId:
                      value: v2.1BB18CE648B5111D0933734ED83EC783
      security:
        - vtex_session: []
          vtex_segment: []
      deprecated: false
    patch:
      tags:
        - Session
      summary: VTex Edit session
      description: "Edits information from a previously created sesssion.\n\r\n\rThis endpoint works the same way as the [Create new session](https://developers.vtex.com/docs/api-reference/session-manager-api#post-/api/sessions) endpoint, but when the request is sent with a `vtex_session` and the `vtex_segment` cookies in the header, it retrieves the session first and then applies the changes instead of generating a new one.\n\r\n\rOnly keys inside the `public` namespace in the request body are considered, and query parameters are automatically added to the public namespace.\n\r\n\r>⚠️ The Session Manager API uses the `vtex_session` and `vtex_segment` cookies to store the data required to identify the user and the session. These cookies are stored in the user's browser when the session is created and sent automatically in every request to that domain. You will have to reproduce that by sending these cookies as headers to Session Manager API in order for it to work outside of a browser environment."
      operationId: Editsession
      parameters: []
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEditSessionRequest'
            example:
              public:
                variable2:
                  value: value2_patched
                variable3:
                  value: value3
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateEditSessionResponse'
              example:
                sessionToken: eyJhbGciOiJFUzI1NiIsImtpZCI6IjM5MEI4MTM1RDUzQ0MwMUY0RjA4N0YwMzA2RjhDODMzNzBDMjY4M0UiLCJ0eXAiOiJqd3QifQ.eyJhY2NvdW50LmlkIjoiYThiMjdmYjQtNjUxNi00Y2MwLTgyYjYtYTVmMmIwMTFlNmUyIiwiaWQiOiIyNmQyY2I2Yy0yMTNlLTQ5MzYtOWUyYS0xZDFlMjk5ZWMzM2IiLCJ2ZXJzaW9uIjoyLCJzdWIiOiJzZXNzaW9uIiwiYWNjb3VudCI6InNlc3Npb24iLCJleHAiOjE2OTM1Nzg5NzYsImlhdCI6MTY5Mjg4Nzc3NiwiaXNzIjoidG9rZW4tZW1pdHRlciIsImp0aSI6IjhiYWU2NzdmLWE0NTAtNGI0OC05YTBkLTViMzAwYjNiY2NkOCJ9.Ak1bn2xEA1A5dVN4qR6RI8vnZpSpLXyVxFCthMoVjmWn0HlP5BqMHEMYApDj8TPPhyxT0hGT0vkmvMQa2Mprrw
                segmentToken: eyJjYW1wYWlnbnMiOm51bGwsImNoYW5uZWwiOiIxIiwicHJpY2VUYWJsZXMiOm51bGwsInJlZ2lvbklkIjpudWxsLCJ1dG1fY2FtcGFpZ24iOm51bGwsInV0bV9zb3VyY2UiOm51bGwsInV0bWlfY2FtcGFpZ24iOm51bGwsImN1cnJlbmN5Q29kZSI6IkJSTCIsImN1cnJlbmN5U3ltYm9sIjoiUiQiLCJjb3VudHJ5Q29kZSI6IkJSQSIsImN1bHR1cmVJbmZvIjoiZW4tVVMiLCJjaGFubmVsUHJpdmFjeSI6InB1YmxpYyJ9
      security:
        - vtex_session: []
          vtex_segment: []
      deprecated: false
  /api/segments:
    get:
      tags:
        - Segment
      summary: VTex Get segment
      description: "Retrieves information about the segment, which contains additional data related to the session's context.\n\r\n\rYou can add certain public fields as the query string and the system will attempt to fulfill it. Values such as `cultureInfo` and `utm` are overwriteable, just keep in mind such changes will not be reflected in the client's session.\n\r\n\rIf you wish to change the value on the session (and thus be reflected on the segment without special query strings), then use the [Edit session](https://developers.vtex.com/docs/api-reference/session-manager-api#patch-/api/sessions) endpoint. ## Permissions\r\n\r\nThis endpoint does not require [authentication](https://developers.vtex.com/docs/guides/authentication) or [permissions](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3)."
      operationId: GetSegment
      parameters: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Segment'
              example:
                campaigns:
                channel: '1'
                priceTables:
                regionId: v2.1BB18CE648B5111D0933734ED83EC783
                utm_campaign:
                utm_source:
                utmi_campaign:
                currencyCode: BRL
                currencySymbol: R$
                countryCode: BRA
                cultureInfo: en-US
                channelPrivacy: public
      security:
        - vtex_session: []
          vtex_segment: []
      deprecated: false
components:
  securitySchemes:
    vtex_session:
      type: apiKey
      in: cookie
      name: vtex_session
      description: Token that identifies the user's individual session. Obtained [when a new session is created](https://developers.vtex.com/docs/api-reference/session-manager-api#post-/api/sessions).
    vtex_segment:
      type: apiKey
      in: cookie
      name: vtex_segment
      description: Token that identifies the user's segment, shared with other users with similar navigation parameters. Obtained [when a new session is created](https://developers.vtex.com/docs/api-reference/session-manager-api#post-/api/sessions).
  schemas:
    CreateEditSessionRequest:
      title: CreateEditSessionRequest
      required:
        - public
      type: object
      properties:
        public:
          title: Public
          type: object
          properties:
            additionalProperties:
              type: object
              description: Custom property.
              properties:
                value:
                  type: string
                  description: Value of the custom property.
          example:
            variable2:
              value: value2
            variable3:
              value: value3
      example:
        public:
          variable2:
            value: value2
          variable3:
            value: value3
    CreateEditSessionResponse:
      type: object
      description: Object containing session token and segment token.
      properties:
        sessionToken:
          type: string
          description: Token that identifies the user's individual session.
        segmentToken:
          type: string
          description: Token that identifies the user's segment, shared with other users with similar navigation parameters.
      example:
        sessionToken: eyJhbGciOiJFUzI1NiIsImtpZCI6IjM5MEI4MTM1RDUzQ0MwMUY0RjA4N0YwMzA2RjhDODMzNzBDMjY4M0UiLCJ0eXAiOiJqd3QifQ.eyJhY2NvdW50LmlkIjoiYThiMjdmYjQtNjUxNi00Y2MwLTgyYjYtYTVmMmIwMTFlNmUyIiwiaWQiOiIyNmQyY2I2Yy0yMTNlLTQ5MzYtOWUyYS0xZDFlMjk5ZWMzM2IiLCJ2ZXJzaW9uIjoyLCJzdWIiOiJzZXNzaW9uIiwiYWNjb3VudCI6InNlc3Npb24iLCJleHAiOjE2OTM1Nzg5NzYsImlhdCI6MTY5Mjg4Nzc3NiwiaXNzIjoidG9rZW4tZW1pdHRlciIsImp0aSI6IjhiYWU2NzdmLWE0NTAtNGI0OC05YTBkLTViMzAwYjNiY2NkOCJ9.Ak1bn2xEA1A5dVN4qR6RI8vnZpSpLXyVxFCthMoVjmWn0HlP5BqMHEMYApDj8TPPhyxT0hGT0vkmvMQa2Mprrw
        segmentToken: eyJjYW1wYWlnbnMiOm51bGwsImNoYW5uZWwiOiIxIiwicHJpY2VUYWJsZXMiOm51bGwsInJlZ2lvbklkIjpudWxsLCJ1dG1fY2FtcGFpZ24iOm51bGwsInV0bV9zb3VyY2UiOm51bGwsInV0bWlfY2FtcGFpZ24iOm51bGwsImN1cnJlbmN5Q29kZSI6IkJSTCIsImN1cnJlbmN5U3ltYm9sIjoiUiQiLCJjb3VudHJ5Q29kZSI6IkJSQSIsImN1bHR1cmVJbmZvIjoiZW4tVVMiLCJjaGFubmVsUHJpdmFjeSI6InB1YmxpYyJ9
    GetSessionResponse:
      type: object
      properties:
        id:
          type: string
          description: Session ID.
        namespaces:
          type: object
          description: Object with namespaces, each containing a set of information about the session.
          properties:
            account:
              type: object
              description: Account information related to the session.
              properties:
                id:
                  type: object
                  description: VTEX account ID.
                  properties:
                    value:
                      type: string
                      description: Value of the VTEX account ID.
                    keepAlive:
                      type: boolean
                      description: Determines whether or not the connection should be kept alive.
                accountName:
                  type: object
                  description: VTEX account name.
                  properties:
                    value:
                      type: string
                      description: Value of the VTEX account name.
            store:
              type: object
              description: Store information related to the session.
              properties:
                channel:
                  type: object
                  description: '[Trade policy](https://help.vtex.com/en/tutorial/how-trade-policies-work--6Xef8PZiFm40kg2STrMkMV) ID.'
                  properties:
                    value:
                      type: string
                      description: Value of the [Trade policy](https://help.vtex.com/en/tutorial/how-trade-policies-work--6Xef8PZiFm40kg2STrMkMV) ID.
                countryCode:
                  type: object
                  description: Country code.
                  properties:
                    value:
                      type: string
                      description: Value of the country code.
                cultureInfo:
                  type: object
                  description: Locale that provides culture-specific information, such as the language, sublanguage, country/region, calendar, and conventions associated with a particular culture. Read [this documentation](https://learn.microsoft.com/en-us/dotnet/api/system.globalization.cultureinfo?view=net-7.0#culture-names-and-identifiers) for more details.
                  properties:
                    value:
                      type: string
                      description: Value of the `cultureInfo` property.
                currencyCode:
                  type: object
                  description: Currency code.
                  properties:
                    value:
                      type: string
                      description: Value of the currency code.
                currencySymbol:
                  type: object
                  description: Currency symbol.
                  properties:
                    value:
                      type: string
                      description: Value of the currency symbol.
                channelPrivacy:
                  type: object
                  description: Defines whether or not the channel is private.
                  properties:
                    value:
                      type: string
                      description: Value containing the channel's privacy option.
            public:
              type: object
              description: Public and editable information related to the session.
              additionalProperties:
                type: object
                description: Custom property.
                properties:
                  value:
                    type: string
                    description: Value of the custom property.
            checkout:
              type: object
              description: Checkout information related to the session.
              properties:
                regionId:
                  type: object
                  description: ID of the session's region.
                  properties:
                    value:
                      type: string
                      description: Value of the Region ID.
      example:
        id: 26d2cb6c-213e-4936-9e2a-1d1e299ec33b
        namespaces:
          account:
            id:
              value: a8b27fb4-6516-4cc0-82b6-a5f2b011e6e2
              keepAlive: true
            accountName:
              value: apiexamples
          store:
            channel:
              value: '1'
            countryCode:
              value: BRA
            cultureInfo:
              value: en-US
            currencyCode:
              value: BRL
            currencySymbol:
              value: R$
            channelPrivacy:
              value: public
          public:
            variable1:
              value: value1
            variable2:
              value: value2
          checkout:
            regionId:
              value: v2.1BB18CE648B5111D0933734ED83EC783
    Segment:
      type: object
      description: Object containing information about the segment.
      properties:
        campaigns:
          type: string
          description: Campaigns associated with the session.
        channel:
          type: string
          description: '[Trade policy](https://help.vtex.com/en/tutorial/how-trade-policies-work--6Xef8PZiFm40kg2STrMkMV) ID.'
        priceTables:
          type: string
          description: Price tables associated with the session.
        regionId:
          type: string
          description: ID of the session's region.
        utm_campaign:
          type: string
          description: UTM campaign code.
        utm_source:
          type: string
          description: UTM source code.
        utmi_campaign:
          type: string
          description: UTMI campaign code.
        currencyCode:
          type: string
          description: Currency code.
        currencySymbol:
          type: string
          description: Currency symbol.
        countryCode:
          type: string
          description: Country code.
        cultureInfo:
          type: string
          description: Locale that provides culture-specific information, such as the language, sublanguage, country/region, calendar, and conventions associated with a particular culture. Read [this documentation](https://learn.microsoft.com/en-us/dotnet/api/system.globalization.cultureinfo?view=net-7.0#culture-names-and-identifiers) for more details.
        channelPrivacy:
          type: string
          description: Defines whether or not the channel is private.
      example:
        campaigns:
        channel: '1'
        priceTables:
        regionId: v2.1BB18CE648B5111D0933734ED83EC783
        utm_campaign:
        utm_source:
        utmi_campaign:
        currencyCode: BRL
        currencySymbol: R$
        countryCode: BRA
        cultureInfo: pt-BR
        channelPrivacy: public
tags:
  - name: Segment
    description: ''
  - name: Session
    description: ''