StockX Catalog API

openapi: 3.0.0
info:
  title: StockX Public Batch Catalog API
  version: 2.0.0
  description: Manage StockX seller account using APIs
  license:
    name: MIT
  contact: {}
servers:
- url: https://api.stockx.com/v2
tags:
- name: Catalog
  description: The StockX Catalog API provides a means for partners to search for catalog data, and request products to be added. Partners can search our Catalog to get StockX product and variant IDs for various purposes. Access to the Catalog Ingestion API is approved on a request-by-request basis.
paths:
  /catalog/ingestion:
    post:
      operationId: Ingestion
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngestionControllerResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
      description: <b>Seamlessly Integrate Catalog Data into Our Platform.</b><br>To create an ingestion job, you need to provide a set of catalog attributes. This API is asynchronous and will return an IngestionID that will require polling.
      summary: Post - Create a Catalog Ingestion Job (Beta)
      tags:
      - Catalog
      security:
      - api_key: []
        jwt: []
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/CatalogIngestionInput'
              - {}
  /catalog/ingestion/{ingestionId}:
    get:
      operationId: IngestionItems
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetIngestionItemsReponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
      description: <b>Monitor Your Data Integration Status.</b><br>Once you create an ingestion job successfully, you need to poll the get catalog ingestion API to track the progress, whether the entire job or individual updates.
      summary: Get - Catalog Ingestion Status (Beta)
      tags:
      - Catalog
      security:
      - api_key: []
        jwt: []
      parameters:
      - description: Unique ID used to return the status of an ingestion job.
        in: path
        name: ingestionId
        required: true
        schema:
          type: string
      - description: The status of the ingestion job. In review, Completed, Rejected.
        in: query
        name: status
        required: false
        schema:
          type: string
  /catalog/products/{productId}:
    get:
      operationId: GetProduct
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
      description: Get product details API allows you to fetch details for a single product
      summary: Get single product
      tags:
      - Catalog
      security:
      - api_key: []
        jwt: []
      parameters:
      - description: Unique identifier for a product
        in: path
        name: productId
        required: true
        schema:
          type: string
  /catalog/products/{productId}/variants/{variantId}:
    get:
      operationId: GetVariant
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductVariantDetails'
        '400':
          description: Variant does not belong to the product.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
      description: 'Get variant details API allows you to fetch the details of a single variant for a given product.

        If the product id doesn''t contain the specified variant, a validation error will be returned.'
      summary: Get single product variant
      tags:
      - Catalog
      security:
      - api_key: []
        jwt: []
      parameters:
      - description: Unique identifier for a product
        in: path
        name: productId
        required: true
        schema:
          type: string
      - description: Unique identifier for a products variant
        in: path
        name: variantId
        required: true
        schema:
          type: string
  /catalog/products/{productId}/variants:
    get:
      operationId: GetVariants
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ProductVariant'
                type: array
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
      description: Get product variants API allows you to get all the different variants of a given product.
      summary: Get all product variants
      tags:
      - Catalog
      security:
      - api_key: []
        jwt: []
      parameters:
      - description: Unique identifier for a product
        in: path
        name: productId
        required: true
        schema:
          type: string
  /catalog/products/{productId}/variants/{variantId}/market-data:
    get:
      operationId: GetVariantMarketData
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VariantMarketDataResponse'
        '400':
          description: Variant does not belong to the product.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
      description: 'Get Market Data API allows you to obtain basic market data - the highest Bid and lowest Ask amount for a given variant.

        If the product id doesn''t contain the specified variant, a validation error will be returned.<br/>

        <b>Note:</b>

        <ul><li>We have deprecated the country param as the market data will now be based on your market.</li>

        <li>Based on your region, the response object may vary.</li>

        <li>Undercut protection is disabled. The system may automatically set a price (beat US) just below your own, even if you''re already the lowest, because it doesn''t consider your current ''Ask'' price.</li></ul>'
      summary: Get market data for a variant
      tags:
      - Catalog
      security:
      - api_key: []
        jwt: []
      parameters:
      - description: Unique identifier for a product
        in: path
        name: productId
        required: true
        schema:
          type: string
      - description: Unique identifier for a products variant
        in: path
        name: variantId
        required: true
        schema:
          type: string
      - description: 'The currency code this product is being listed in.<br><br>Available values: "AUD", "CAD", "CHF", "EUR", "GBP", "HKD", "JPY", "KRW", "MXN", "NZD", "SGD", "USD"'
        in: query
        name: currencyCode
        required: false
        schema:
          $ref: '#/components/schemas/CurrencyCode'
      - description: ISO Alpha-2 code representing the country you need the market data for. If not provided, will default to your country.
        in: query
        name: country
        required: false
        schema:
          type: string
        deprecated: true
  /catalog/products/{productId}/market-data:
    get:
      operationId: GetProductMarketData
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/VariantMarketDataResponse'
                type: array
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
      description: 'Get Market Data API allows you to obtain basic market data - the highest Bid and lowest Ask amount for all variants of given product.

        You may notice discrepancies in the values for sellFasterAmount and earnMoreAmount between this and the ‘Get market data for a variant` API. This is because this API does not take into account any live asks you currently have for each individual variant, while the ''Get market data for a variant’ API does.<br/>

        <b>Note:</b>

        <li>Based on your region, the response object may vary.</li>

        <li>Undercut protection is disabled. The system may automatically set a price (beat US) just below your own, even if you''re already the lowest, because it doesn''t consider your current ''Ask'' price.</li></ul>'
      summary: Get market data for a product
      tags:
      - Catalog
      security:
      - api_key: []
        jwt: []
      parameters:
      - description: Unique identifier for a product
        in: path
        name: productId
        required: true
        schema:
          type: string
      - description: 'The currency code this product is being listed in.<br><br>Available values: "AUD", "CAD", "CHF", "EUR", "GBP", "HKD", "JPY", "KRW", "MXN", "NZD", "SGD", "USD"'
        in: query
        name: currencyCode
        required: false
        schema:
          $ref: '#/components/schemas/CurrencyCode'
  /catalog/products/variants/gtins/{gtin}:
    get:
      operationId: GetVariantsByGtin
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductVariantDetails'
        '400':
          description: Invalid GTIN
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
      description: 'Fetches details for a single product variant using its GTIN (Global Trade Item Number).

        If the gtin id is invalid, a validation error will be thrown.'
      summary: Retrieve product variant details by GTIN
      tags:
      - Catalog
      security:
      - api_key: []
        jwt: []
      parameters:
      - description: (Global Trade Item Number ) Unique identifier for a product variant
        in: path
        name: gtin
        required: true
        schema:
          type: string
        example: 194817794556
  /catalog/search:
    get:
      operationId: Search
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Search'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
      description: 'Search catalog API allows you to search the StockX catalog via freeform text, GTIN (UPC, EAN, ITF-14) or styleId.

        The output is a paginated list of products that match the search term provided in the API call.'
      summary: Search catalog
      tags:
      - Catalog
      security:
      - api_key: []
        jwt: []
      parameters:
      - description: Specifies a keyword, GTIN (UPC, EAN, ITF-14) or styleId string to search for products
        in: query
        name: query
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 100
        examples:
          Example 1:
            value: nike
          Example 2:
            value: '194817794556'
      - description: Requested page number. By default, the page number starts at 1.
        in: query
        name: pageNumber
        required: false
        schema:
          format: int32
          type: integer
          minimum: 1
        example: 1
      - description: The number of products to return. By default, the page size starts at 1.
        in: query
        name: pageSize
        required: false
        schema:
          format: int32
          type: integer
          minimum: 1
          maximum: 50
        example: 10
components:
  schemas:
    SearchProduct:
      description: Product information returned in search results
      properties:
        productId:
          type: string
          description: Unique identifier for a product
          example: bf364c53-eb77-4522-955c-6a6ce952cc6f
        urlKey:
          type: string
          description: The product name
          example: purple-hand-bag-leather
        styleId:
          type: string
          nullable: true
          description: ID of product style
          example: BY9109
        productType:
          type: string
          description: The type of product categories that are available on StockX
          example: handbags
        title:
          type: string
          nullable: true
          description: A string that uniquely identifies the product name.
          example: Gucci Duchessa Boston Bag
        brand:
          type: string
          nullable: true
          description: Brand of the product
          example: Nike
        productAttributes:
          properties:
            gender:
              type: string
              nullable: true
              description: Gender targeted product
              example: women
            season:
              type: string
              nullable: true
              description: The season the product was released
              example: SS21
            releaseDate:
              type: string
              nullable: true
              description: The date the product was released
              example: '2017-09-14'
            retailPrice:
              type: number
              format: double
              nullable: true
              description: The retail price of the product.
              example: 456
            colorway:
              type: string
              nullable: true
              description: The combinations of colors in which the product is designed
              example: String/Black-Villain Red-Neptune Green
            color:
              type: string
              nullable: true
              description: Color of product
              example: purple
          required:
          - gender
          - season
          - releaseDate
          - retailPrice
          - colorway
          - color
          type: object
          description: Object containing the attributes of the product.
      required:
      - productId
      - urlKey
      - styleId
      - productType
      - title
      - brand
      - productAttributes
      type: object
      additionalProperties: false
    INGESTION_ITEM_STATUS:
      enum:
      - In Review
      - Completed
      - Rejected
      type: string
    GetIngestionItemsReponse:
      properties:
        items:
          items:
            $ref: '#/components/schemas/GetIngestionItem'
          type: array
      required:
      - items
      type: object
      additionalProperties: false
    VariantSizeConversion:
      properties:
        size:
          type: string
          nullable: true
          description: The size of this size conversion
          example: '5'
        type:
          type: string
          nullable: true
          description: The type of the size conversion/chart
          example: us m
      required:
      - size
      - type
      type: object
      additionalProperties: false
    CurrencyCode:
      description: Currency codes we support at StockX
      enum:
      - AUD
      - BRL
      - CAD
      - CHF
      - CLP
      - CNY
      - DKK
      - EUR
      - GBP
      - HKD
      - HUF
      - IDR
      - ILS
      - JPY
      - KRW
      - KWD
      - MOP
      - MXN
      - MYR
      - NOK
      - NZD
      - PEN
      - PHP
      - PLN
      - SEK
      - SGD
      - THB
      - TWD
      - USD
      - VND
      type: string
    ProductVariant:
      description: Variant information
      properties:
        productId:
          type: string
          description: Unique identifier for a product
          example: bf364c53-eb77-4522-955c-6a6ce952cc6f
        variantId:
          type: string
          description: Unique identifier for a products variant
          example: 586c3334-4dac-4ee0-bce3-eea845581a08
        variantName:
          type: string
          description: SKU of the variant
          example: Auston-Matthews-2016-Upper-Deck-Series-1-Young-Guns-Rookie-201:0
        variantValue:
          type: string
          nullable: true
          description: Variant's value
          example: PSA 10
        sizeChart:
          properties:
            availableConversions:
              items:
                $ref: '#/components/schemas/VariantSizeConversion'
              type: array
              description: The available size conversions for this variant
            defaultConversion:
              allOf:
              - $ref: '#/components/schemas/VariantSizeConversion'
              nullable: true
              description: The default sizing information for this variant
          required:
          - availableConversions
          - defaultConversion
          type: object
          description: Size chart related information for this variant
        gtins:
          items:
            $ref: '#/components/schemas/VariantGtinDetails'
          type: array
          description: The GTINs associated with this variant
        isFlexEligible:
          type: boolean
          description: Indicates if the variant is eligible for flex fulfillment
          example: true
        isDirectEligible:
          type: boolean
          description: Indicates if the variant is eligible for direct fulfillment
          example: false
      required:
      - productId
      - variantId
      - variantName
      - variantValue
      - sizeChart
      type: object
      additionalProperties: false
    IngestionSneakersShoesRequestInput:
      properties:
        category:
          $ref: '#/components/schemas/PRODUCT_CATEGORIES'
          description: 'A string that specifies product category. Valid values: "sneakers, shoes, apparel, accessories, collectibles, electronics, trading cards"'
          example: shoes
        productTitle:
          type: string
          description: A string that uniquely identifies the name of the product.
          example: Jordan 4 retro
        brand:
          type: string
          description: The brand of the product.
        productImages:
          items:
            type: string
          type: array
          description: Public facing links to the products image.
        variants:
          items:
            type: string
          type: array
          description: The product variants available to sell. For example, for sneakers, each different size is a different variant or for electronics like iPhone, each different storage capacity is a different variant.
        retailPrice:
          type: string
          description: The products retail price.
        releaseDate:
          type: string
          description: The products release date.
        countryOfOrigin:
          type: string
          description: The country in which the product was manufactured in ISO Alpha 2 Format.
          example: US
        partnerProductId:
          type: string
          description: An external ID that partners will use to reference an internal StockX catalog item if approved. Note that this is the higher level product id, not the variantId.
        tags:
          items:
            type: string
          type: array
          description: A list of attributes or short descriptors associated with the product.
        colorway:
          type: string
          description: The combinations of colors in which the product is designed. Ex VIOLET ORE/MEDIUM ASH-BLACK-MUSLIN-BURGUNDY CRUSH.
        gtin:
          type: string
          description: The products global trade item number. Length must be 8, 12, 13, 14 or 18.
        gender:
          type: string
          description: The products targeted gender.
        styleCode:
          type: string
          description: The Style Code for the product  @example "M990BK5"
        productDescription:
          type: string
          description: Open text field used for describing the product to the customer.
        dimensions:
          type: string
          description: A string of the dimensions of the product. @example "2/"x4/"x6/""
        weight:
          type: string
          description: The weight of the product.
        material:
          type: string
          description: Brand listed materials.
        productURL:
          type: string
          description: Official third party product URL.
      required:
      - category
      - productTitle
      - brand
      - productImages
      - variants
      - retailPrice
      - releaseDate
      - countryOfOrigin
      - colorway
      - gtin
      - gender
      - styleCode
      type: object
      additionalProperties: false
    ProductCode:
      properties:
        code:
          type: string
          description: Unique code that identifies the product.
          example: Y0133892
        name:
          $ref: '#/components/schemas/PRODUCT_CODE_NAME'
          description: The type of product code
          example: serial number
      required:
      - code
      - name
      type: object
      additionalProperties: false
    IngestionCollectiblesRequestInput:
      properties:
        category:
          $ref: '#/components/schemas/PRODUCT_CATEGORIES'
          description: 'A string that specifies product category. Valid values: "sneakers, shoes, apparel, accessories, collectibles, electronics, trading cards"'
          example: shoes
        productTitle:
          type: string
          description: A string that uniquely identifies the name of the product.
          example: Jordan 4 retro
        brand:
          type: string
          description: The brand of the product.
        productImages:
          items:
            type: string
          type: array
          description: Public facing links to the products image.
        variants:
          items:
            type: string
          type: array
          description: The product variants available to sell. For example, for sneakers, each different size is a different variant or for electronics like iPhone, each different storage capacity is a different variant.
        retailPrice:
          type: string
          description: The products retail price.
        releaseDate:
          type: string
          description: The products release date.
        countryOfOrigin:
          type: string
          description: The country in which the product was manufactured in ISO Alpha 2 Format.
          example: US
        partnerProductId:
          type: string
          description: An external ID that partners will use to reference an internal StockX catalog item if approved. Note that this is the higher level product id, not the variantId.
        tags:
          items:
            type: string
          type: array
          description: A list of attributes or short descriptors associated with the product.
        colorway:
          type: string
          description: The combinations of colors in which the product is designed.
          example: VIOLET ORE/MEDIUM ASH-BLACK-MUSLIN-BURGUNDY CRUSH
        styleCode:
          type: string
          description: The Style Code for the product  @example "M990BK5"
        productDescription:
          type: string
          description: Open text field used for describing the product to the customer.
        dimensions:
          type: string
          description: A string of the dimensions of the product.
        weight:
          type: string
          description: The weight of the product.
        productURL:
          type: string
          description: Official third party product URL.
        productCode:
          $ref: '#/components/schemas/ProductCode'
          description: An object containing Unique code that identifies the product and the type of the code
      required:
      - category
      - productTitle
      - brand
      - productImages
      - variants
      - retailPrice
      - releaseDate
      - countryOfOrigin
      type: object
      additionalProperties: false
    PublicApiError:
      properties:
        statusCode:
          $ref: '#/components/schemas/HttpStatusCodeLiteral'
          description: The error status code
          example: 400
        message:
          type: string
          description: The error message
          example: The request did not succeed 😭
      required:
      - statusCode
      - message
      type: object
      additionalProperties: false
    HttpStatusCodeLiteral:
      type: number
      enum:
      - 100
      - 101
      - 102
      - 200
      - 201
      - 202
      - 203
      - 204
      - 205
      - 206
      - 207
      - 208
      - 226
      - 300
      - 301
      - 302
      - 303
      - 304
      - 305
      - 307
      - 308
      - 400
      - 401
      - 402
      - 403
      - 404
      - 405
      - 406
      - 407
      - 408
      - 409
      - 410
      - 411
      - 412
      - 413
      - 414
      - 415
      - 416
      - 417
      - 418
      - 422
      - 423
      - 424
      - 426
      - 428
      - 429
      - 431
      - 451
      - 500
      - 501
      - 502
      - 503
      - 504
      - 505
      - 506
      - 507
      - 508
      - 510
      - 511
    VariantMarketDataResponse:
      properties:
        productId:
          type: string
          description: Unique identifier for this product
          example: 35d76ac8-a112-4d75-b44f-c8ef04a87c93
        variantId:
          type: string
          description: Unique identifier for this product variant
          example: 35d76ac8-a112-4d75-b44f-c8ef04a87c93
        currencyCode:
          type: string
          description: 'The currency code. If not provided, it will default to USD.  Only valid currencies supported on stockx.com are supported via API.<br><br>Available values: "AUD", "CAD", "CHF", "EUR", "GBP", "HKD", "JPY", "KRW", "MXN", "NZD", "SGD", "USD"'
          example: USD
        lowestAskAmount:
          type: string
          nullable: true
          description: The lowest ask for the product variant listed in the market.
          example: '100'
        highestBidAmount:
          type: string
          nullable: true
          description: The highest bid for the product variant listed in the market.
          example: '150'
        sellFasterAmount:
          type: string
          nullable: true
          description: The price you have to list at, inclusive of duties and taxes, to become the lowest Ask to buyers in the United States, and also includes checks to recommend a competitive price compared to recent global sales.
          example: '150'
        earnMoreAmount:
          type: string
          nullable: true
          description: The price you have to list at, inclusive of duties and taxes, that maximizes your earnings by staying competitive with recent global sales.
          example: '151'
        flexLowestAskAmount:
          type: string
          nullable: true
          description: The Flex program's lowest ask for the product variant listed in the flex market.
          example: '100'
        standardMarketData:
          properties:
            beatUS:
              type: string
              nullable: true
              description: The price you have to list at, to beat the lowest ask in the US for standard market.
              example: '152'
            earnMore:
              type: string
              nullable: true
              description: The price you have to list at, inclusive of duties and taxes, that maximizes your earnings by staying competitive with recent global sales in standard market.
              example: '151'
            sellFaster:
              type: string
              nullable: true
              description: The price you have to list at, inclusive of duties and taxes, to become the lowest Ask to buyers in the United States for standard market, and also includes checks to recommend a competitive price compared to recent global sales.
              example: '150'
            highestBidAmount:
              type: string
              nullable: true
              description: The highest bid for the product variant listed in the standard market.
              example: '150'
            lowestAsk:
              type: string
              nullable: true
              description: The lowest ask for the product variant listed in the standard market.
              example: '100'
          type: object
          description: The standard market data for the p

# --- truncated at 32 KB (54 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/stockx/refs/heads/main/openapi/stockx-catalog-api-openapi.yml