Create products in bulk

What this endpoint does

Create up to 100 products in one all-or-nothing request.

INFO

Workflow

Categories → product batch → read each 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 A",
    "description": "<p>Synthetic voucher product.</p>",
    "image": null,
    "price": 50,
    "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-BULK-A"
    ],
    "voucherExpireDate": "2027-01-01T00:00:00.000Z"
  },
  {
    "name": "Agent B",
    "description": "<p>Synthetic voucher product.</p>",
    "image": null,
    "price": 75,
    "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-BULK-B"
    ],
    "voucherExpireDate": "2027-01-01T00:00:00.000Z"
  }
]

Success and readback

Branch on: meta.code = PRODUCTS_BULK_CREATED

{
  "meta": {
    "status": "success",
    "statusCode": 201,
    "code": "PRODUCTS_BULK_CREATED",
    "created": 2
  },
  "message": "Create products in bulk successfully",
  "data": [
    {
      "_id": "prd_agent_a",
      "name": "Agent A",
      "category": {
        "_id": "cat_agent_01",
        "name": "Agent Test Rewards",
        "displayOrder": 10
      },
      "price": 50,
      "stocks": 2
    },
    {
      "_id": "prd_agent_b",
      "name": "Agent B",
      "category": {
        "_id": "cat_agent_01",
        "name": "Agent Test Rewards",
        "displayOrder": 10
      },
      "price": 75,
      "stocks": 2
    }
  ]
}

CHECK

Readback

List by the returned IDs or exact names and verify every item. The response returns created in meta and the created products in data.

Errors and recovery

Branch on meta.code, never message text.

HTTP	Machine code	What the caller should do	Retry?
400	`VALIDATION_FAILED`	Repair the indexed item; the request writes nothing.	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`	Resolve conflicting items before retrying.	After reconciliation
500	`INTERNAL_ERROR`	Retry with exponential backoff and the same request context, then escalate.	Yes, with backoff

Retry safety

WARNING

Exact retry

This bulk create is not idempotent. Reconcile every item before deciding whether to retry.

Gotchas

Avoid this mistake

Next steps

List Store products

Continue with the next operation in the connected Store lifecycle.

curl --location 'https://api.returning.ai/v1/products/bulk' \ --header 'Authorization: Bearer XXXXXX' \ --header 'Content-Type: application/json' \ --data '[ { "name": "Premium Voucher", "description": "Premium access reward.", "image": "https://example.com/product.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": [ { "isEnabled": true, "type": "role", "permission": { "roleNames": [ "VIP Member" ], "tagNames": [ "Early Access" ], "usernames": [ "alex" ], "combination": [ { "type": "role", "values": [ "VIP Member" ] } ] }, "purchaseAccess": { "specialPrice": 80, "isSpecialPriceEnabled": false }, "purchaseLimit": { "isPurchaseLimitEnabled": false, "quantity": 1, "intervalCount": 1, "intervalUnit": "months" }, "accessLevel": "full-access", "isExclusiveTagEnabled": false } ], "isProductAccessEnabled": false, "purchaseStatusOverrideName": null, "vouchers": [ "VOUCHER-001", "VOUCHER-002" ], "voucherExpireDate": "2026-12-31T00:00:00.000Z" } ]'

{ "meta": { "status": "success", "statusCode": 201, "created": 1 }, "message": "Create products success.", "data": [ { "_id": "507f1f77bcf86cd799439011", "communityID": "6502c9e514a3e564c5c09c0a", "name": "Premium Voucher", "description": "Redeem for premium access.", "image": "https://example.com/product.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": [ { "isEnabled": true, "type": "role", "permission": { "roleNames": [ "VIP Member" ], "tagNames": [ "Early Access" ], "usernames": [ "alex" ], "combination": [ { "type": "role", "values": [ "VIP Member" ] } ] }, "purchaseAccess": { "specialPrice": 80, "isSpecialPriceEnabled": false }, "purchaseLimit": { "isPurchaseLimitEnabled": false, "quantity": 1, "intervalCount": 1, "intervalUnit": "months" }, "accessLevel": "full-access", "isExclusiveTagEnabled": false } ], "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