Create store product

Creates a store product for the API-key's community and returns the created product.

Use this when a partner integration needs to add a product, reward, voucher, or catalog item to the authenticated community's storefront.

Authentication:

Bearer API key in Authorization header

API key must have the store permission

Community is resolved from the API key token — do not pass communityID

Returns 401 if the key is missing, invalid, or expired

Returns 403 if the key does not include the store permission

Side effects:

A product is created for the resolved community

Publishes create:product

Downstream store service processes the write

Rate limits:

Standard API rate limits apply

Constraints:

name and price are required

categoryID, when provided, must refer to a category accepted by the store service

Discount, access, permission, redemption, and purchase-status override fields follow the source store-service product shape

Upstream store-service failures return 502

Example — create:

{
  "name": "Premium Voucher",
  "description": "<p>Premium access.</p>",
  "price": 100,
  "type": "voucher",
  "categoryID": "650906d314a3e564c56f3450"
}

Related endpoints:

GET /products — list active store products

GET /products/{productID} — read a single store product

PUT /products/{productID} — update a store product

DELETE /products/{productID} — delete a store product

What it is for: Create store product in the community store catalog. Use this to manage redeemable products and broker reward inventory.
How to use it: Send a POST request to /products with the request body, query parameters, or multipart fields shown below. Partner API key required when this surface is enabled for the community. Confirm gateway access before using in production.
Successful response: HTTP 201. The body follows the endpoint schema; many integration endpoints wrap the useful payload under data with status and message.
Common error states:

400 invalid request body, query, ObjectId, pagination, file format, or missing required field.

401 missing, invalid, expired, or insufficient API key/token.

403 key is valid but cannot access this community/channel/user/resource, where supported by the service.

404 target resource, route, or community-scoped record was not found.

409 duplicate or conflicting state for create/update operations, where applicable.

500 unexpected Returning.AI service error.

{ "meta": { "status": "success", "statusCode": 201 }, "message": "Create product success.", "data": { "_id": "507f1f77bcf86cd799439031", "communityID": "6502c9e514a3e564c5c09c0a", "name": "Premium Voucher", "description": "<p>Premium access.</p>", "image": "https://example.com/product.png", "price": 100, "type": "voucher", "categoryID": "650906d314a3e564c56f3450", "isArchived": false, "displayOrder": 0, "createdAt": "2026-04-28T00:00:00.000Z", "updatedAt": "2026-04-28T00:00:00.000Z" } }

Request

Responses