VTEX Manage Suggestions API

openapi: 3.2.0
info:
  title: VTex Suggestions Manage Suggestions API
  description: "\nThe **Marketplace API** enables marketplaces and sellers hosted on VTEX to perform their collaborative operations.  \n\n>⚠️ The marketplace must [create an appKey and appToken](https://developers.vtex.com/docs/guides/getting-started-authentication) for each non-VTEX seller that will use this API.\n\n## Index\n\n### Notification\n\nEndpoints used by sellers to notify marketplaces that the price or inventory language has changed for one of their SKUs.\n\n`POST` [Notify marketplace of price update](https://developers.vtex.com/docs/api-reference/marketplace-apis#post-/notificator/-sellerId-/changenotification/-skuId-/price)\n\n`POST` [Notify marketplace of inventory update](https://developers.vtex.com/docs/api-reference/marketplace-apis#post-/notificator/-sellerId-/changenotification/-skuId-/inventory)\n\n\n### Suggestions\n\n#### Get Suggestions\n\nSearch and filter all suggestions using specific criteria.\n\n`GET` [Get all SKU Suggestions](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#get-/suggestions)\n\n`GET` [Get SKU Suggestion by ID](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#get-/suggestions/-sellerId-/-sellerSkuId-)\n\n\n#### Manage Suggestions\n\nSend or delete SKU suggestions from the seller to marketplace.\n\n`PUT` [Send SKU Suggestion](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#put-/suggestions/-sellerId-/-sellerSkuId-)\n\n`DELETE` [Delete SKU Suggestion](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#delete-/suggestions/-sellerId-/-sellerSkuId-)\n\n\n#### Get Versions\n\nSearch and filter all versions of suggestions, using specific criteria.\n\n`GET` [Get all versions](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#get-/suggestions/-sellerId-/-sellerskuid-/versions)\n\n`GET` [Get version by ID](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#get-/suggestions/-sellerId-/-sellerskuid-/versions/-version-)\n\n\n#### Match Received SKUs\n\nMatch SKU suggestions received in the marketplace.\n\n`PUT` [Match Received SKUs individually](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#put-/suggestions/-sellerId-/-sellerskuid-/versions/-version-/matches/-matchid-)\n\n`PUT` [Match Multiple Received SKUs](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#put-/suggestions/matches/action/-actionName-)\n\n\n#### SKU Approval Settings\n\nAllows marketplaces to configure rules for automatically and manually approving SKUs received from sellers.\n\n`GET`[Get autoApprove Status in Account Settings](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#get-/suggestions/configuration/autoapproval/toggle)  \n\n`PUT`[Activate autoApprove in Marketplace's Account](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#put-/suggestions/configuration/autoapproval/toggle)  \n\n`GET`[Get Account's Approval Settings](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#get-/suggestions/configuration)\n\n`PUT`[Save Account's Approval Settings](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#put-/suggestions/configuration)\n\n`GET`[Get Seller's Approval Settings](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#get-/suggestions/configuration/seller/-sellerId-)\n\n`PUT`[Save Seller's Approval Settings](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#put-/suggestions/configuration/seller/-sellerId-)\n\n`PUT`[Activate autoApprove Setting for a Seller](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#put-/suggestions/configuration/autoapproval/toggle/seller/-sellerId-)   \n\n\n### Matched Offers\n\nOffers are seller products and SKUs that were sent to the marketplace, and already have their price and inventory level configured.\n\n`GET`[Get Matched Offers List](https://developers.vtex.com/docs/api-reference/marketplace-apis#get-/offer-manager/pvt/offers)\n\n`GET`[Get Matched Offer's Data by SKU ID](https://developers.vtex.com/docs/api-reference/marketplace-apis#get-/offer-manager/pvt/product/-productId-/sku/-skuId-)  \n\n`GET`[Get Matched Offer's Data by Product ID](https://developers.vtex.com/docs/api-reference/marketplace-apis#get-/offer-manager/pvt/product/-productId-)\n"
  contact: {}
  version: '1.0'
servers:
- url: https://api.vtex.com/{accountName}
  description: Suggestions Server URL.
  variables:
    accountName:
      description: Name of the VTEX account. Used as part of the URL.
      default: apiexamples
tags:
- name: Manage Suggestions
paths:
  /suggestions/{sellerId}/{sellerSkuId}:
    put:
      tags:
      - Manage Suggestions
      summary: VTex Send SKU Suggestion
      description: 'This request is used by the seller when it wants to suggest that one of their SKUs is sold in the marketplace.


        Before using this request, the seller should always use the [Change Notification](https://developers.vtex.com/vtex-rest-api/reference/catalog-api-get-seller-sku-notification) request in order to check if the SKU already exists in the marketplace. If it doesn''t, then this is the next call in the SKU integration flow.


        In the Send Suggestion request, the seller must send information about the SKU, such as the product and SKU name, the seller ID, and the image URL. All parameters are explained below. '
      operationId: SaveSuggestion
      parameters:
      - name: accountName
        in: path
        required: true
        description: Name of the VTEX account to which the seller wants to suggest a new SKU. It is used as part of the request URL.
        schema:
          type: string
          default: apiexamples
      - 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
          example: application/vnd.vtex.suggestion.v0+json
          default: application/json
      - name: Content-Type
        in: header
        description: Describes the type of the content being sent.
        required: true
        style: simple
        schema:
          type: string
          default: application/json
      - name: sellerId
        in: path
        description: A string that identifies the seller in the marketplace. This ID must be created by the marketplace and informed to the seller before the integration is built.
        required: true
        style: simple
        schema:
          type: string
          default: seller123
      - name: sellerSkuId
        in: path
        description: A string that identifies the SKU in the seller. This is the ID that the marketplace will use for future references to this SKU, such as price and inventory notifications.
        required: true
        style: simple
        schema:
          type: string
          default: '1234'
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SaveSuggestionRequest'
            example:
              ProductId: '321'
              ProductName: Product sample
              NameComplete: Complete product name
              ProductDescription: sample
              BrandName: Brand 1
              SkuName: Sku sample
              SellerId: string
              Height: 1
              Width: 1
              Length: 1
              Weight: 1
              Updated: null
              RefId: REFID123
              SellerStockKeepingUnitId: 567
              CategoryFullPath: Category 1
              Images:
              - imageName: Principal
                imageUrl: https://i.pinimg.com/originals/2d/96/4a/2d964a6bf37d9224d0615dc85fccdd62.jpg
              ProductSpecifications:
              - fieldName: Fabric
                fieldValues:
                - Cotton
                - Velvet
              SkuSpecifications:
              - fieldName: Color
                fieldValues:
                - Red
                - Blue
              EAN: EAN123
              MeasurementUnit: un
              UnitMultiplier: 1
              AvailableQuantity: 111
              Pricing:
                Currency: BRL
                SalePrice: 399
                CurrencySymbol: R$
        required: true
      responses:
        '200':
          description: OK
          headers: {}
      deprecated: false
    delete:
      tags:
      - Manage Suggestions
      summary: VTex Delete SKU Suggestion
      description: This endpoint deletes a chosen SKU suggestion. Only one SKU should be deleted per request. This request cannot be undone. A workaround to revert its action, is to send the suggestion again, through the Send Suggestion API.
      operationId: DeleteSuggestion
      parameters:
      - name: accountName
        in: path
        required: true
        description: Name of the VTEX account. Used as part of the URL.
        schema:
          type: string
          default: apiexamples
      - 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
      - name: Content-Type
        in: header
        description: Describes the type of the content being sent.
        required: true
        style: simple
        schema:
          type: string
          default: application/json
      - name: sellerId
        in: path
        description: A string that identifies the seller in the marketplace. This ID must be created by the marketplace and informed to the seller before the integration is built.
        required: true
        style: simple
        schema:
          type: string
          default: seller123
      - name: sellerSkuId
        in: path
        description: A string that identifies the SKU in the marketplace. This is the ID that the marketplace will use for future references to this SKU, such as price and inventory notifications.
        required: true
        style: simple
        schema:
          type: string
          default: '1234'
      responses:
        '200':
          description: OK
          headers: {}
      deprecated: false
components:
  schemas:
    Image:
      title: Image
      required:
      - imageName
      - imageUrl
      type: object
      properties:
        imageName:
          type: string
          description: Name of the SKU image.
        imageUrl:
          type: string
          description: URL of the SKU image. The image must be sent through `https` protocol, otherwise it will not be rendered in VTEX Admin.
          default: https://imageurl.example
      example:
        imageName: Principal
        imageUrl: https://i.pinimg.com/originals/2d/96/4a/2d964a6bf37d9224d0615dc85fccdd62.jpg
    ProductSpecification:
      title: Product Specification
      type: object
      properties:
        fieldName:
          type: string
          description: 'Name of the product specification field. Example: ''Fabric''.'
          default: Fabric type
        fieldValues:
          type: array
          description: 'Value of the product specification field. Example: ''Cotton''.'
          items:
            type: string
            default: Cotton
            description: Value of the product specification field.
      example:
        fieldName: Color
        fieldValues:
        - Red
        - Green
    SkuSpecification:
      title: skuSpecification
      type: object
      properties:
        fieldName:
          type: string
          description: 'Name of the SKU specification field. Example: ''Color''.'
          default: color
        fieldValues:
          type: array
          items:
            type: string
            default: Red
            description: Value of the SKU specification field.
          default:
          - Red
          description: 'Array with values of the SKU specification field. Example: ''Red''.'
      default:
        fieldName: Color
        fieldValues:
        - Red
        - Green
    SaveSuggestionRequest:
      title: SaveSuggestionRequest
      required:
      - ProductName
      - ProductId
      - ProductDescription
      - BrandName
      - SkuName
      - SellerId
      - Height
      - Width
      - Length
      - Weight
      - Updated
      - RefId
      - CategoryFullPath
      - Images
      - EAN
      - AvailableQuantity
      - Pricing
      type: object
      properties:
        ProductName:
          type: string
          description: Name of the suggested product. This field has a limit of 150 characters.
          default: ''
        ProductId:
          type: string
          description: Product ID in seller's account.
          default: '1234'
        ProductDescription:
          type: string
          description: Product Description containing the main information about the product (not the SKU).
        BrandName:
          type: string
          description: Name of the brand to which this SKU belongs. It must match the brand created in the marketplace.
        SkuName:
          type: string
          description: Name of the suggested SKU.
        SellerId:
          type: string
          description: ID of the seller in the marketplace. This ID must be created by the marketplace and informed to the seller before the integration is built.
          default: '1'
        Height:
          type: integer
          format: decimal
          description: Height of the SKU.
          default: 10
        Width:
          type: integer
          format: decimal
          description: Width of the SKU.
          default: 10
        Length:
          type: integer
          format: decimal
          description: Length of the SKU.
          default: 10
        Weight:
          type: integer
          format: decimal
          description: Weight of the SKU in grams.
          default: 100
        RefId:
          type: string
          description: SKU reference code. Mandotory if the EAN is not informed.
          default: REF10
        EAN:
          type: string
          description: SKU reference code. Mandatory if the RefId is not informed.
          default: EAN10
        SellerStockKeepingUnitId:
          type: integer
          format: int32
          description: ID of the SKU registered in the seller.
        CategoryFullPath:
          type: string
          description: 'Full path to the SKU''s category. It should be written as {department}/{category}. For example: if the department is **Appliances** and the category is **Oven**, the full path should be ''Appliances/Oven''.'
        SkuSpecifications:
          type: array
          items:
            $ref: '#/components/schemas/SkuSpecification'
          description: Array containing the names and values of the SKU specifications.
        ProductSpecifications:
          type: array
          items:
            $ref: '#/components/schemas/ProductSpecification'
          description: Array containing the names and values of the product specifications.
        Images:
          type: array
          items:
            $ref: '#/components/schemas/Image'
          description: Array containing the URLs and names the SKU images.
        MeasurementUnit:
          type: string
          description: Measurement unit that should be used for this SKU. If this information doesn't apply, you should use the default value `un`.
        UnitMultiplier:
          type: integer
          format: int32
          description: Unit multiplier for this SKU. If this information doesn't apply, you should use the default value `1`.
        AvailableQuantity:
          type: integer
          format: int32
          description: ''
        Pricing:
          type: object
          properties:
            Currency:
              type: string
            SalePrice:
              type: integer
              format: int32
            CurrencySymbol:
              type: string
          description: ''
      default:
        ProductId: '321'
        ProductName: Product sample
        NameComplete: My complete product name?
        ProductDescription: sample
        BrandName: Brand 1
        SkuName: Sku sample
        SellerId: '123'
        Height: 1
        Width: 1
        Length: 1
        Weight: 1
        Updated: null
        RefId: REFID123
        SellerStockKeepingUnitId: 567
        CategoryFullPath: Category 1
        Images:
        - imageName: Principal
          imageUrl: https://i.pinimg.com/originals/2d/96/4a/2d964a6bf37d9224d0615dc85fccdd62.jpg
        ProductSpecifications:
        - fieldName: prodspec1
          fieldValues:
          - value1
          - value2
        SkuSpecifications:
        - fieldName: skuspec1
          fieldValues:
          - value1
          - value2
        EAN: EAN123
        MeasurementUnit: un
        UnitMultiplier: 1
        AvailableQuantity: 111
        Pricing:
          Currency: BRL
          SalePrice: 399
          CurrencySymbol: R$