# Campaign API V3 — Developer Guide

- **Applies to:** Sprinklr Campaign API V3 (`/api/v3/campaign`, `/api/v3/campaign/brief`)
- **V2 API reference:** [Campaign | Sprinklr Developer Portal](https://legacy-dev.sprinklr.com/campaign)


## 1. Overview

A **product** is a single item record in a Sprinklr **product catalog** — the centralized repository of the goods and services your brand sells. Catalog data drives Reviews sub-ratings, Product Insights, and product-aware chatbot and agent responses. It also keeps product information consistent across channels. For Meta channels (WhatsApp, Facebook, and Instagram), Facebook Business Manager synchronises the catalog. For all other sources, you load and maintain products through the Product Catalog APIs.

Product V3 exposes full CRUD on a **single resource path** — `/api/v3/product` — differentiated by HTTP method, plus one auxiliary path for external-key upsert:

| Operation | Method | Path |
|  --- | --- | --- |
| Fetch product(s) | `GET` | `/api/v3/product?productId=` or `?externalProductId=` |
| Create product | `POST` | `/api/v3/product` |
| Update product (full replace) | `PUT` | `/api/v3/product?productId=` or `?externalProductId=` |
| Update product (partial) | `PATCH` | `/api/v3/product?productId=` or `?externalProductId=` |
| Delete product (soft delete) | `DELETE` | `/api/v3/product?productId=` or `?externalProductId=` |
| Upsert product by external source product ID | `POST` | `/api/v3/product/upsert` |


### 1.1 The product data model

A `Product` consists of four logical layers.

| Layer | Fields | What it holds |
|  --- | --- | --- |
| Identity | `id`, `source`, `sourceType`, `sourceId`, `sourceProductId`, `channelType` | Who owns the record and how it is keyed. `sourceType` and `sourceProductId` are the external identity; `id` is the Sprinklr identity. |
| Placement | `catalogIds`, `categoryIds`, `groupId` | Which catalogs and categories the product belongs to, and which variant group it joins. |
| Commerce attributes | `title`, `description`, `link`, `price`, `standardPrice`, `sellingPrice`, `currency`, `availability`, `inventory`, `gtin`, `mpn`, `brand`, `retailerId`, `sku`, `specification`, `subSpecification`, `delisted` | The merchandising payload. |
| Media and workflow | `attachment`, `workflow` | Product imagery/video and Sprinklr-side workflow state (custom properties, queues, assignment, space workflows). |


Use `specification` to define attributes that distinguish product variants, such as `size` or `colour`. Use `groupId` to group related variants.

### 1.2 Addressing a product

You can identify a product in two ways:

- **By Sprinklr ID** — `productId`, for example `5ffc72931b36a02632e347a8`
- **By external source product ID** — `externalProductId`, the identifier the product carries in your source system (`sourceProductId`), for example `PE897Ω0524`


`GET` accepts either parameter and supports up to 50 comma-separated IDs per request. `POST` request takes no query parameter at all. The API identifies the product by the `sourceProductId` in the request body.

## 2. Base URLs and environments

**All API calls are sent to the production endpoint:**

```
https://api3.sprinklr.com/{env}/api/v3
```

So the product resource in production is:

```
https://api3.sprinklr.com/{env}/api/v3/product
```

Replace `{env}` with your assigned environment identifier. The V3 specification enumerates: `prod`, `prod0`, `prod2`, and so on. See [APIs | Sprinklr Developer Portal](https://dev.sprinklr.com/apis) for the current environment list.

## 3. Authentication and common headers

OAuth 2.0 authenticates all Product API calls. See [Developer Tools in Sprinklr](https://www.sprinklr.com/help/articles/developer-tools/developer-tools-in-sprinklr/692e8b39f0afa271d18a5929) to generate an API key and secret and authorize access, and [API Overview](https://dev.sprinklr.com/api-overview) for the OAuth grant types supported by Sprinklr.

| Header | Value | Purpose | Required on |
|  --- | --- | --- | --- |
| `Authorization` | `Bearer {{accessToken}}` | Authenticates the user with the server. | All requests |
| `Key` | `{{apiKey}}` | Authenticates the application with the server. | All requests |
| `Content-Type` | `application/json` | Declares the request body media type. | `POST`, `PUT`, `PATCH` |
| `Accept` | `application/json` | Declares the acceptable response type. | All requests |


Every request carries `Authorization` and `Key`, with `Content-Type: application/json` added on `POST`/`PUT` and `Accept: application/json` on `GET`/`PUT`/`DELETE`.

**Permissions**: Users need the appropriate Product Catalog permissions to access Product API operations. Missing permissions return a `403 Forbidden` response.

## 4. Write operations

### 4.1 Create a product

**`POST /api/v3/product`**

Use this API to create a product and associate it with one or more catalogs. The API returns the newly created product.

#### Request body parameters

| **Parameter** | **Sub parameter** | **Required** / **Optional** | **Type** | **Description** |
|  --- | --- | --- | --- | --- |
| `source` |  | **Required** | Object | Source details for the product. |
|  | `sourceType` | **Required** | String | Type of product source. Example: `ACCOUNT`, `EXTERNAL`. |
|  | `sourceProductId` | **Required** | String | Unique identifier of the product in the source system. |
|  | `sourceId` | Optional | String | Identifier of the source account or system. |
|  | `channelType` | **Required** | String | Channel associated with the product source. |
| `catalogIds` |  | Optional | Array[String] | Identifiers of the catalogs that contain the product. |
| `categoryIds` |  | Optional | Array[String] | Identifiers of the categories assigned to the product. |
| `title` |  | Optional | String | Title of the product. |
| `description` |  | Optional | String | Description of the product. |
| `link` |  | Optional | String | URL of the product. |
| `price` |  | Optional | Object | Pricing information for the product. |
|  | `value` | **Required** within price | Double | Product price amount. |
|  | `currency` | Optional | String | Currency associated with the price amount. |
| `standardPrice` |  | Optional | Double | Standard price of the product. |
| `sellingPrice` |  | Optional | Double | Selling price of the product. |
| `currency` |  | Optional | String | Currency associated with the standard or selling price. |
| `availability` |  | Optional | String | Availability status of the product. |
| `inventory` |  | Optional | Integer | Available inventory quantity. |
| `gtin` |  | Optional | String | Global Trade Item Number (GTIN) of the product. |
| `mpn` |  | Optional | String | Manufacturer part number of the product. |
| `brand` |  | Optional | String | Brand name of the product. |
| `retailerId` |  | Optional | String | Retailer-specific identifier of the product. |
| `sku` |  | Optional | String | Stock keeping unit (SKU) of the product. |
| `groupId` |  | Optional | String | Product group identifier used to group product variants. |
| `specification` |  | Optional | Map[String, String] | Product attributes that distinguish a variant from other products in the same group. |
| `subSpecification` |  | Optional | Map[String, Object] | Additional attributes associated with a specification attribute. |
| `attachment` |  | Optional | Object | Media attached to the product. |
|  | `type` | **Required** within attachment | String | Type of attachment. Example: `IMAGE`, `VIDEO`, `CAROUSEL`, `LINK`, `DOC`. |
|  | `url` | Optional | String | URL of the attached media. |
|  | `alternateText` | Optional | String | Alternative text associated with the attachment. |
| `workflow` |  | Optional | Object | Workflow properties associated with the product. |
| `delisted` |  | Optional | Boolean | Indicates whether the product is delisted. |


#### 4.1.1 `attachment`

| **Parameter** | **Required** / **Optional** | **Type** | **Description** |
|  --- | --- | --- | --- |
| `type` | **Required** within attachment | String | Type of attachment. Example: `IMAGE`, `VIDEO`, `CAROUSEL`, `LINK`, `DOC`. |
| `url` | Optional | String | URL of the attached media. |
| `alternateText` | Optional | String | Alternative text associated with the attachment. |


#### 4.1.2 `workflow`

| **Parameter** | **Required** / **Optional** | **Type** | **Description** |
|  --- | --- | --- | --- |
| `assignment` | Optional | Object | Assignment details associated with the product. |
| `modifiedTime` | Optional | Long | Workflow modification time, in epoch milliseconds. |
| `customProperties` | Optional | Map[String, Array[String]] | Custom properties associated with the product. |
| `queues` | Optional | Array[Object] | Queue information associated with the product workflow. |
| `spaceWorkflows` | Optional | Array[Object] | Workspace-level workflows associated with the product. |


In API payloads, custom property keys use Sprinklr custom-field IDs in the format `_c_<24-hex-id>`. For example, `_c_62b2f38107fc693d373ea40e`. Values are always arrays, even when the field is single-valued.

#### Sample Request

```bash
curl --location POST 'https://api3.sprinklr.com/{env}/api/v3/product' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Key: {{apiKey}}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
    "source": {
        "sourceType": "ACCOUNT",
        "sourceProductId": "PE58790024",
        "sourceId": "2567865",
        "channelType": "SOURCE_AGNOSTIC"
    },
    "catalogIds": [
        "632866b24423b4217dd08a0b"
    ],
    "categoryIds": [
        "FRAG"
    ],
    "title": "Test Product",
    "link": "https://spriklr.com/pe/p/200897",
    "price": {
        "value": 78.0
    },
    "specification": {
        "product_type": "PERFUME",
        "cuv": "41",
        "campaign_code": "216",
        "country_iso": "PE"
    },
    "groupId": "20097",
    "attachment": {
        "type": "IMAGE",
        "url": "https://cloudfront.net/PE/202016/05841.jpg"
    },
    "workflow": {
        "customProperties": {
        "_c_62b2f38107fc693d373ea40e": [
            "nnlb"
        ],
        "_c_5fa41eba513a9e238d7a810a": [
            "New"
        ]
        }
    }
}'
```

#### Response

A successful request returns **201 Created** and the created product in the data object. The response also includes an errors array.

```json
{
    "data": {
        "id": "6a9968815d82d94f23d44994",
        "source": {
            "sourceType": "ACCOUNT",
            "sourceId": "2567865",
            "sourceProductId": "PE58790024",
            "channelType": "SOURCE_AGNOSTIC"
        },
        "catalogIds": [
            "632866b24423b4217dd08a0b"
        ],
        "categoryIds": [
            "FRAG"
        ],
        "title": "Test Product",
        "link": "https://spriklr.com/pe/p/200897",
        "price": {
            "value": 78
        },
        "specification": {
            "product_type": "PERFUME",
            "cuv": "41",
            "campaign_code": "216",
            "country_iso": "PE"
        },
        "groupId": "20097",
        "attachment": {
            "url": "https://cloudfront.net/PE/202016/05841.jpg",
            "encryptedUrl": "enc_Lw/tAIdPRcx8V786WADAexLr/gkFONw3lwzG5KxZy9lG+BRFc1X7hwQB+7XlXthVwWbt7Aq63DOBGj8fUJ0bjn2iUeOdDA==",
            "type": "IMAGE"
        },
        "workflow": {
            "customProperties": {
                "_c_62b2f38107fc693d373ea40e": [
                    "nnlb"
                ],
                "_c_5fa41eba513a9e238d7a810a": [
                    "New"
                ]
            }
        },
        "delisted": false
    },
    "errors": []
}
```

### 4.2 Update a product — full update

- **`PUT /api/v3/product?productId={productId}`**
- **`PUT /api/v3/product?externalProductId={sourceProductId}`**


Use this API to replace an existing product. Include the complete product definition in the request body because any omitted values may be removed.

#### Query parameters

| Parameter | Type | Required / Optional | Description | Example |
|  --- | --- | --- | --- | --- |
| `productId` | String | Optional | Identifier of the product to update. | `5ffc72931b36a02632e347a8` |
| `externalProductId` | String | Optional | External source product ID. | `PE897-0524` |


> **Note**: Specify either `productId` or `externalProductId`. Do not specify both.


#### Sample Request

```bash
curl --location --request PUT 'https://api3.sprinklr.com/{env}/api/v3/product?productId={{productId}}' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Key: {{apiKey}}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
    "source": {
        "sourceType": "ACCOUNT",
        "sourceProductId": "{{sourceProductId}}",
        "sourceId": "{{sourceId}}",
        "channelType": "SOURCE_AGNOSTIC"
    },
    "catalogIds": ["{{catalogId}}"],
    "categoryIds": ["{{categoryId}}"],
    "title": "Updated product title",
    "description": "Updated product description",
    "link": "https://example.com/products/{{sourceProductId}}",
    "price": {
        "value": 99.0
    },
    "specification": {
        "{{attributeName}}": "{{attributeValue}}"
    },
    "groupId": "{{groupId}}",
    "attachment": {
        "type": "IMAGE",
        "url": "https://example.com/images/product.jpg"
    },
    "workflow": {
        "customProperties": {
            "{{customFieldId}}": ["{{customFieldValue}}"]
        }
    },
    "delisted": false
}'
```

#### ⚠️ `PUT` replaces — it does not merge

On `PATCH`, the API updates only the fields that you provide and leaves all other fields unchanged. By contrast, `PUT` replaces the product document. The API does not preserve fields that you omit from a `PUT` request.

For example, if a `PUT` request omits `catalogIds`, `specification`, or `workflow.customProperties`, the API can remove those values from the product, including custom-property values added by Sprinklr users.
Before you send a PUT request:

1. Retrieve the current product by using `GET`.
2. Merge your changes into the retrieved document.
3. Send the merged document in the `PUT` request.


If you need to update only a few fields, such as `price`, `inventory count`, or `delisted status`, use `PATCH` instead. `PATCH` lets you update specific fields without performing a read-modify-write cycle.

### 4.3 Update a product — partial update

- **`PATCH /api/v3/product?productId={productId}`**
- **`PATCH /api/v3/product?externalProductId={sourceProductId}`**


Use this API to update specific fields in an existing product. Unlike `PUT`, you do not need to provide the complete product definition in the request body. Include only the fields that you want to update. The API preserves fields that are not included in the request.

#### Query parameters

| Parameter | Type | Required / Optional | Description | Example |
|  --- | --- | --- | --- | --- |
| `productId` | String | Optional | Identifier of the product to update. | `5ffc72931b36a02632e347a8` |
| `externalProductId` | String | Optional | External source product ID | `PE897-0524` |


> **Note**: Specify either `productId` or `externalProductId`. Do not specify both.


#### Request body parameters

> **Note**: PATCH uses a different request schema than `PUT`. The request bodies are not interchangeable.


| **Parameter** | **Type** | **Description** |
|  --- | --- | --- |
| `title` | String | Title of the product. |
| `description` | String | Description of the product. |
| `link` | String | URL of the product. |
| `standardPrice` | Double | Standard price of the product. |
| `sellingPrice` | Double | Selling price of the product. |
| `currency` | String | Currency associated with the product price. |
| `availability` | String | Availability status of the product. |
| `inventory` | Integer | Available inventory quantity. |
| `gtin` | String | Global Trade Item Number (GTIN) of the product. |
| `mpn` | String | Manufacturer part number of the product. |
| `brand` | String | Brand name of the product. |
| `retailerId` | String | Retailer-specific identifier of the product. |
| `sku` | String | Stock keeping unit (SKU) of the product. |
| `groupId` | String | Product group identifier used to group product variants. |
| `specification` | Map[String, String] | Product attributes that distinguish a variant from other products in the same group. |
| `subSpecification` | Map[String, Object] | Additional attributes associated with a specification attribute. |
| `catalogIds` | Array[String] | Identifiers of the catalogs that contain the product. |
| `categoryIds` | Array[String] | Identifiers of the categories assigned to the product. |
| `attachment` | Object | Media attached to the product. |
| `workflow` | Object | Workflow properties associated with the product. |
| `delisted` | Boolean | Indicates whether the product is delisted. |


> **Note**: `PATCH` does not support the following fields: `id`, `source`, `sourceType`, `sourceId`, `sourceProductId`, `channelType`, and the nested `price` object. You cannot update identity fields through this endpoint. To update pricing, use `standardPrice`, `sellingPrice`, and `currency` instead of `price.value`.


```bash
curl --location --request PATCH 'https://api3.sprinklr.com/{env}/api/v3/product?productId={{productId}}' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Key: {{apiKey}}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"sellingPrice": 69.99,
"currency": "USD",
"inventory": 8,
"availability": "IN_STOCK"
}'
```

### 4.4 Upsert a product by external source product ID

**`POST /api/v3/product/upsert`**

Creates a product if no matching `sourceProductId` exists. Otherwise, the API updates the existing product. This endpoint accepts a complete `Product` object and does not use query parameters. The API identifies the product by the `sourceProductId` in the request body.

Use this endpoint for feed-based integrations that do not store Sprinklr product IDs. Send the same product payload with each synchronisation cycle, and the API determines whether to create a new product or update an existing one.

```bash
curl --location POST 'https://api3.sprinklr.com/{env}/api/v3/product/upsert' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Key: {{apiKey}}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
    "source": {
        "sourceType": "EXTERNAL",
        "sourceProductId": "PE897-0524"
    },
    "catalogIds": ["ONE"],
    "title": "The EPIC",
    "price": { "value": 78.0, "currency": "USD" },
    "inventory": 40
}'
```

### 4.5 Delete a product (soft delete)

- **`DELETE /api/v3/product?productId={productId}`**
- **`DELETE /api/v3/product?externalProductId={sourceProductId}`**


Use this API to soft-delete one or more products from the product catalog. Provide a single product ID or multiple product IDs as a comma-separated list in the productId query parameter.

```bash
curl --location --request DELETE 'https://api3.sprinklr.com/{env}/api/v3/product?productId=6a7e8f9938a5f5ee3801e212' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Key: {{apiKey}}' \
--header 'Accept: application/json'
```

`DELETE` and `delisted` serve different purposes.

| Intent | Operation |
|  --- | --- |
| Keep the product in the catalog but prevent it from appearing on channels | `PATCH` with `{"delisted": true}` |
| Remove the product from the catalog | `DELETE` |


Use `delisted` to temporarily disable a product without removing it from the catalog. Use `DELETE` when you no longer want the product to exist in the catalog.

### 4.6 Method comparison — when to use which

|  | `POST` | `POST /upsert` | `PUT` | `PATCH` | `DELETE` |
|  --- | --- | --- | --- | --- | --- |
| Purpose | Create a new product | Create or update by external key | Replace the full product document | Change selected fields | Soft-delete the product |
| Addressing | None — identity comes from the body | None — `sourceProductId` in the body | `?productId=` or `?externalProductId=` | `?productId=` or `?externalProductId=` | `?productId=` or `?externalProductId=` |
| Identity fields in body | Required (`source`, `sourceType`, `sourceProductId`) | Required | Required | Not accepted | — |
| Unspecified fields | N/A | Replaced on the update path | **Replaced/cleared** | **Preserved** | — |
| Safe for incremental sync | — | Only if you always send the full record | No, without read-modify-write | Yes | — |


## 5. Read operations

### 5.1 `GET /api/v3/product` — Fetch product(s)

Use this endpoint to retrieve one or more products by Sprinklr product ID (`productId`) or external product ID (`externalProductId`). You can retrieve up to 50 products in a single request by providing a comma-separated list of IDs.

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `productId` | String | Optional | Sprinklr product ID(s), **comma-separated for bulk (max 50)** |
| `externalProductId` | String | Optional | External source product ID(s), **comma-separated for bulk (max 50)** |


```bash
# Single product by Sprinklr ID
curl --location 'https://api3.sprinklr.com/{env}/api/v3/product?productId=6a7e8f9938a5f5ee3801e212' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Key: {{apiKey}}' \
--header 'Accept: application/json'
```

```bash
# Bulk fetch — up to 50 IDs in one call
curl --location 'https://api3.sprinklr.com/{env}/api/v3/product?productId=5ffc72931b36a02632e347a8,5ffc72931b36a02632e347a9' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Key: {{apiKey}}' \
--header 'Accept: application/json'

# By external source product id
curl --location 'https://api3.sprinklr.com/{env}/api/v3/product?externalProductId=PE897-0524' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Key: {{apiKey}}' \
--header 'Accept: application/json'
```

**Response**

```json
{
  "data": {
    "id": "5ffc72931b36a02632e347a8",
    "source": {
      "sourceType": "EXTERNAL",
      "sourceProductId": "PE897-0524"
    },
    "catalogIds": ["ONE"],
    "categoryIds": ["FRAG"],
    "title": "The EPIC",
    "link": "https://sprinklr.com/pe/p/200897",
    "price": { "value": 78.0 },
    "inventory": 40,
    "specification": {
      "product_type": "PERFUME",
      "cuv": "41",
      "campaign_code": "216",
      "country_iso": "PE"
    },
    "groupId": "20097",
    "attachment": { "type": "IMAGE" },
    "workflow": {
      "customProperties": {
        "OFFER_PRICE_CF_NEW": ["2.9"],
        "STRATEGY_CODE_CF_VALUE": ["0"]
      }
    }
  },
  "errors": []
}
```

**Pagination**: To retrieve multiple products, provide a comma-separated list of up to 50 product IDs or external product IDs in a single request. Product V3 does not provide an endpoint to retrieve all products in a catalog.

## 6. Response format and status codes

### 6.1 The V3 envelope

| Field | Type | Description |
|  --- | --- | --- |
| `data` | Object | The product payload |
| `errors` | Array[`Error`] | Array of error objects (empty if no errors) |
| `metadata` | Object (`ResponseMetadata`) | Response metadata |


### 6.2 Response codes

| HTTP code | Scenario | Description |
|  --- | --- | --- |
| `200 OK` | Success | Operation completed. Also returned by `POST` on create — **not** `201`. |
| `400 Bad Request` | Invalid parameters | Missing required fields, invalid parameter combination, or malformed body |
| `401 Unauthorized` | Authentication failed | Invalid or missing `Authorization` token or `Key` |
| `403 Forbidden` | Insufficient permissions | The calling user's role lacks the required product/catalog permission |
| `404 Not Found` | No product found | No product matches the supplied `productId` / `externalProductId` |


`500 Internal Server Error` is not declared on these operations but should still be handled by any production client.

## 7. Migration from V2 to V3

### 7.1 Endpoint mapping

| V2 | V3 |
|  --- | --- |
| `POST /api/v2/product` | `POST /api/v3/product` |
| `GET /api/v2/product/{Id}` | `GET /api/v3/product?productId=` (or `?externalProductId=`) |
| `PUT /api/v2/product/{Id}` | `PUT /api/v3/product?productId=` |
| `DELETE /api/v2/product/{Id}` | `DELETE /api/v3/product?productId=` |
| *No V2 equivalent* | `PATCH /api/v3/product?productId=` |
| *No V2 equivalent on this page* | `POST /api/v3/product/upsert` — upsert by external source product ID |
| `POST /api/v1/universal-commerce/product/create` (V1) | `POST /api/v3/product` |


### 7.2 What changed, and what did not

| Aspect | API V2 | API V3 | Impact |
|  --- | --- | --- | --- |
| Addressing | Path segment `/product/{Id}` | Query parameter `?productId=` | Every URL in your client changes. |
| External-key lookup | Not available on the product path | `?externalProductId=` | You no longer need to persist Sprinklr IDs. |
| Bulk | One product per call | Comma-separated IDs, **max 50**, on `GET` | Up to 50× fewer round trips on read. |
| Partial update | Not available — `PUT` only | `PATCH` | Update the price directly without retrieving the product first. |
| Request body fields | `Product_V2` | `Product` | Reuse the existing payload builders without changes. |
| Response envelope | `{data, errors}` | `{data, errors}` | Reuse the existing response parsers without changes. |
| Base path | `/api/v2` | `/api/v3` | Base-URL change. |


### 7.3 Migration steps

1. **Update the base URL** to `https://api3.sprinklr.com/{env}/api/v3`.
2. **Move the identifier from the path to the query string.** `/product/5ffc72931b36a02632e347a8` to `/product?productId=5ffc72931b36a02632e347a8`.
3. **Keep your existing request bodies** for `POST` and `PUT`. `source`, `catalogIds`, `categoryIds`, `title`, `price`, `attachment`, `workflow`, and the remaining fields are unchanged.
4. **Keep your existing response parsers**. The `{data, errors}` envelope is unchanged.
5. **Retrieve multiple products in a single `GET` request**. Include up to 50 product IDs per request.
6. **Use `PATCH` for partial updates**. Include only the fields you want to update, omit identity fields, and map `price`.`value` to `standardPrice` or `sellingPrice`, as applicable.
7. **Switch feed-style integrations to `/product/upsert`** if your source system has no Sprinklr ID.
8. **Re-verify permissions**.


## 8. Use cases

### 8.1 Initial catalog load from an external commerce platform

**Scenario:** You are onboarding and need to push several thousand SKUs into a Sprinklr catalog.

Send one `POST /api/v3/product` request for each SKU with `source.sourceType = "EXTERNAL"`, `source.sourceProductId` = your SKU key, and `catalogIds` set to the target catalog. Group variants of the same item by giving them a shared `groupId` and distinct `specification` maps.

### 8.2 Hourly price and inventory sync

**Scenario:** Prices and stock levels change continuously.

Use `PATCH` with the three fields that actually changed:

```json
{ "sellingPrice": 69.99, "currency": "USD", "inventory": 8 }
```

You do not need to retrieve the product first, and you avoid the risk of overwriting `catalogIds`, `specification`, or workflow custom properties. Using `PUT` here would require reconstructing the entire product document to change one number.

### 8.3 Seasonal delisting without deleting

**Scenario:** A product goes out of season and must stop appearing in Chatbot and agent product replies, but returns next year.

```json
{ "delisted": true }
```

Send a `PATCH` request with `{"delisted": true}` now. When the product becomes available again, send `{"delisted": false}`. Do **not** use `DELETE`. You have to recreate the record and lose its history.

### 8.4 Reconcile a batch of products against your source system

**Scenario:** A nightly job compares 200 stock keeping units (SKUs) in your product information management (PIM) system with products in Sprinklr.

Retrieve products by `externalProductId` in batches of up to 50:

```
GET /api/v3/product?externalProductId=SKU1,SKU2,...,SKU50
```

For 200 SKUs, this requires four requests. Compare the returned products with your PIM data and update only the fields that have changed.

### 8.5 Feed-driven integration with no ID bookkeeping

**Scenario:** A partner drops a full product feed daily. You do not track which items are new.

Push each row to `POST /api/v3/product/upsert` with `sourceProductId` set from the feed's own key. Sprinklr inserts or updates as appropriate. Because upsert takes the full `Product` object, send the complete record each time — treat it as `PUT` semantics on the update path.

### 8.6 Move a product between catalogs or categories

**Scenario:** merchandising re-organizes the catalog structure.

`PATCH` with the new `catalogIds` / `categoryIds` arrays. Send the **complete intended list**, not just the additions. Sending the full list is correct under either semantics.

### 8.7 Enrich products with Sprinklr-side custom properties

**Scenario:** a pricing engine writes an offer price and a strategy code onto each product for use in agent replies.

```json
{
  "workflow": {
    "customProperties": {
      "OFFER_PRICE_CF_NEW": ["2.9"],
      "STRATEGY_CODE_CF_VALUE": ["0"]
    }
  }
}
```

Custom property values are **always lists**, even when the field holds one value.

## 9. Caveats and best practices

**Method selection**

- Default to `PATCH`. Use `PUT` only when you have the complete authoritative document.
- `PUT` replaces the entire document. Any catalog ID, specification key, or workflow custom property omitted from the request body can be removed.
- `PUT` and `PATCH` take **different body schemas** (`Product` versus `ProductPatchRequestDTO`). Payloads are not interchangeable.
- `PATCH` does not accept identity fields (`source`, `sourceType`, `sourceProductId`, `channelType`) or the nested `price` object.


**Identifiers**

- Exactly three fields are required on create: `source`, `sourceType`, `sourceProductId`.
- Use `externalProductId` if your system does not store Sprinklr product IDs. Use `productId` if it does.
- URL-encode ID values containing reserved characters.
- Send `productId` **or** `externalProductId`, never both.


**Bulk**

- The `GET` bulk limit is **50 IDs per call**, comma-separated. Split larger sets into batches of 50.


**Deletion**

- `DELETE` is a **soft delete**. Use `delisted` for temporary removal from channels.


**Error handling**

- Always inspect the `errors` array even on a `200` response.
- Create returns **`200`**, not `201`.
- `403` means a permission gap.


**Rate limiting**

- Implement retries with exponential backoff.


**Data**

- `price` (object, with `value` and `currency`) and the flat `standardPrice` / `sellingPrice` / `currency` fields coexist on `Product`. `ProductPatchRequestDTO` supports only the flat form. Pick one convention per integration and keep it consistent.
- Custom property values are always lists.