MerchantHQ API
GET /2024-09/products
Default

Get the list of products for a merchant.

Query parameters

  • merchant_id string(uuid) Required

    The UUID of the merchant to filter products by

  • q string

    A search query to filter products by title or SKU

  • sku string

    Filter products by exact SKU match

  • page integer

    The page number to retrieve

    Minimum value is 1.

  • per_page integer

    The number of results to return per page

    Minimum value is 1, maximum value is 100.

Responses

  • 200 application/json

    A successful response returning the list of products

    Hide response attributes Show response attributes object
    • links object
      Hide links attributes Show links attributes object
      • first string
      • last string
      • prev string | null
      • next string | null
    • meta object
      Hide meta attributes Show meta attributes object
      • current_page integer
      • from integer | null
      • last_page integer
      • path string
      • per_page integer
      • to integer | null
      • total integer
    • data array[object] Required

      Representation of a product

      Hide data attributes Show data attributes object
      • id string(uuid)

        The UUID of the resource.

      • merchant_id string(uuid)

        The UUID of the merchant that owns this product

      • sku string

        Stock Keeping Unit - unique identifier for the product within the merchant

        Maximum length is 255.

      • title string

        The title or name of the product

      • identifiers array[object]

        Array of product identifiers

        Full representation of a product identifier

        Hide identifiers attributes Show identifiers attributes object
        • id string(uuid)

          The UUID of the resource.

        • product_id string(uuid)

          The UUID of the product this identifier belongs to

        • type string

          The type of identifier

          Values are UPC, EAN, GTIN, or ISBN.

        • value string

          The identifier value

        • created_at string(date-time)

          The date and time the resource was created.

        • updated_at string(date-time)

          The date and time the resource was last updated.

      • main_image_id string | null

        The UUID of the main product image

      • main_image_url string | null

        The URL of the main product image

      • thumbnail_image_id string | null

        The UUID of the thumbnail product image

      • thumbnail_image_url string | null

        The URL of the thumbnail product image

      • created_at string(date-time)

        The date and time the resource was created.

      • updated_at string(date-time)

        The date and time the resource was last updated.
  • 401 application/json

    The request requires user authentication or the user is not authorized to access this resource.

    Hide response attribute Show response attribute object
    • message string
  • 403 application/json

    Forbidden - The user does not have permission to access this resource.

    Hide response attribute Show response attribute object
    • message string Required
  • 404 application/json

    The specified resource was not found

    Hide response attribute Show response attribute object
    • message string
GET /2024-09/products 
curl \
 --request GET 'https://app.merchanthq.com/api/2024-09/products?merchant_id=1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4' \
 --header "Authorization: Bearer $ACCESS_TOKEN"
Response examples (200) 
{
  "links": {
    "first": "https://app.merchanthq.com/api/2024-09/merchants?page=1",
    "last": "https://app.merchanthq.com/api/2024-09/merchants?page=10",
    "prev": "https://app.merchanthq.com/api/2024-09/merchants?page=1",
    "next": "https://app.merchanthq.com/api/2024-09/merchants?page=3"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 10,
    "path": "https://app.merchanthq.com/api/2024-09/merchants",
    "per_page": 10,
    "to": 10,
    "total": 20
  },
  "data": [
    {
      "id": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4",
      "merchant_id": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4",
      "sku": "PROD-001",
      "title": "Blue Widget",
      "identifiers": [
        {
          "id": "1e7f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d4",
          "product_id": "string",
          "type": "UPC",
          "value": "string",
          "created_at": "2025-01-10T10:37:11Z",
          "updated_at": "2025-01-10T10:37:11Z"
        }
      ],
      "main_image_id": "2e8f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d5",
      "main_image_url": "https://example.com/images/2e8f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d5.jpg",
      "thumbnail_image_id": "3e9f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d6",
      "thumbnail_image_url": "https://example.com/images/3e9f0a0f-b5a9-4d1a-a2d5-d0e0c2b1c3d6.jpg",
      "created_at": "2025-01-10T10:37:11Z",
      "updated_at": "2025-01-10T10:37:11Z"
    }
  ]
}
Response examples (401) 
{
  "message": "Unauthorized"
}
Response examples (403) 
{
  "message": "This action is unauthorized."
}
Response examples (404) 
{
  "message": "Not found"
}