Skip to main content
GET
List products by category

๐Ÿ“Œ Endpoint

GET /stores/{storeId}/categories/{categoryId}/products Returns the public (not disabled) products that belong to a category of a store. Products are returned in position order (ascending).

๐Ÿ” Authentication

  • Public route for queries.
  • The store must exist and have an active plan.

๐Ÿงพ Route parameters


โœ… Request example


๐Ÿ”Ž Query params


๐Ÿ”„ Cursor pagination

For large lists (more than ~100 items), prefer cursor pagination instead of page:
  1. Make the first call without cursor.
  2. If hasMore is true, the response includes the nextCursor field.
  3. Send that nextCursor in the cursor parameter of the next request to fetch the next page.
In cursor mode, pagination is returned only with nextCursor, hasMore and limit:
  • cursor and page cannot be used together (400 INVALID_PAGINATION).
  • When there are no products in the category, offset mode (without cursor) returns 404 PRODUCTS_NOT_FOUND, whereas cursor mode returns 200 with products: [], nextCursor: null, and hasMore: false.
  • nextCursor: null with hasMore: false indicate the end of the list (the API responds 200 with an empty array).

๐Ÿ“ฆ Success response (200)

The first call (without cursor) already returns nextCursor and hasMore in the pagination, allowing cursor pagination to start without extra calls.

โš ๏ธ Possible errors

  • 400 INVALID_DATA โ†’ invalid parameter
  • 400 INVALID_PAGINATION_LIMIT โ†’ limit outside the allowed range (1 to 100)
  • 400 INVALID_PAGINATION_PAGE โ†’ invalid page
  • 400 INVALID_PAGINATION_CURSOR โ†’ invalid or malformed cursor
  • 400 INVALID_PAGINATION โ†’ page and cursor used together
  • 401 UNAUTHENTICATED โ†’ could not identify the subscription user
  • 403 NO_ACTIVE_SUBSCRIPTION โ†’ inactive or expired plan
  • 404 STORE_NOT_FOUND โ†’ store not found
  • 404 PRODUCTS_NOT_FOUND โ†’ no products found for the category (returned only in offset mode when total is 0; cursor mode returns 200 with [])
  • 429 RATE_LIMIT_EXCEEDED โ†’ rate limit per minute exceeded
  • 500 INTERNAL_SERVER_ERROR โ†’ internal server error
  • 503 SERVICE_UNAVAILABLE โ†’ service or database unavailable

Path Parameters

storeId
string
required
Required string length: 1 - 50
categoryId
string
required
Required string length: 1 - 50

Query Parameters

page
integer
default:1
Required range: x >= 1
limit
integer
default:20
Required range: 1 <= x <= 100
cursor
string

Opaque cursor from previous page (do not combine with page).

Response

List products by category.

code
string
required
Example:

"PRODUCTS_BY_CATEGORY_FETCHED"

products
object[]
required
pagination
object
required