List products

What this endpoint does

Find visible products, prices, category membership, and stock without exposing voucher codes.

INFO

Workflow

List products → product ID → product or Store widget

NOTE

List behavior

Empty results keep the same collection shape with empty arrays and zero totals. Use the documented pagination fields for later pages.

Quick start

Use the environment selected by Try it. The example values are synthetic.

Authentication and permission

Send	Permission	Community scope
`Authorization: Bearer <apiKey>`	`store`	Community scope is derived from the key; do not send a community identifier.

Complete examples

No JSON body is sent. Replace each {pathParameter} and use the query parameters documented below.

Success and readback

Branch on: meta.code = PRODUCTS_RETRIEVED

{
  "meta": {
    "status": "success",
    "statusCode": 200,
    "code": "PRODUCTS_RETRIEVED",
    "skip": 0,
    "limit": 20,
    "total": 1
  },
  "message": "List products successfully",
  "data": [
    {
      "_id": "prd_agent_01",
      "name": "Agent Test Voucher",
      "category": {
        "_id": "cat_agent_01",
        "name": "Agent Test Rewards",
        "displayOrder": 10
      },
      "price": 100,
      "stocks": 2
    }
  ]
}

CHECK

Readback

This collection response is the readback. An empty result returns data: [] with skip, limit, and total in meta.

Errors and recovery

Branch on meta.code, never message text.

HTTP	Machine code	What the caller should do	Retry?
400	`VALIDATION_FAILED`	Repair the named request field before retrying.	No, fix first
401	`AUTH_API_KEY_REQUIRED`	Add the Authorization header.	No, fix first
401	`AUTH_API_KEY_INVALID`	Replace or rotate the key.	No, fix first
401	`AUTH_API_KEY_VALIDATION_FAILED`	Authentication could not be completed.	Yes, with backoff
403	`AUTH_PERMISSION_REQUIRED`	Request the store permission; no resource data is returned.	No, fix first
500	`INTERNAL_ERROR`	Retry with exponential backoff and the same request context, then escalate.	Yes, with backoff

Retry safety

TIP

Exact retry

This read is safe to retry with exponential backoff.

Gotchas

Avoid this mistake

Next steps

Read Store product

Read one product or create inventory.

curl --location 'https://api.returning.ai/v1/products?skip=undefined&limit=20&sort=createdAt%3Adesc&fields=name%2Cprice%2Ccategory%2Cstocks&search=keyword%3Apremium&filter=categoryName%3APremium%20Rewards&lang=th&userID=507f1f77bcf86cd799439011' \ --header 'Authorization: Bearer XXXXXX'

{ "meta": { "status": "success", "statusCode": 200, "skip": 0, "limit": 20, "total": 1 }, "message": "Read products success.", "data": [ { "_id": "507f1f77bcf86cd799439031", "communityID": "6502c9e514a3e564c5c09c0a", "name": "Premium Voucher", "description": "<p>Premium access reward.</p>", "image": "https://example.com/images/premium-voucher.png", "price": 100, "category": "Premium Rewards", "stocks": 2, "discountPrice": 90, "isDiscountEnabled": false, "discountStartDate": null, "discountEndDate": null, "userInformation": { "isEnabled": false, "shouldCollectName": false, "shouldCollectPhone": false, "shouldCollectAddress": false }, "shouldPrioritiesExpiringVouchers": false, "shouldDisplayRemainingQuantity": true, "expiringVoucherHighlight": { "isEnabled": false, "duration": 7, "timeframe": "days" }, "isArchived": false, "totalOrders": 0, "redemptionInstructions": "<p>Show this voucher at checkout.</p>", "productPermission": [], "isProductAccessEnabled": false, "purchaseStatusOverride": { "isEnabled": false, "status": null }, "createdAt": "2026-06-09T00:00:00.000Z", "updatedAt": "2026-06-09T00:00:00.000Z" } ] }

What this endpoint does#

Quick start#

Authentication and permission#

Complete examples#

Success and readback#

Errors and recovery#

Retry safety#

Gotchas#

Next steps#

Request

Responses

What this endpoint does

Quick start

Authentication and permission

Complete examples

Success and readback

Errors and recovery

Retry safety

Gotchas

Next steps