Walmart Marketplace Authentication API

openapi: 3.0.1
info:
  title: Walmart Authentication & Authorization Management
  description: The Walmart Marketplace APIs use OAuth for token-based authentication and authorization.<Br /> We also introduced OAuth 2.0 for solution providers to enable new authorizations using authorization code grant type. Sellers can now connect with solution provider apps seamlessly through this new Walmart's OAuth 2.0 user experience. Refer to the [Guide section](/doc/us/mp/us-mp-auth2/#606) for comprehensive instructions. Existing seller connections using the previous authorization method will remain operational.
servers:
  - url: https://marketplace.walmartapis.com
    description: Production URL
  - url: https://sandbox.walmartapis.com
    description: Sandbox URL
security:
  - basicScheme: []
paths:
  "/v3/token":
    post:
      tags:
        - Authorization
      summary: Walmart Token Api
      description: Get access token by providing Client ID and Client Secret.<br />An access token expires after a certain interval, so you will have to refresh a user's access token. You could use refresh token, obtained from the token API call using authorization code grant type, to get a new access token. Refresh tokens remain valid for a year.<br /><br /> [Guide reference - authorization_code](/doc/us/mp/us-mp-auth2/#606)<br /><br /> [Guide reference - refresh_token](/doc/us/mp/us-mp-auth2/#606)<br /><br /> [Guide reference - client_credentials](/doc/us/mp/us-mp-auth/#606)
      operationId: tokenAPI
      parameters:
        - in: header
          name: WM_PARTNER.ID
          description: 'Partner Id registered in Walmart marketplace to identify a seller. <br /> This field is required when **grant_type: authorization_code** and **grant_type: refresh_token**'
          required: false
          schema:
            type: string
          example: '43423324'
        - in: header
          name: Authorization
          description: Basic authorization header. Base 64 encodes the Client ID and Client Secret retrieved in step two of the integration steps.
          required: true
          schema:
            type: string
          example: Basic YzcyOTFjNmItNzI5MC00....
        - in: header
          name: Content-Type
          description: Content type of the request body.
          required: true
          schema:
            type: string
          example: application/x-www-form-urlencoded
        - in: header
          name: WM_CONSUMER.CHANNEL.TYPE
          description: A unique ID to track the consumer request by channel. Use the Consumer Channel Type received during onboarding.
          required: false
          schema:
            type: string
        - in: header
          name: WM_QOS.CORRELATION_ID
          description: A unique ID which identifies each API call and used to track and debug issues; use a random generated GUID for this ID
          required: true
          schema:
            type: string
          example: b3261d2d-028a-4ef7-8602-633c23200af6
        - in: header
          name: WM_SVC.NAME
          description: Walmart Service Name
          required: true
          schema:
            type: string
          example: Walmart Service Name
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              required:
                - grant_type
              type: object
              properties:
                grant_type:
                  type: string
                  description: Type of grant requested. <br /> **Available grant types:** authorization_code, refresh_token and client_credentials
                  enum:
                    - authorization_code
                    - refresh_token
                    - client_credentials
                  default: client_credentials
                code:
                  type: string
                  description: 'Authorization code obtained by your client app when the seller authorizes your app to access the seller resource. <br /> This field is required when **grant_type: authorization_code**'
                  default: 65CA5DA313A549D49D15D3119D9AD85D
                redirect_uri:
                  type: string
                  description: 'This should be same as one of your client app URIs provided while registering the app. <br /> This field is required when **grant_type: authorization_code**'
                  default: https://example-client-app.com
                refresh_token:
                  type: string
                  description: 'Refresh token received as response of Authentication API with authorization_code grant type, to be used to refresh the access token. <br /> This field is required when **grant_type: refresh_token**'
                  default: APXcIoTpKMH9OQN.....
            examples:
              clientCredentialsReq:
                summary: Token Api - Client_credentials
                value:
                  grant_type: client_credentials
              tokenAPIReq:
                summary: Token Api - Authorization_code
                value:
                  grant_type: authorization_code
                  code: 65CA5DA313A549D49D15D3119D9AD85D
                  redirect_uri: https://example-client-app.com
              refreshTokenReq:
                summary: Token Api - Refresh_token
                value:
                  grant_type: refresh_token
                  refresh_token: APXcIoTpKMH9OQN…….
        required: true
      responses:
        '200':
          description: Successful Operation
          content:
            application/json:
              schema:
                required:
                  - access_token
                  - expires_in
                  - token_type
                type: object
                properties:
                  access_token:
                    type: string
                    description: Access token to be used for accessing business APIs
                    default: eyJraWQiOiI1MWY3MjM0Ny0wYWY5LTRhZ....
                  token_type:
                    type: string
                    description: Type of token according to user. (e.g., 'BEARER')
                    default: Bearer
                  expires_in:
                    type: integer
                    description: Expiry time of access token in seconds
                    format: int32
                    default: 900
                  refresh_token:
                    type: string
                    description: 'Token which should be used to refresh access token.<br /> This field is present in response when **grant_type: authorization_code**'
                    default: APXcIoTpKMH9OQN…….
              examples:
                clientCredentialsRes:
                  summary: Token Api - Client_credentials
                  value:
                    access_token: eyJraWQiOiI1MWY3MjM0Ny0wYWY5LTRhZ.....
                    token_type: Bearer
                    expires_in: 900
                tokenAPIRes:
                  summary: Token Api - Authorization_code
                  value:
                    access_token: eyJraWQiOiI1MWY3MjM0Ny0wYWY5LTRhZ.....
                    refresh_token: APXcIoTpKMH9OQN....
                    token_type: Bearer
                    expires_in: 900
                refreshTokenRes:
                  summary: Token Api - Refresh_token
                  value:
                    access_token: eyJraWQiOiI1MWY3MjM0Ny0wYWY5LTRhZ.....
                    token_type: Bearer
                    expires_in: 900
              example:
                access_token: eyJraWQiOiIzN2JmOWQ5MS04ZDRkLTQwYjEtODU4NS1mNzhlZDc3MjM4MDQiLCJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiZGlyIn0..bKkYKqJ5CP0Qb2Qz.wQ4TTa2nwL1rbT98BBdbTi_MRNMM0gW_5q8im6uX4olRwYiuOXjaG6TbnnFOK5fT0UzMEJUf-uybalogMH78cHP0ZyL6hONKJOMJ8VK3ThcZ4AUcqrMRBNIMFiAWSTvHJg1y5g-t-WwmZbaD589dMll7-aXG6PPncpeQA1zOyOTaELjDA4O4jimc2_7PnEdc6ETv89AKcnw1J1cPz6BPG9jpyLVX_zEZcQnxbAHYZiSFscFCzdMtpFDrPWIwWuRcV5qRlH4DghHMqKG7V2wqX1VYV_gUvLH5b2y8O6Y0u9nmkBpqTGNiMpWzNE7amFyqKExGk4Jc_ziJdsrj38cSz9a4KtZOrV6E3mN5gFFEQSNAGzrdEv2IdTfWdNgTnHopQecgrlP7EcsrmGh1ARGTWr-e7RaiL8m2Sx5i9odGj5FDJKXiDeohX-KEB-Vc2KJeLxvYAHA7nPT1_pkZDBCfpqq_6GAUBDEbDZ6mJH93TAE1YhFeR_jcdl_23lND9sHKlvHA97-fHAjEVTqu-4wVmFFelGyJD4VIBkieWn94jq_opMiz-RjyYn8Vj-tfdJy8azBNt5NkjjW7Rsque04LsfujrqHDcJHio3ukT5JKwxNv9PoHMxoHnQ5fUdF4pOzt6ZShkki-jSbhileDlClh0ufLSNYgBmy6Fz4wTZWgL-DhJOcv-7Cup95Rx35Wh7XDYTbdz_z_avtfF-f-JS5XyN20Hn-gioWdNA7DNhI1O6s7zKZ2s2iD9eFkprOLGtcJzvNVjrxKZKD6R0hrUUzDXRn95oWlJXfan-OsTNdRypfGWFqIes-n8cBhzVF69LEWIDMr6YfdkRkmCq_p_A.Bvyf-k_rnsiiuf0jGGVXvw
                token_type: Bearer
                expires_in: 900
            application/xml:
              schema:
                required:
                  - accessToken
                type: object
                properties:
                  accessToken:
                    type: string
                    description: Access token to be used for accessing business APIs
                    xml:
                      namespace: http://walmart.com/
                  tokenType:
                    type: string
                    description: Type of token according to user. (e.g., 'BEARER')
                    xml:
                      namespace: http://walmart.com/
                  expiresIn:
                    type: integer
                    description: Expiry time of access token in seconds
                    format: int32
                    xml:
                      namespace: http://walmart.com/
                  refresh_token:
                    type: string
                    description: 'Token which should be used to refresh access token.<br /> This field is present in response when **grant_type: authorization_code**'
                    xml:
                      namespace: http://walmart.com/
                xml:
                  name: oAuthToken
              example: |
                <OAuthTokenDTO xmlns="">
                    <accessToken>eyJraWQiOiIzN2JmOWQ5MS04ZDRkLTQwYjEtODU4NS1mNzhlZDc3MjM4MDQiLCJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiZGlyIn0..yI0d0EFgt3gpEMQj.APvV5upgh1nBRcZPG6d9a5PYNAwayZdIZc4s-J42Ol-Zk6V9liVWmgs4qyPdkghfLKWwAyOBoc5g1vxRsYQNOeDH_p7KM_dO3D80g8adtGDkcAoEimyhP0inGHOjT2PziwIWjtRbE5bm8WTZN7wwJPV5SFqBP-XvS03OdPcZ2V_f0mVln5EdzaRt0BmpvlVDgqn_9Pe_jIYadWX-qc1N_Lh6oe3Q6bUKTJIhb6N-v8dNDO6qyRbeWo0_0M1s7g_mBKIp2FeO8a_ezIkpjtRv81SwXxEDqFacT2O46GlILO0Nfh7lbI2HZK2eUPrC-XVCiLiGoKsQDxHxD_Po0QrH0OxD6jnQvUfiqpgsULsvtbsSuHpUNl-OlIFhxODRxyIILsjAoWaQi9yEEV5swLVTdCix7e8ZKJPWQKEi55e7WYZm8vJqIUaaKrgdbw8HDlOWiJcrzzKdg-Hk3QBxnuoT4wqiaJaKb3uIQUtPzo5Jn_58PIxHh1WawpJOOmTH5RFgGTHlMB-5nBKG0iW1Bzm_vlg0NU_ZlYjvTWWDGOldk18WbzBr88XUI_jyRylFp_gYxc2peAyPnhZtOJGC4-7Eudbjz7QtClntVenjcG9h0k-xUejD0fcvCQUCty8S0ZfvCMEhrOJXEYCfI9-ESFFzpRh0EDCyfllS2Ugor4ZtUBjztXsj5sz2tp1wOSG7QR22K8rBKBFSyaKdIrNoLoucCEFFqlK_WSxfgsvUhspr4ZztxzPCejv3pKu9XYOV5nM6_qRsQY9ub88kQQKf2ZwNUnuYM_JYcvr2P9R551Pqqssk2KmbU42P35a2t5xJo9h921tGxUNjS9k4LAaO9g.Em_yWzxnUwwvs90IRZzH-Q</accessToken>
                    <tokenType>Bearer</tokenType>
                    <expiresIn>900</expiresIn>
                </OAuthTokenDTO>
  "/v3/token/detail":
    get:
      tags:
        - Authorization
      summary: Walmart Token Detail
      description: 'This process retrieves the access permissions granted by sellers to applications in the context of OAuth 2.0. The scope encompasses various API categories, each with its respective access levels, for example Reports: View Only, Item: Full Access, etc.'
      externalDocs:
        description: View Guide
        url: "/doc/us/mp/us-mp-auth2/#606"
      operationId: getTokenDetail
      parameters:
        - in: header
          name: WM_SEC.ACCESS_TOKEN
          description: The access token retrieved in the Token API call
          required: true
          schema:
            type: string
          example: eyJraWQiOiIzZjVhYTFmNS1hYWE5LTQzM.....
        - in: header
          name: Content-Type
          description: Content type of the request body.
          required: true
          schema:
            type: string
          example: application/x-www-form-urlencoded
        - in: header
          name: WM_CONSUMER.CHANNEL.TYPE
          description: A unique ID to track the consumer request by channel. Use the Consumer Channel Type received during onboarding.
          required: false
          schema:
            type: string
        - in: header
          name: WM_QOS.CORRELATION_ID
          description: A unique ID which identifies each API call and used to track and debug issues; use a random generated GUID for this ID
          required: true
          schema:
            type: string
          example: b3261d2d-028a-4ef7-8602-633c23200af6
        - in: header
          name: WM_SVC.NAME
          description: Walmart Service Name
          required: true
          schema:
            type: string
          example: Walmart Service Name
      responses:
        '200':
          description: Successful Operation
          content:
            application/json:
              schema:
                required:
                  - expire_at
                  - is_channel_match
                  - is_valid
                  - issued_at
                  - scopes
                type: object
                properties:
                  scopes:
                    type: object
                    properties:
                      reports:
                        type: string
                        enum:
                          - full_access
                          - view_only
                          - no_access
                      item:
                        type: string
                        enum:
                          - full_access
                          - view_only
                          - no_access
                      shipping:
                        type: string
                        enum:
                          - full_access
                          - view_only
                          - no_access
                      price:
                        type: string
                        enum:
                          - full_access
                          - view_only
                          - no_access
                      lagtime:
                        type: string
                        enum:
                          - full_access
                          - view_only
                          - no_access
                      feeds:
                        type: string
                        enum:
                          - full_access
                          - view_only
                          - no_access
                      returns:
                        type: string
                        enum:
                          - full_access
                          - view_only
                          - no_access
                      orders:
                        type: string
                        enum:
                          - full_access
                          - view_only
                          - no_access
                      rules:
                        type: string
                        enum:
                          - full_access
                          - view_only
                          - no_access
                      inventory:
                        type: string
                        enum:
                          - full_access
                          - view_only
                          - no_access
                      content:
                        type: string
                        enum:
                          - full_access
                          - view_only
                          - no_access
                    description: The API categories with their corresponding access levels
                    default: "{“reports”: “view_only”}"
                  expire_at:
                    type: string
                    description: The timestamp when the token expires
                    default: '1560973098000'
                  issued_at:
                    type: string
                    description: The timestamp when the token is issued
                    default: '1560973098000'
                  is_valid:
                    type: boolean
                    description: Whether the token is valid; boolean value of true or false
                    default: true
                  is_channel_match:
                    type: boolean
                    description: Whether the keys Seller used are correctly associated
                    default: true
              example:
                expire_at: '1560973098000'
                issued_at: '1560972198000'
                is_valid: true
                scopes:
                  reports: view_only
                  item: full_access
                  price: no_access
                  lagtime: full_access
                  feeds: view_only
                  returns: full_access
                  orders: full_access
                  inventory: full_access
                  content: full_access
components:
  schemas:
    OAuthTokenDTO:
      required:
        - accessToken
      type: object
      properties:
        accessToken:
          type: string
          description: Access token to be used for accessing business APIs
          xml:
            namespace: http://walmart.com/
        tokenType:
          type: string
          description: Type of token according to user. (e.g., 'BEARER')
          xml:
            namespace: http://walmart.com/
        expiresIn:
          type: integer
          description: Expiry time of access token in seconds
          format: int32
          xml:
            namespace: http://walmart.com/
        refresh_token:
          type: string
          description: 'Token which should be used to refresh access token.<br /> This field is present in response when **grant_type: authorization_code**'
          xml:
            namespace: http://walmart.com/
      xml:
        name: oAuthToken
    OAuthToken:
      required:
        - access_token
        - expires_in
        - token_type
      type: object
      properties:
        access_token:
          type: string
          description: Access token to be used for accessing business APIs
          default: eyJraWQiOiI1MWY3MjM0Ny0wYWY5LTRhZ....
        token_type:
          type: string
          description: Type of token according to user. (e.g., 'BEARER')
          default: Bearer
        expires_in:
          type: integer
          description: Expiry time of access token in seconds
          format: int32
          default: 900
        refresh_token:
          type: string
          description: 'Token which should be used to refresh access token.<br /> This field is present in response when **grant_type: authorization_code**'
          default: APXcIoTpKMH9OQN…….
    IAMTokenDTO:
      required:
        - grant_type
      type: object
      properties:
        grant_type:
          type: string
          description: Type of grant requested. <br /> **Available grant types:** authorization_code, refresh_token and client_credentials
          enum:
            - authorization_code
            - refresh_token
            - client_credentials
          default: client_credentials
        code:
          type: string
          description: 'Authorization code obtained by your client app when the seller authorizes your app to access the seller resource. <br /> This field is required when **grant_type: authorization_code**'
          default: 65CA5DA313A549D49D15D3119D9AD85D
        redirect_uri:
          type: string
          description: 'This should be same as one of your client app URIs provided while registering the app. <br /> This field is required when **grant_type: authorization_code**'
          default: https://example-client-app.com
        refresh_token:
          type: string
          description: 'Refresh token received as response of Authentication API with authorization_code grant type, to be used to refresh the access token. <br /> This field is required when **grant_type: refresh_token**'
          default: APXcIoTpKMH9OQN.....
    Scopes:
      type: object
      properties:
        reports:
          type: string
          enum:
            - full_access
            - view_only
            - no_access
        item:
          type: string
          enum:
            - full_access
            - view_only
            - no_access
        shipping:
          type: string
          enum:
            - full_access
            - view_only
            - no_access
        price:
          type: string
          enum:
            - full_access
            - view_only
            - no_access
        lagtime:
          type: string
          enum:
            - full_access
            - view_only
            - no_access
        feeds:
          type: string
          enum:
            - full_access
            - view_only
            - no_access
        returns:
          type: string
          enum:
            - full_access
            - view_only
            - no_access
        orders:
          type: string
          enum:
            - full_access
            - view_only
            - no_access
        rules:
          type: string
          enum:
            - full_access
            - view_only
            - no_access
        inventory:
          type: string
          enum:
            - full_access
            - view_only
            - no_access
        content:
          type: string
          enum:
            - full_access
            - view_only
            - no_access
      description: The API categories with their corresponding access levels
      default: "{“reports”: “view_only”}"
    TokenDetailResponse:
      required:
        - expire_at
        - is_channel_match
        - is_valid
        - issued_at
        - scopes
      type: object
      properties:
        scopes:
          type: object
          properties:
            reports:
              type: string
              enum:
                - full_access
                - view_only
                - no_access
            item:
              type: string
              enum:
                - full_access
                - view_only
                - no_access
            shipping:
              type: string
              enum:
                - full_access
                - view_only
                - no_access
            price:
              type: string
              enum:
                - full_access
                - view_only
                - no_access
            lagtime:
              type: string
              enum:
                - full_access
                - view_only
                - no_access
            feeds:
              type: string
              enum:
                - full_access
                - view_only
                - no_access
            returns:
              type: string
              enum:
                - full_access
                - view_only
                - no_access
            orders:
              type: string
              enum:
                - full_access
                - view_only
                - no_access
            rules:
              type: string
              enum:
                - full_access
                - view_only
                - no_access
            inventory:
              type: string
              enum:
                - full_access
                - view_only
                - no_access
            content:
              type: string
              enum:
                - full_access
                - view_only
                - no_access
          description: The API categories with their corresponding access levels
          default: "{“reports”: “view_only”}"
        expire_at:
          type: string
          description: The timestamp when the token expires
          default: '1560973098000'
        issued_at:
          type: string
          description: The timestamp when the token is issued
          default: '1560973098000'
        is_valid:
          type: boolean
          description: Whether the token is valid; boolean value of true or false
          default: true
        is_channel_match:
          type: boolean
          description: Whether the keys Seller used are correctly associated
          default: true
  parameters:
    authorization:
      name: Authorization
      in: header
      description: Basic authorization header. Base 64 encodes the Client ID and Client Secret retrieved in step two of the integration steps.
      required: true
      schema:
        type: string
      example: Basic YzcyOTFjNmItNzI5MC00....
    accessToken:
      name: WM_SEC.ACCESS_TOKEN
      in: header
      description: The access token retrieved in the Token API call
      required: true
      schema:
        type: string
      example: eyJraWQiOiIzZjVhYTFmNS1hYWE5LTQzM.....
    channelType:
      name: WM_CONSUMER.CHANNEL.TYPE
      in: header
      description: A unique ID to track the consumer request by channel. Use the Consumer Channel Type received during onboarding.
      required: false
      schema:
        type: string
    correlationId:
      name: WM_QOS.CORRELATION_ID
      in: header
      description: A unique ID which identifies each API call and used to track and debug issues; use a random generated GUID for this ID
      required: true
      schema:
        type: string
      example: b3261d2d-028a-4ef7-8602-633c23200af6
    svcName:
      name: WM_SVC.NAME
      in: header
      description: Walmart Service Name
      required: true
      schema:
        type: string
      example: Walmart Service Name
    content-type:
      name: Content-Type
      in: header
      description: Content type of the request body.
      required: true
      schema:
        type: string
      example: application/x-www-form-urlencoded
    wm_partner_id:
      name: WM_PARTNER.ID
      in: header
      description: 'Partner Id registered in Walmart marketplace to identify a seller. <br /> This field is required when **grant_type: authorization_code** and **grant_type: refresh_token**'
      required: false
      schema:
        type: string
      example: '43423324'
  securitySchemes:
    basicScheme:
      type: http
      description: ''
      name: Authorization
      in: header
      scheme: basic
tags:
  - name: Authorization