Create product with vouchers

What this endpoint does

Create a Store product and load its first voucher inventory in one request.

INFO

Workflow

Category → product + vouchers → read product → Store widget

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

Scenario	Apidog example
Standard-price voucher product	`standard`
Product with an active discount window	`discounted`

{
  "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-001",
    "AGENT-002"
  ],
  "voucherExpireDate": "2027-01-01T00:00:00.000Z"
}

Success and readback

Branch on: meta.code = PRODUCT_CREATED

{
  "meta": {
    "status": "success",
    "statusCode": 201,
    "code": "PRODUCT_CREATED"
  },
  "message": "Create product with vouchers 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

GET /v1/products/{productID} returns stocks=2; Store admin and widget show the same product and price.

Errors and recovery

Branch on meta.code, never message text.

HTTP	Machine code	What the caller should do	Retry?
400	`VALIDATION_FAILED`	Repair errors[]; no product or vouchers persist.	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`	Replace conflicting codes; no partial stock change.	After reconciliation
500	`INTERNAL_ERROR`	Retry with exponential backoff and the same request context, then escalate.	Yes, with backoff

Retry safety

WARNING

Exact retry

Create is not idempotent. After a timeout, reconcile by exact name and stock before deciding whether to retry.

Gotchas

Avoid this mistake

Next steps

Read Store product

Read product and verify widget visibility.

curl --location 'https://api.returning.ai/v1/products' \ --header 'Authorization: Bearer XXXXXX' \ --header 'Content-Type: application/json' \ --data '{ "name": "Premium Voucher", "description": "Premium access reward.", "image": "https://example.com/images/premium-voucher.png", "price": 100, "categoryName": "Premium Rewards", "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, "redemptionInstructions": "Show this voucher at checkout.", "productPermission": [], "isProductAccessEnabled": false, "purchaseStatusOverrideName": null, "vouchers": [ "VOUCHER-001", "VOUCHER-002" ], "voucherExpireDate": "2026-12-31T00:00:00.000Z" }'

{ "meta": { "status": "success", "statusCode": 201 }, "message": "Create product success.", "data": { "_id": "507f1f77bcf86cd799439031", "communityID": "6502c9e514a3e564c5c09c0a", "name": "Premium Voucher", "description": "Premium access reward.", "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": "Show this voucher at checkout.", "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