Skip to content

Product Catalog API V3 - Developer Guide

  • Applies to: /api/v3/product
  • API Version: V3
  • Resource: Product Catalog
  • Operations: Create, Fetch, Update, Partial Update, Delete
  • Supports: Single-product and bulk operations for retrieval and deletion

1. Overview

1.1 The Product Object

A product catalog is a collection of products on which Reviews appear on your website. You can use product catalogs to organize products into catalogs and categories, apply product-specific configurations, and customize product review experiences.

The Product Catalog API allows you to create, retrieve, update, partially update, and delete product records. Product records can contain:

  • Source information
  • Catalog assignments
  • Category assignments
  • Product attributes
  • Pricing information
  • Media attachments
  • Workflow properties
  • Product lifecycle status

1.2 Product Data Model

A product consists of several logical components:

Product
├─ id
├─ source
│  ├─ sourceType
│  ├─ sourceProductId
│  ├─ sourceId
│  └─ channelType
├─ catalogIds[]
├─ categoryIds[]
├─ title
├─ description
├─ link
├─ price
├─ specification
├─ subSpecification
├─ attachment
├─ workflow
└─ delisted

The source information identifies where the product originated. Catalog and category mappings determine how the product is organized within Sprinklr. Pricing, specifications, media attachments, and workflow metadata enrich the product record.

1.3 Product Identification Model

Products are identified by a unique product identifier.

IdentifierPurpose
idInternal product identifier
sourceProductIdProduct identifier in the source system
productIdAPI query parameter used for retrieval, updates, and deletion

Source systems can also provide additional identifiers such as SKU, GTIN, MPN, retailer ID, and group ID.

Supported Operations

OperationMethodEndpoint
Create a productPOST/api/v3/product
Fetch productsGET/api/v3/product?productId={productIds}
Replace a productPUT/api/v3/product?productId={productId}
Update product fieldsPATCH/api/v3/product?productId={productId}
Delete productsDELETE/api/v3/product?productId={productIds}

2. Base URLs and Environments

Base URL

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

Replace {env} with the environment identifier assigned to your Sprinklr account. The default documented value is prod.

3. Authentication and Common Headers

All operations require an access token and API key.

Required Headers

HeaderValuePurpose
AuthorizationBearer {Access Token}Authenticates the user
Key{API Key}Authenticates the application
Acceptapplication/jsonRequests a JSON response
Content-Typeapplication/jsonIdentifies the request body as JSON

Example

Authorization: Bearer {Access Token}
Key: {API Key}
Accept: application/json
Content-Type: application/json

3.1 Permissions

The source documentation does not specify the permissions required to use this API.

4. Write Operations

4.1 Create a Product

Creates a product and associates it with one or more product catalogs. A successful request returns the created product record.

Endpoint

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

Request Body

FieldTypeRequiredDescription
sourceObjectYesSource details for the product
catalogIdsArray of StringsNoIdentifiers of catalogs that contain the product
categoryIdsArray of StringsNoIdentifiers of categories assigned to the product
titleStringNoProduct title
descriptionStringNoProduct description
linkStringNoProduct URL
priceObjectNoPricing information
standardPriceNumberNoStandard product price
sellingPriceNumberNoSelling price
currencyStringNoCurrency for the standard or selling price
availabilityStringNoProduct availability status
inventoryIntegerNoAvailable inventory quantity
gtinStringNoGlobal Trade Item Number
mpnStringNoManufacturer part number
brandStringNoBrand name
retailerIdStringNoRetailer-specific identifier
skuStringNoStock keeping unit
groupIdStringNoIdentifier used to group product variants
specificationMap of String to StringNoAttributes that distinguish a variant from other products in the same group
subSpecificationMap of String to ObjectNoAdditional attributes associated with a specification attribute
attachmentObjectNoMedia attached to the product
workflowObjectNoWorkflow properties associated with the product
delistedBooleanNoIndicates whether the product is delisted

Source Object

FieldTypeRequiredDescription
sourceTypeStringYesType of product source
sourceProductIdStringYesUnique product identifier in the source system
sourceIdStringNoIdentifier of the source account or system
channelTypeStringYesChannel associated with the product source

Price Object

FieldTypeRequiredDescription
valueNumberYes, when price is includedProduct price amount
currencyStringNoCurrency associated with the price amount

Attachment Object

FieldTypeRequiredDescription
typeStringYes, when attachment is includedAttachment type
urlStringNoURL of the attached media
alternateTextStringNoAlternative text for the attachment

Workflow Object

FieldTypeRequiredDescription
assignmentObjectNoAssignment details associated with the product
modifiedTimeIntegerNoWorkflow modification time in epoch milliseconds
customPropertiesMap of String to Array of StringsNoCustom properties associated with the product
queuesArray of ObjectsNoQueue information associated with the product workflow
spaceWorkflowsArray of ObjectsNoWorkspace-level workflows associated with the product

Request

curl --location 'https://api3.sprinklr.com/{env}/api/v3/product' \
  --header 'Authorization: Bearer {Access Token}' \
  --header 'Key: {API Key}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "source": {
      "sourceType": "ACCOUNT",
      "sourceProductId": "SKU-200897",
      "sourceId": "{sourceId}",
      "channelType": "SOURCE_AGNOSTIC"
    },
    "catalogIds": ["{catalogId}"],
    "categoryIds": ["FRAGRANCE"],
    "title": "Sample Product",
    "description": "Sample product description",
    "link": "https://example.com/products/sku-200897",
    "price": {
      "value": 78.00,
      "currency": "USD"
    },
    "groupId": "20097",
    "attachment": {
      "type": "IMAGE",
      "url": "https://example.com/images/product.jpg"
    },
    "workflow": {
      "customProperties": {
        "{customFieldId}": ["New"]
      }
    }
  }'

Response

A successful request returns 201 Created and the newly created product.

{
  "data": {
    "id": "6a9968815d82d94f23d44994",
    "source": {
      "sourceType": "ACCOUNT",
      "sourceId": "{sourceId}",
      "sourceProductId": "SKU-200897",
      "channelType": "SOURCE_AGNOSTIC"
    },
    "catalogIds": ["{catalogId}"],
    "categoryIds": ["FRAGRANCE"],
    "title": "Sample Product",
    "description": "Sample product description",
    "link": "https://example.com/products/sku-200897",
    "price": {
      "value": 78.0,
      "currency": "USD"
    },
    "groupId": "20097",
    "attachment": {
      "url": "https://example.com/images/product.jpg",
      "encryptedUrl": "enc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "type": "IMAGE"
    },
    "workflow": {
      "customProperties": {
        "{customFieldId}": ["New"]
      }
    },
    "delisted": false
  },
  "errors": []
}

4.2 Update a Product

Replaces an existing product with the product definition supplied in the request body. Include all product attributes that you want to retain.

Endpoint

PUT https://api3.sprinklr.com/{env}/api/v3/product?productId={productId}

Query Parameters

ParameterTypeRequiredDescription
productIdStringYesIdentifier of the product to update

Request

curl --location --request PUT \
  'https://api3.sprinklr.com/{env}/api/v3/product?productId={productId}' \
  --header 'Authorization: Bearer {Access Token}' \
  --header 'Key: {API Key}' \
  --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
  }'

Response

HTTP/1.1 204 No Content

The response body is empty.

4.3 Update Product Fields

Updates selected fields in an existing product. Fields not included in the request are preserved.

Endpoint

PATCH https://api3.sprinklr.com/{env}/api/v3/product?productId={productId}

Query Parameters

ParameterTypeRequiredDescription
productIdStringYesIdentifier of the product to update

Supported Request Fields

FieldTypeDescription
titleStringProduct title
descriptionStringProduct description
linkStringProduct URL
standardPriceNumberStandard product price
sellingPriceNumberSelling price
currencyStringProduct price currency
availabilityStringProduct availability status
inventoryIntegerAvailable inventory quantity
gtinStringGlobal Trade Item Number
mpnStringManufacturer part number
brandStringBrand name
retailerIdStringRetailer-specific identifier
skuStringStock keeping unit
groupIdStringIdentifier used to group product variants
specificationMap of String to StringAttributes that distinguish a product variant
subSpecificationMap of String to ObjectAdditional specification attributes
catalogIdsArray of StringsCatalog identifiers
categoryIdsArray of StringsCategory identifiers
attachmentObjectProduct media
workflowObjectProduct workflow properties
delistedBooleanIndicates whether the product is delisted

Request

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

Response

HTTP/1.1 204 No Content

The response body is empty.

4.4 Delete Products

Deletes one or more products. To delete multiple products, supply their identifiers as a comma-separated list.

Endpoint

DELETE https://api3.sprinklr.com/{env}/api/v3/product?productId={productIds}

Query Parameters

ParameterTypeRequiredDescription
productIdStringYesOne product ID or a comma-separated list of product IDs

Delete a Product

curl --location --request DELETE \
  'https://api3.sprinklr.com/{env}/api/v3/product?productId={productId}' \
  --header 'Authorization: Bearer {Access Token}' \
  --header 'Key: {API Key}' \
  --header 'Accept: application/json'

Delete Multiple Products

curl --location --request DELETE \
  'https://api3.sprinklr.com/{env}/api/v3/product?productId={productId1},{productId2}' \
  --header 'Authorization: Bearer {Access Token}' \
  --header 'Key: {API Key}' \
  --header 'Accept: application/json'

Response

HTTP/1.1 204 No Content

The response body is empty.

5. Read Operations

5.1 Fetch Products

Retrieves one or more products. Supply one product ID or a comma-separated list of product IDs.

Endpoint

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

Query Parameters

ParameterTypeRequiredDescription
productIdStringYesProduct identifier or comma-separated list of product identifiers

Fetch a Product

curl --location \
  'https://api3.sprinklr.com/{env}/api/v3/product?productId={productId}' \
  --header 'Authorization: Bearer {Access Token}' \
  --header 'Key: {API Key}' \
  --header 'Accept: application/json'

Fetch Multiple Products

curl --location \
  'https://api3.sprinklr.com/{env}/api/v3/product?productId={productId1},{productId2}' \
  --header 'Authorization: Bearer {Access Token}' \
  --header 'Key: {API Key}' \
  --header 'Accept: application/json'

Response

A successful request returns 200 OK and one or more products in the data array.

{
  "data": [
    {
      "id": "{productId}",
      "source": {
        "sourceType": "ACCOUNT",
        "sourceId": "{sourceId}",
        "sourceProductId": "{sourceProductId}",
        "channelType": "SOURCE_AGNOSTIC"
      },
      "catalogIds": ["{catalogId}"],
      "categoryIds": ["{categoryId}"],
      "title": "Sample Product",
      "description": "Sample product description",
      "link": "https://example.com/products/{sourceProductId}",
      "price": {
        "value": 78.0,
        "currency": "USD"
      },
      "groupId": "{groupId}",
      "attachment": {
        "url": "https://example.com/images/product.jpg",
        "encryptedUrl": "{encryptedUrl}",
        "type": "IMAGE"
      },
      "workflow": {
        "customProperties": {
          "{customFieldId}": ["{customFieldValue}"]
        }
      },
      "delisted": false
    }
  ],
  "errors": []
}

Response Schema

FieldTypeDescription
idStringUnique identifier of the product
sourceObjectSource details associated with the product
catalogIdsArray of StringsCatalog identifiers associated with the product
categoryIdsArray of StringsCategory identifiers associated with the product
titleStringProduct title
descriptionStringProduct description
linkStringProduct URL
priceObjectProduct pricing information
specificationMap of String to StringProduct attributes
groupIdStringProduct group identifier
attachmentObjectProduct media
workflowObjectProduct workflow properties
delistedBooleanIndicates whether the product is delisted

Response Attachment Object

FieldTypeDescription
urlStringAttachment URL
encryptedUrlStringEncrypted attachment URL
typeStringAttachment type

6. Response Format and Status Codes

6.1 V3 Response Envelope

Create and Fetch operations return a response envelope containing data and errors.

Create response:

{
  "data": {},
  "errors": []
}

Fetch response:

{
  "data": [],
  "errors": []
}

6.2 Response Cardinality

Operationdata Type
CreateObject
FetchArray of Objects

6.3 Response Codes

HTTP CodeOperationMeaning
200 OKGETThe requested products were returned
201 CreatedPOSTThe product was created
204 No ContentPUTThe product was replaced
204 No ContentPATCHThe product fields were updated
204 No ContentDELETEThe products were deleted

8. Supported Values

8.1 Source Types

ValueEvidence
ACCOUNTUsed in the request and response examples
EXTERNALListed as an example source type

8.2 Channel Types

ValueEvidence
SOURCE_AGNOSTICUsed in the request and response examples

8.3 Attachment Types

Value
IMAGE
VIDEO
CAROUSEL
LINK
DOC

8.4 Availability Values

ValueEvidence
IN_STOCKUsed in the partial-update example

Additional availability values are not documented in the available source.

9. Use Cases

9.1 Create Products From an External Commerce System

  1. Extract product information from the commerce platform.
  2. Map source identifiers and catalog assignments.
  3. Send a POST request to create each product.
  4. Store the returned product IDs for future operations.

9.2 Synchronize Product Catalogs

  1. Retrieve existing products with GET.
  2. Compare the returned data with the source system.
  3. Use PUT to replace complete outdated records.
  4. Use PATCH to change selected fields.
  5. Delete obsolete products when appropriate.

9.3 Update Inventory and Pricing

Use PATCH when only operational fields change.

{
  "sellingPrice": 69.99,
  "currency": "USD",
  "inventory": 8,
  "availability": "IN_STOCK"
}

9.4 Manage Product Variants

Use:

  • groupId to associate related variants.
  • specification to distinguish products in the same variant group.
  • subSpecification to store additional attributes associated with a specification.

10. Caveats and Best Practices

Choose PUT or PATCH Carefully

  • Use PUT to replace the complete product definition.
  • Use PATCH to update selected fields while preserving omitted fields.

Preserve Fields During PUT

Include every field that you want to retain. PUT replaces the existing product with the submitted payload.

Parse Dynamic Specifications

Treat specification, subSpecification, and workflow.customProperties as dynamic map structures. Do not assume fixed property names.

Support Bulk Operations

GET and DELETE accept comma-separated product IDs. Use bulk operations to reduce API calls when appropriate.

Handle Encrypted Media URLs

Attachment responses can include both url and encryptedUrl. Support both fields in your response model.

Protect Credentials

Use placeholders in examples and store access tokens and API keys securely. Do not commit credentials to source control or application logs.