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",
      "categoryID": "650906d314a3e564c56f3450",
      "category": "Premium Rewards",
      "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
502	`STORE_DEPENDENCY_UNAVAILABLE`	Retry after a short backoff; the Store dependency is unavailable.	Yes, with backoff
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.

Effective response fields

categoryID is canonical and category is its readable name.

redemptionMethodIDs is the raw stored product-owned array; redemptionMethods is the effective ordered read view, including inheritance.

redemptionProductFieldValues contains only values applicable to the effective methods.

Public permission user references are readable usernames only; internal user identifiers are not documented.

An explicit fields projection is authoritative after effective-method and readable-reference enrichment; only selected public fields remain. Selecting categoryID also retains its readable category companion.

{ "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": "Premium Rewards", "price": 100, "stocks": 2, "categoryID": "650906d314a3e564c56f3450", "redemptionMethodIDs": [], "redemptionMethods": [ { "_id": "method_1", "enabled": true, "title": "Email delivery", "description": "Deliver the voucher by email", "icon": "mail", "defaultFields": { "name": true, "phone": false, "address": false }, "fields": [ { "_id": "recipient_email", "name": "Recipient email", "description": "Where the voucher will be delivered", "placeholder": "name@example.com", "type": "text", "required": true, "fieldOptionsMode": "customField", "options": [ { "value": "primary", "label": "Primary email", "isDefault": true } ], "userFieldSource": { "customFieldId": "custom_field_1", "separator": ",", "defaultSelectFirst": true, "userFieldType": "text" }, "displayInDropdown": false } ], "productFields": [ { "id": "field_1", "name": "Amount" } ], "redemptionCondition": { "enabled": true, "title": "Eligibility check", "description": "Validated during redemption", "localizedFieldLabels": { "status": "Eligibility status" } } } ], "redemptionProductFieldValues": { "method_1": { "field_1": "250" } }, "productPermission": [ { "isEnabled": true, "type": "user", "permission": { "roleNames": [ "VIP Member" ], "tagNames": [ "Early Access" ], "usernames": [ "alex" ], "combination": [ { "type": "role", "values": [ "VIP Member" ] } ], "isSelectAll": false } } ] } ] }

What this endpoint does#

Quick start#

Authentication and permission#

Complete examples#

Success and readback#

Errors and recovery#

Retry safety#

Gotchas#

Next steps#

Effective response fields#

Request

Responses

What this endpoint does

Quick start

Authentication and permission

Complete examples

Success and readback

Errors and recovery

Retry safety

Gotchas

Next steps

Effective response fields