StockX Catalog API

openapi: 3.2.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:
    IngestionItemResult:
      properties:
        brand:
          type: string
          description: The brand of the product.
        title:
          type: string
          description: A string that uniquely identifies the name of the product.
        variantId:
          type: string
          description: Unique identifier for the product variant.
      required:
      - brand
      - title
      - variantId
      type: object
      additionalProperties: false
    ProductSizeConversion:
      properties:
        name:
          type:
          - string
          - 'null'
          description: The display name for the size conversion
          example: US M
        type:
          type:
          - string
          - 'null'
          description: The type of the size conversion
          example: us m
      required:
      - name
      - type
      type: object
      additionalProperties: false
    IngestionControllerResponse:
      properties:
        ingestionId:
          type: string
          description: Unique ID used to return the status of an ingestion job.
      required:
      - ingestionId
      type: object
      additionalProperties: false
    IngestionItemRejectionDetails:
      properties:
        reason:
          type: string
      required:
      - reason
      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
    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
          - 'null'
          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'
              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
    Search:
      properties:
        count:
          type: number
          format: double
          description: Total number of items present
          example: 266
        pageSize:
          type: number
          format: double
          description: Total number of items in the current page
          example: 10
        pageNumber:
          type: number
          format: double
          description: Requested page number. Starts at 1.
          example: 1
        hasNextPage:
          type: boolean
          description: Returns true if there are elements in the next page.
          example: true
        products:
          items:
            $ref: '#/components/schemas/SearchProduct'
          type: array
          description: List of products that matched the search term
      required:
      - count
      - pageSize
      - pageNumber
      - hasNextPage
      - products
      type: object
      additionalProperties: false
    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
          - 'null'
          description: The lowest ask for the product variant listed in the market.
          example: '100'
        highestBidAmount:
          type:
          - string
          - 'null'
          description: The highest bid for the product variant listed in the market.
          example: '150'
        sellFasterAmount:
          type:
          - string
          - 'null'
          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
          - 'null'
          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
          - 'null'
          description: The Flex program's lowest ask for the product variant listed in the flex market.
          example: '100'
        standardMarketData:
          properties:
            beatUS:
              type:
              - string
              - 'null'
              description: The price you have to list at, to beat the lowest ask in the US for standard market.
              example: '152'
            earnMore:
              type:
              - string
              - 'null'
              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
              - 'null'
              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
              - 'null'
              description: The highest bid for the product variant listed in the standard market.
              example: '150'
            lowestAsk:
              type:
              - string
              - 'null'
              description: The lowest ask for the product variant listed in the standard market.
              example: '100'
          type: object
          description: The standard market data for the product variant.
        flexMarketData:
          properties:
            beatUS:
              type:
              - string
              - 'null'
              description: The price you have to list at, to beat the lowest ask in the US for flex market.
              example: '152'
            earnMore:
              type:
              - string
              - 'null'
              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 flex market.
              example: '151'
            sellFaster:
              type:
              - string
              - 'null'
              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 flex market, and also includes checks to recommend a competitive price compared to recent global sales.
              example: '150'
            highestBidAmount:
              type:
              - string
              - 'null'
              description: The highest bid for the product variant listed in the Flex market.
              example: '150'
            lowestAsk:
              type:
              - string
              - 'null'
              description: The lowest ask for the product variant listed in the Flex market.
              example: '100'
          type: object
          description: The Flex market data for the product variant.
        directMarketData:
          properties:
            beatUS:
              type:
              - string
              - 'null'
              description: The price you have to list at, to beat the lowest ask in the US for direct market.
              example: '152'
            earnMore:
              type:
              - string
              - 'null'
              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 direct market.
              example: '151'
            sellFaster:
              type:
              - string
              - 'null'
              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 direct market, and also includes checks to recommend a competitive price compared to recent global sales.
              example: '150'
            highestBidAmount:
              type:
              - string
              - 'null'
              description: The highest bid for the product variant listed in the Direct market.
              example: '150'
            lowestAsk:
              type:
              - string
              - 'null'
              description: The lowest ask for the product variant listed in the Direct market.
              example: '100'
          type: object
          description: The market data for the product variant in the Direct market.
      required:
      - productId
      - variantId
      - currencyCode
      type: object
      additionalProperties: false
    CatalogIngestionInput:
      properties:
        items:
          items:
            anyOf:
            - $ref: '#/components/schemas/IngestionSneakersShoesRequestInput'
            - $ref: '#/components/schemas/IngestionApparelAccessoriesRequestInput'
            - $ref: '#/components/schemas/IngestionCollectiblesRequestInput'
            - $ref: '#/components/schemas/IngestionElectronicsRequestInput'
            - $ref: '#/components/schemas/IngestionTradingCardsRequestInput'
          type: array
          description: An array of items associated with the ingestion job.
      required:
      - items
      type: object
      additionalProperties: false
    INGESTION_ITEM_STATUS:
      enum:
      - In Review
      - Completed
      - Rejected
      type: string
    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 

# --- 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