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.
Change Log
Version 2023-08-01
FEATURE: The catalog_entry_updates endpoint now accepts a product_identifiers field. This enables the following:
UPCs no longer have length validations.
Multiple ASINs can be associated with the same catalog entry.
UPCs can now be associated with multiple catalog entries.
Update behavior can be specified: either append or replace existing UPCs/ASINs.
BREAKING: The upc, upcs, and asin fields are no longer accepted by the catalog_entry_updates endpoint. * BREAKING: allowed_channels and disallowed_channels are truly mutually exclusive on the
catalog_entry_updates endpoint.
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
header Parameters
Optiturn-Catalogs-Version
required
string
The version of the API to use. Must specify '2023-08-01' to use the current API version. Defaults to '2018-05-10' if omitted.
Request Body schema: application/json
Wholesale Price Cents (object) or Retail Price Cents (object)
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.
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 non-empty
Complete product name.
description
string or null
Detailed product description.
object
required
Array of objects
A list of product identifiers that should be associated with the catalog entry.
Array
value
required
string
A barcode or other value that can uniquely identify a product.
type
string
Default: "generic"
The kind of product identifier. Can be one of the following: - upc - Universal Product Code. A barcode number that is ususally 8, 12, 13, or 14 characters. - asin - Amazon Standard Identification Number. A 10-character alphanumeric unique identifier assigned by Amazon.com. - generic - a catch-all if the type is unknown, should be avoided.
Enum:"upc""asin""generic"
update_behavior
string
Default: "append"
Determines how to handle product identifiers (e.g. UPCs, ASINs) already associated with this catalog entry from previous requests.
append: Existing list of associated product identifiers is preserved and appended to. - replace: Existing list of associated product identifiers is removed and replaced.
Enum:"append""replace"
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.
outlet_price_cents
integer or null
category
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 category_name field can be omitted.
subcategory
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 subcategory_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.
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.