Products | Rarely Resources

GET

/api/integrations/v1/products

List products

Returns merchant products with variants, media, and inventory-linked data.

GET

/api/integrations/v1/products/:productId

Get product

Returns a single merchant product with variants and inventory-linked data.

POST

/api/integrations/v1/products

Create product

Creates a native product with variants, media links, and optional tags.

PATCH

/api/integrations/v1/products/:productId

Update product

Updates a native product. Connected products are read-only.

GET

/api/integrations/v1/products

Read products

List products

Use this endpoint to sync the merchant catalog into a warehouse or operational system.

Query Parameters

Supported inputs for this operation.

limit

integerOptional

Maximum number of rows returned per page.

Example: 50

Default: 50

cursor

stringOptional

Opaque cursor from a previous response page.

Name	Type	Required	Description
limit	integer	No	Maximum number of rows returned per page. Example: 50 Default: 50
cursor	string	No	Opaque cursor from a previous response page.

Headers

Supported inputs for this operation.

Authorization

Bearer tokenOptional

Preferred API key header.

X-API-Key

stringOptional

Fallback API key header.

Name	Type	Required	Description
Authorization	Bearer token	No	Preferred API key header.
X-API-Key	string	No	Fallback API key header.

Examples

Switch between the sample request and example responses for this endpoint.

Sample cURL

curl -X GET "https://merchants.rarely.co/api/integrations/v1/products" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET

/api/integrations/v1/products/:productId

Read products

Get product

Use this endpoint when a downstream system needs the full canonical product object.

Path Parameters

Supported inputs for this operation.

productId

uuidRequired

Merchant-owned product id.

Example: 91dcd85d-8b1d-4f9f-90f0-694f9a604c74

Name	Type	Required	Description
productId	uuid	Yes	Merchant-owned product id. Example: 91dcd85d-8b1d-4f9f-90f0-694f9a604c74

Headers

Supported inputs for this operation.

Authorization

Bearer tokenOptional

Preferred API key header.

X-API-Key

stringOptional

Fallback API key header.

Name	Type	Required	Description
Authorization	Bearer token	No	Preferred API key header.
X-API-Key	string	No	Fallback API key header.

Examples

Switch between the sample request and example responses for this endpoint.

Sample cURL

curl -X GET "https://merchants.rarely.co/api/integrations/v1/products/:productId" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST

/api/integrations/v1/products

Write products

Create product

Use this endpoint for native catalog imports. Connected products and connected media records remain read-only; this endpoint creates Rarely-native catalog data only.

Request Body

JSON payload fields accepted by this endpoint.

title

stringRequired

Product title.

description

stringOptional

Product description.

handle

stringOptional

Preferred URL handle. Rarely will make it unique if needed.

vendor_id

uuidOptional

Merchant vendor id.

primary_image_asset_id

uuidOptional

Merchant media asset used as the primary image.

gallery_asset_ids

uuid[]Optional

Additional merchant media assets.

tag_ids

uuid[]Optional

Merchant tag ids to assign.

variants

object[]Optional

Variant rows with sku, options, price, inventory policy, media asset, shipping profile, and weight fields.

submit

booleanOptional

Submit the product for review immediately. Requires products.submit.

Field	Type	Required	Description
title	string	Yes	Product title.
description	string	No	Product description.
handle	string	No	Preferred URL handle. Rarely will make it unique if needed.
vendor_id	uuid	No	Merchant vendor id.
primary_image_asset_id	uuid	No	Merchant media asset used as the primary image.
gallery_asset_ids	uuid[]	No	Additional merchant media assets.
tag_ids	uuid[]	No	Merchant tag ids to assign.
variants	object[]	No	Variant rows with sku, options, price, inventory policy, media asset, shipping profile, and weight fields.
submit	boolean	No	Submit the product for review immediately. Requires products.submit.

Examples

Switch between the sample request and example responses for this endpoint.

Sample cURL

curl -X POST "https://merchants.rarely.co/api/integrations/v1/products" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Canvas Camp Cap",
  "description": "Structured six-panel cap with contrast stitching.",
  "variants": [
    {
      "sku": "CAP-RED-OS",
      "option1": "Red",
      "option2": "One Size",
      "price": 74
    }
  ]
}'

PATCH

/api/integrations/v1/products/:productId

Write products

Update product

Use this endpoint for partial updates to Rarely-native products. If the product is managed by a connected source, the API returns a conflict instead of changing it.

Path Parameters

Supported inputs for this operation.

productId

uuidRequired

Product id.

Example: 91dcd85d-8b1d-4f9f-90f0-694f9a604c74

Name	Type	Required	Description
productId	uuid	Yes	Product id. Example: 91dcd85d-8b1d-4f9f-90f0-694f9a604c74

Request Body

JSON payload fields accepted by this endpoint.

title

stringOptional

New pending title.

description

stringOptional

New pending description.

variants

object[]Optional

Full native variant set to keep for the product.

tag_ids

uuid[]Optional

Full tag set to keep for the product.

Field	Type	Required	Description
title	string	No	New pending title.
description	string	No	New pending description.
variants	object[]	No	Full native variant set to keep for the product.
tag_ids	uuid[]	No	Full tag set to keep for the product.

Examples

Switch between the sample request and example responses for this endpoint.

Sample cURL

curl -X PATCH "https://merchants.rarely.co/api/integrations/v1/products/:productId" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Canvas Camp Cap",
  "tag_ids": []
}'

Live PlaygroundClient memory only

Test live requests against your merchant integration API.

The docs app proxies requests server-side to the merchant API. Your API key stays in local browser memory for the current docs session and is never stored by this UI.

Operation

Auth mode

API key

Query: limit

Query: cursor

Resolved request

https://merchants.rarely.co/api/integrations/v1/products

Live Output

Switch between the generated request and the most recent live response.

Generated cURL

curl -X GET "https://merchants.rarely.co/api/integrations/v1/products" \
  -H "Authorization: Bearer YOUR_API_KEY"

Search docs