The Catalogs API provides an easy, seamless integration between your product merchandising system and Optoro's platform. This ensures that all catalog entries are up to date with the highest quality product information. Optoro can then disposition and route returned items, ensuring retailers receive maximum recovery at the highest possible velocity.
Data Handling
The Catalogs API is intended to be updated in real time from your merchandising system. For large, initial catalog data transfers, Optoro recommends a CSV file transfer. For ongoing maintenance, Optoro recommends utilizing the Catalogs API.
When submitting catalog data, Optoro will perform minimal validation. Data sent to the API will be treated as accurate. Null or empty values will be saved and can overwrite previously submitted data. If this is not desired then omit the field from the update request.
Custom Fields
You may submit additional product fields to the Catalogs API. These fields will be made available for dispositioning, routing, reporting, and other decision making within OptiTurn.
For example, if you have products that are customizable, you might include a customizable boolean field in your catalog updates. This field could then be used to route customizable items to the appropriate channel.
You must work with Optoro's Client Success team to configure this feature.
Create / Update Catalog Entry
A catalog entry is identified by its SKU. If the Catalogs API cannot locate the SKU, a new catalog entry is created. If the SKU is located, the catalog entry is updated with the provided payload.
SecurityoAuth2
Request
Request Body schema: application/json
object
One of:
Any of:
wholesale_price_cents
required
integer or null
Wholesale price represented in US cents. Either wholesale or retail price is required.
sku
required
string (sku) non-empty
A catalog entry's SKU. This value must be unique. If you are using concepts (see below), then the SKU must be unique across all catalog entries for the concept. If not using concepts, the SKU must be unique across your entire catalog.
upc
string (upc) ^[0-9]{8}([0-9]{4,6})?$
Deprecated
Product UPC. Must be provided if receiving against UPCs. A valid UPC contains either 8, 12, 13, or 14 characters. A UPC can only belong to a single SKU. When updating a Catalog Entry, providing UPC(s) will replace any existing UPCs associated with the SKU. To append to the list of associated UPCs instead of replacing it, see the append_upcs parameter below.
This field is deprecated and will be replaced in a future API version.
upcs
Array of strings (upc)
Deprecated
List of product UPCs. The provided list will replace any existing UPCs associated with the SKU. To append to the list of associated UPCs instead of replacing it, see the append_upcs parameter below. Use this field as an alternative to the single upc field above.
This field is deprecated and will be replaced in a future API version.
append_upcs
boolean
Deprecated
If set to true, any UPCs in the same payload will be appended to (rather than replacing) UPCs already assigned to an existing Catalog Entry.
This field is deprecated and will be replaced in a future API version.
concept
string or null
A unique identifier for the retail ‘concept’ or ‘brand’ to which the product belongs. This differentiates similar products when the your company has multiple retail concepts. Must work with Professional Services when using this field to uniquely identify catalog entries.
merchant
string or null
The name of the merchant that sells the product. Used to differentiate products when your company supports multiple merchants.
title
required
string
Complete product name.
description
string or null
Detailed product description.
retail_price_cents
integer or null
Retail price represented in US cents. Either wholesale or retail price is required. Retail price is required for units to be drop shipped.
msrp_cents
integer or null
Manufacturer's suggested retail price.
category
required
string
Root of the product taxonomy (e.g. Toys, Clothing, etc.). Can be a name or identifier.
When updating categories for a SKU, a request must contain all parent values. For example, if leaf_category is provided, category and subcategory must be provided. If subcategory is provided, then category must be provided.
category_name
string
If the category field represents an external identifier (i.e. an identifier coming from the your system), the cateogry_name field should include the name. If the category field represents a name, then the cateogry_name field can be omitted.
subcategory
required
string
Extend the product taxonomy. Must also include category. Can be a name or identifier.
subcategory_name
string
If the subcategory field represents an external identifier (i.e. an identifier coming from the your system), the subcateogry_name field should include the name. If the subcategory field represents a name, then the subcateogry_name field can be omitted.
leaf_category
string
Extend the product taxonomy further. Must also include category and subcategory. Can be a name or identifier.
leaf_category_name
string
If the leaf_category field represents an external identifier (i.e. an identifier coming from the your system), the cateogry_name field should include the name. If the leaf_category field represents a name, then the cateogry_name field can be omitted.
manufacturer
string or null
Name of product’s manufacturer.
part_number
string or null
Part number.
model_number
string or null
Model number.
asin
string or null
Deprecated
10-character alphanumeric unique identifier assigned by Amazon.com and its partners for product.
This field is deprecated and will be replaced in a future API version.
url
string or null <= 256 characters
Product image url. Should use https. Images should have a minimum of 500px for height or width.
color
string or null
Product color.
inspection_notes
string or null
Custom instructions for the Test and Grade process
size
string or null
Product size.
length
number or null
Unboxed product length in inches.
width
number or null
Unboxed product width in inches.
height
number or null
Unboxed product height in inches.
weight
number or null
Unboxed product weight in pounds.
object or null
The dimensions of the boxed product during shipment. Always in inches and pounds.
shipping_length
number or null
Boxed product shipping length in inches.
shipping_width
number or null
Boxed product shipping width in inches.
shipping_height
number or null
Boxed product shipping height in inches.
shipping_weight
number or null
Boxed product shipping weight in pounds.
object or null
Information about hazardous materials must be provided if present in a product. This information influences dispositioning decisions, determines how a product can be shipped, and indicates the type of packaging and labeling required on products. If a product contains no hazardous material, the entire hazmat object can be omitted.
battery
string or null
An object describing the type of battery.
Note: This field is only for lithium ion batteries that are <= 100 Wh or lithium ion cells that are <= 20 Wh and lithium metal batteries <=2g of lithium metal or cells <=1g of lithium metal
Enum:"lithium ion battery only""lithium ion packed with equipment""lithium ion contained in equipment""lithium ion button/coin cell shipped installed""lithium metal battery only""lithium metal packed with equipment""lithium metal contained in equipment""lithium metal button/coin cell shipped installed"null
shipped_under_DOT_as
string or null
Please refer to Title 49 of the Code of Federal Regulations for hazmat handling as required by the Department of Transportation for shipping hazardous materials within the US via ground.
A list of fully regulated hazmat components in the product. One object per component.
You should provide data in this object if "Fully-Regulated" is provided or otherwise applicable values are provided into shipped_under_DOT_as, shipped_under_IATA_as, or shipped_under_IMDG_code_as indicating a product as a hazardous material or dangerous good.
Note: fully regulated components will impact product disposition at the discretion of Optoro.
Array
hazard_class_or_division
string or null
Department of Transportation hazard class. Will accept number values with up to one decimal place.