Read product
GET
https://sgtr-api.returning.ai/v1/products/{productID}
Store / Catalog
What this endpoint does
INFO
Quick start
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
{pathParameter} and use the query parameters documented below.Success and readback
meta.code = PRODUCT_RETRIEVED{
"meta": {
"status": "success",
"statusCode": 200,
"code": "PRODUCT_RETRIEVED"
},
"message": "Read product successfully",
"data": {
"_id": "prd_agent_01",
"name": "Agent Test Voucher",
"categoryID": "650906d314a3e564c56f3450",
"category": "Premium Rewards",
"price": 100,
"stocks": 2
}
}CHECK
Errors and recovery
meta.code, never message text.| HTTP | Machine code | What the caller should do | Retry? |
|---|---|---|---|
| 400 | VALIDATION_FAILED | Repair the path ID. | 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 |
| 404 | STORE_RESOURCE_NOT_FOUND | Refresh the product list. | After refreshing the ID |
| 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
Gotchas
Next steps
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.fields projection is authoritative after effective-method and readable-reference enrichment; only selected public fields remain. Selecting categoryID also retains its readable category companion.Request
Path Params
Query Params
Header Params
Responses
Request Request Example
Shell
JavaScript
Java
Swift
curl --location 'https://sgtr-api.returning.ai/v1/products/prd_agent_01?fields=name%2CdisplayOrder&lang=en' \
--header 'Authorization: Bearer XXXXXX'Response Response Example
200 - Success Example
{
"meta": {
"status": "success",
"statusCode": 200,
"code": "PRODUCT_RETRIEVED"
},
"message": "Read product 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
}
}
]
}
}Modified at 2026-08-17 06:50:11