Update product and append vouchers

What this endpoint does

Replace a product's full configuration and optionally append new voucher inventory.

INFO

Workflow

Product → replace fields or append vouchers → read product

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

{
  "name": "Agent Test Voucher",
  "description": "<p>Synthetic voucher product.</p>",
  "image": null,
  "price": 100,
  "categoryName": "Agent Test Rewards",
  "discountPrice": 0,
  "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,
  "redemptionInstructions": null,
  "productPermission": [],
  "isProductAccessEnabled": false,
  "purchaseStatusOverrideName": null,
  "vouchers": [
    "AGENT-003"
  ],
  "voucherExpireDate": "2027-01-01T00:00:00.000Z"
}

Success and readback

Branch on: meta.code = PRODUCT_UPDATED

{
  "meta": {
    "status": "success",
    "statusCode": 200,
    "code": "PRODUCT_UPDATED"
  },
  "message": "Update product and append vouchers successfully",
  "data": {
    "_id": "prd_agent_01",
    "name": "Agent Test Voucher",
    "categoryID": "650906d314a3e564c56f3450",
    "category": "Premium Rewards",
    "price": 100,
    "stocks": 3
  }
}

CHECK

Readback

GET /products/{productID}; all full-body fields match and stock increases exactly once.

Errors and recovery

Branch on meta.code, never message text.

HTTP	Machine code	What the caller should do	Retry?
400	`VALIDATION_FAILED`	Repair the complete body; no partial change.	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
409	`STORE_RESOURCE_CONFLICT`	No voucher or product field changes.	After reconciliation
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

WARNING

Exact retry

Product replacements are repeatable, but voucher append is not assumed idempotent. Read stock before retrying.

Gotchas

Avoid this mistake

Next steps

Read Store product

Continue with the next operation in the connected Store lifecycle.

curl --location --request PUT 'https://sgtr-api.returning.ai/v1/products/prd_agent_01' \ --header 'Authorization: Bearer XXXXXX' \ --header 'Content-Type: application/json' \ --data '{ "name": "Agent Test Voucher", "description": "<p>Synthetic voucher product.</p>", "image": null, "price": 100, "categoryName": "Agent Test Rewards", "discountPrice": 0, "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, "redemptionInstructions": null, "productPermission": [], "isProductAccessEnabled": false, "purchaseStatusOverrideName": null, "vouchers": [ "AGENT-003" ], "voucherExpireDate": "2027-01-01T00:00:00.000Z" }'

{ "meta": { "status": "success", "statusCode": 200, "code": "PRODUCT_UPDATED" }, "message": "Update product and append vouchers successfully", "data": { "_id": "prd_agent_01", "name": "Agent Test Voucher", "category": "Premium Rewards", "price": 100, "stocks": 3, "categoryID": "650906d314a3e564c56f3450" } }

Update product and append vouchers

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