Returning.AIDevelopers
v1

API reference / Store / Products

.md

Delete product

Permanently remove one Store product from the community that owns your API key.

Last updated 26 Sep 2026API v1

Method
DELETE
Path
https://api.returning.ai/v1/products/{productID}
Permission
store
Retries
No Idempotency-Key; a repeat returns 404

When to use this

  • A reward is discontinued and should never come back.
  • You created a product by mistake, for example with the wrong category or price.
  • You clean up test products after checking your integration.

Authentication#

Header
Authorization: Bearer <API_KEY>
Permission
storeShown in the dashboard as “Store”

Send a Community API key with the store permission. The key decides the community, so you can only delete products in that community. Keep the key on your server.

Behaviour#

The product is removed at once and can't be restored: Read product returns 404 from then on. Orders traders already placed for it are kept, and still appear in the order lists and order detail. Those orders can lose the product's ID and name, because the product can't be looked up any more.

Archiving keeps the product and hides it from traders. Use Update product and append vouchers with isArchived: true when you might want it back.

Request#

Path parameters#

productID#stringREQUIRED
ID of the product to delete, from List products or Read product.

Rule24-character hex ID

Eg66f000000000000000000101

Headers#

Authorization#stringREQUIRED
Community API key with store.

RuleBearer <API_KEY>

curl --request DELETE \
  --url https://api.returning.ai/v1/products/66f000000000000000000101 \
  --header 'Authorization: Bearer <API_KEY>'

Response#

A 200 returns the deleted product's ID as a string in data. Branch on the HTTP status and meta.code, never on message.

meta#objectALWAYS
Status details.

Eg{ ... }

status#stringALWAYS
Result of the request.

Rulesuccess

statusCode#integerALWAYS
The HTTP status, repeated.

Eg200

code#stringALWAYS
Machine-readable result code.

RulePRODUCT_DELETED

message#stringALWAYS
Human-readable summary. Do not branch on it.

Eg"Delete product success."

data#stringALWAYS
ID of the deleted product.

Eg"66f000000000000000000101"

{
  "meta": {
    "status": "success",
    "statusCode": 200,
    "code": "PRODUCT_DELETED"
  },
  "message": "Delete product success.",
  "data": "66f000000000000000000101"
}

Errors#

Every error carries its code in meta.code, with the reason in detail. A product in another community returns 404, the same as a missing one.

Fix the request04

400VALIDATION_FAILEDFix the request
productID isn't a 24-character hex ID. Nothing was deleted.
401AUTH_API_KEY_REQUIREDFix the request
No key was sent. Send Authorization: Bearer <API_KEY>.
401AUTH_API_KEY_INVALIDFix the request
The key is unknown, expired or malformed. Use a current Community API key.
403AUTH_PERMISSION_REQUIREDFix the request
The key lacks store. Add the permission in Settings > Integration > API Keys.

Fix the data01

404STORE_RESOURCE_NOT_FOUNDFix the data
No product with this ID in your community. It may already be deleted, or belong to another community. If you are retrying a delete, treat this as done.

Retry with backoff03

502STORE_DEPENDENCY_UNAVAILABLERetry with backoff
The outcome is unknown. Read the product; if it still exists, delete it again.
500INTERNAL_ERRORRetry with backoff
The outcome is unknown. Read the product; if it still exists, delete it again.
401AUTH_API_KEY_VALIDATION_FAILEDRetry with backoff
The key could not be checked just now, and nothing was deleted. Retry with backoff.
{
  "meta": {
    "status": "error",
    "statusCode": 400,
    "code": "VALIDATION_FAILED"
  },
  "message": "Validation failed",
  "detail": {
    "productID": "productID must be a valid MongoDB ObjectId string"
  },
  "solution": "Please check the request and try again"
}

Next step#

Read productGET/v1/products/{productID}Confirm the delete. Read product now returns 404 STORE_RESOURCE_NOT_FOUND for this ID.