VTEX SKU Seller API

openapi: 3.2.0
info:
  title: VTex Catalog SKU Seller API
  description: '> Check the new Catalog onboarding guide.'
  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
security:
- appKey: []
  appToken: []
- VtexIdclientAutCookie: []
tags:
- name: SKU Seller
paths:
  /api/catalog_system/pvt/skuseller/{sellerId}/{sellerSkuId}:
    get:
      tags:
      - SKU Seller
      summary: VTex Get details of a seller's SKU
      description: '> ⚠️ Check out the updated version of this endpoint in our SKU Bindings API documentation. If you are doing this integration for the first time, we recommend that you follow the updated documentation.


        Retrieves the details of a seller''s SKU given a seller ID and the SKU ID in the seller''s store.


        ## Permissions


        Any user or application key must have at least one of the appropriate License Manager resources to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:


        | **Product** | **Category** | **Resource** |

        | --------------- | ----------------- | ----------------- |

        | Catalog | Marketplace | **Seller SKUs** |


        There are no applicable predefined roles for this resource list. You must create a custom role and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see Authentication overview.


        >❗ To prevent integrations from having excessive permissions, consider the best practices for managing app keys when assigning License Manager roles to integrations.'
      operationId: GetSKUseller
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      - name: sellerId
        in: path
        description: ID that identifies the seller in the marketplace. It can be the same as the seller name or a unique number. Check the **Sellers management** section in the Admin to get the correct ID.
        required: true
        style: simple
        schema:
          type: string
          example: '101'
      - name: sellerSkuId
        in: path
        description: SKU ID in the seller's store.
        required: true
        style: simple
        schema:
          type: string
          example: '1'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - IsPersisted
                - IsRemoved
                - SkuSellerId
                - SellerId
                - StockKeepingUnitId
                - SellerStockKeepingUnitId
                - IsActive
                - UpdateDate
                - RequestedUpdateDate
                properties:
                  IsPersisted:
                    type: boolean
                    description: Defines if the seller is persisted.
                  IsRemoved:
                    type: boolean
                    description: Defines if the seller is removed.
                  SkuSellerId:
                    type: integer
                    format: int32
                    description: SKU ID in the seller's store.
                  SellerId:
                    type: string
                    description: ID that identifies the seller in the marketplace. It can be the same as the seller name or a unique number. Check the **Sellers management** section in the Admin to get the correct ID.
                  StockKeepingUnitId:
                    type: integer
                    format: int32
                    description: SKU ID in the VTEX marketplace.
                  SellerStockKeepingUnitId:
                    type: string
                    description: SKU seller ID.
                  IsActive:
                    type: boolean
                    description: Defines if the SKU binding is active.
                  UpdateDate:
                    type: string
                    description: Date when the SKU binding was updated for the last time, in UTC format.
                  RequestedUpdateDate:
                    type:
                    - string
                    - 'null'
                    description: Date when an SKU binding update was requested for the last time, in UTC format.
              example:
                IsPersisted: true
                IsRemoved: false
                SkuSellerId: 799
                SellerId: myseller
                StockKeepingUnitId: 50
                SellerStockKeepingUnitId: '502'
                IsActive: true
                UpdateDate: '2018-10-11T04:52:42.1'
                RequestedUpdateDate: null
      deprecated: false
  /api/catalog_system/pvt/skuseller/remove/{sellerId}/{sellerSkuId}:
    post:
      tags:
      - SKU Seller
      summary: VTex Remove a seller's SKU binding
      description: '> ⚠️ Check out the updated version of this endpoint in our SKU Bindings API documentation. If you are doing this integration for the first time, we recommend that you follow the updated documentation.


        Remove a seller''s SKU binding, given the seller ID and the SKU ID in the seller''s store.


        ## Permissions


        Any user or application key must have at least one of the appropriate License Manager resources to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:


        | **Product** | **Category** | **Resource** |

        | --------------- | ----------------- | ----------------- |

        | Catalog | Marketplace | **Seller SKUs** |


        There are no applicable predefined roles for this resource list. You must create a custom role and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see Authentication overview.


        >❗ To prevent integrations from having excessive permissions, consider the best practices for managing app keys when assigning License Manager roles to integrations.'
      operationId: DeleteSKUsellerassociation
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      - name: sellerId
        in: path
        description: ID that identifies the seller in the marketplace. It can be the same as the seller name or a unique number. Check the **Sellers management** section in the Admin to get the correct ID.
        required: true
        style: simple
        schema:
          type: string
          example: '101'
      - name: sellerSkuId
        in: path
        description: SKU ID in the seller's store.
        required: true
        style: simple
        schema:
          type: string
          example: '1'
      responses:
        '200':
          description: OK
      deprecated: false
  /api/catalog_system/pvt/skuseller/changenotification/{sellerId}/{sellerSkuId}:
    post:
      tags:
      - SKU Seller
      summary: VTex Change notification with seller ID and seller SKU ID
      description: '> ⚠️ Check out the updated version of this endpoint in our SKU Bindings API documentation. If you are doing this integration for the first time, we recommend that you follow the updated documentation.


        The seller is responsible for suggesting new SKUs to be sold in the VTEX marketplace and also for informing the marketplace about changes in their SKUs that already exist in the marketplace. Both actions start with a catalog notification, which is made by this request.


        With this notification, the seller is telling the marketplace that something has changed about a specific SKU, like price or inventory, or that this is a new SKU that the seller would like to offer to the marketplace.


        There are two information expected by the marketplace in this request: the `sellerId`, which identifies the seller, and the `sellerSkuId`, which identifies the binding of the seller with the SKU.


        Both information are passed through the request URL. The body of the request should be empty.


        ## Permissions


        Any user or application key must have at least one of the appropriate License Manager resources to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:


        | **Product** | **Category** | **Resource** |

        | --------------- | ----------------- | ----------------- |

        | Catalog | Marketplace | **Seller SKUs** |


        There are no applicable predefined roles for this resource list. You must create a custom role and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see Authentication overview.


        >❗ To prevent integrations from having excessive permissions, consider the best practices for managing app keys when assigning License Manager roles to integrations.'
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      - name: sellerId
        in: path
        description: ID that identifies the seller in the marketplace. It can be the same as the seller name or a unique number. Check the **Sellers management** section in the Admin to get the correct ID.
        required: true
        style: simple
        schema:
          type: string
          example: '101'
      - name: sellerSkuId
        in: path
        description: ID of the binding of the seller with the SKU.
        required: true
        style: simple
        schema:
          type: string
          example: '1'
      responses:
        '204':
          description: No Content
      deprecated: false
      operationId: postApiCatalogSystemPvtSkusellerChangenotificationBySellerIdBySellerSkuId
      x-operation-id-source: derived
  /api/catalog_system/pvt/skuseller/changenotification/{skuId}:
    post:
      tags:
      - SKU Seller
      summary: VTex Change notification with SKU ID
      description: '> ⚠️ Check out the updated version of this endpoint in our SKU Bindings API documentation. If you are doing this integration for the first time, we recommend that you follow the updated documentation.


        The seller is responsible for suggesting new SKUs to be sold in the VTEX marketplace and also for informing the marketplace about changes in their SKUs that already exist in the marketplace. Both actions start with a catalog notification, which is made by this request.


        With this notification, the seller is telling the marketplace that something has changed about a specific SKU, like its name or description, or that this is a new SKU that the seller would like to offer to the marketplace. The body of the request should be empty.


        > ⚠️ Do not use this endpoint for price and inventory changes, because these types of updates should be notified using Marketplace API. For price changes, we recommend using the Notify marketplace of price update endpoint. For inventory changes, use Notify marketplace of inventory update.


        ## Example


        Let''s say your seller has the ID `123` in the marketplace and you want to inform the marketplace that has been a change in the SKU with ID `700`.


        In this case, you would have to replace the `sellerId` parameter with the value `123` and the `skuId` parameter with the value `700`. The URL of the request would be the following.


        ```

        https://{{accountName}}.vtexcommercestable.com.br/api/catalog_system/pvt/skuseller/changenotification/123/700

        ```


        ## Response codes


        The following response codes are possible for this request.


        * **404:** the SKU was not found in the marketplace. The body of the response, in this case, should follow this format: "Seller StockKeepingUnit `{{skuId}}` not found for this seller id `{{sellerId}}`". This means that the seller can now proceed with sending an offer to the marketplace in order to suggest that this SKU is sold there.

        * **200:** the SKU whose ID was informed in the URL already exists in the marketplace and was found. The marketplace can now proceed with a fulfillment simulation in order to get updated information about this SKU''s inventory and price.

        * **429:** Failure due to too many requests.

        * **403:** Failure in the authentication.


        ## Permissions


        Any user or application key must have at least one of the appropriate License Manager resources to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:


        | **Product** | **Category** | **Resource** |

        | --------------- | ----------------- | ----------------- |

        | Catalog | Marketplace | **Seller SKUs** |


        There are no applicable predefined roles for this resource list. You must create a custom role and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see Authentication overview.


        >❗ To prevent integrations from having excessive permissions, consider the best practices for managing app keys when assigning License Manager roles to integrations.'
      operationId: ChangeNotification
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      - name: skuId
        in: path
        description: A string that identifies the SKU in the marketplace. This is the ID that the marketplace will use to look for the SKU whose change the seller wants to inform. If the marketplace finds this ID, it responds with status code 200. Otherwise, it responds with status code 404.
        required: true
        style: simple
        schema:
          type: string
          example: '10'
      responses:
        '200':
          description: OK
        '404':
          description: Not found
          content:
            text/plain:
              schema:
                type: string
              example: Seller StockKeepingUnit `{{skuId}}` not found for this seller id `{{sellerId}}`
        '429':
          description: Too many requests
        '403':
          description: Forbidden
      deprecated: false
components:
  parameters:
    Accept:
      name: Accept
      in: header
      description: HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.
      required: true
      style: simple
      schema:
        type: string
        default: application/json
    Content-Type:
      name: Content-Type
      in: header
      description: Type of the content being sent.
      required: true
      style: simple
      schema:
        type: string
        default: application/json
  securitySchemes:
    appKey:
      type: apiKey
      in: header
      name: X-VTEX-API-AppKey
      description: Unique identifier of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys).
    appToken:
      type: apiKey
      in: header
      name: X-VTEX-API-AppToken
      description: Secret token of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys).
    VtexIdclientAutCookie:
      type: apiKey
      in: header
      name: VtexIdclientAutCookie
      description: '[User token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens), valid for 24 hours.'