Variants
RevCascade uses the term "variant" to describe a sellable item. Variants can be enhanced using RevCascade attributes. For example, variants can grouped into products using a "parent identifier" and "parent name" attributes. There are many other attributes as described in the attributes endpoint, including attributes for inventory, product & shipping dimensions, descriptive information, and many others.
Operations
Click on an operation to view requirements, options, & examples.
| GET | /v1/retailers/{retailer_id}/variants/ | Get approved variants |
|---|---|---|
| GET | /v1/retailers/{retailer_id}/variants/{id}/ | Get a single variant |
| PATCH | /v1/retailers/{retailer_id}/variants/{id}/ | Update a single variant |
| PUT | /v1/retailers/{retailer_id}/variants/{id}/acknowledge/ | Acknowledge receipt of new variant |
Variant Properties
| Name | Description |
|---|---|
|
id integer (11) |
A static id assigned by RevCascade. Can be used as the primary key in the url of other variant endpoints. |
|
brand |
The vendor/brand that owns the variant. "brand": {
"id": 1000,
"name": "Demo Brand"
...
}
|
|
name string (200) |
The name of the variant. |
|
identifier string (128) |
The vendor's internal identifier the variant. This value is expected to be unique across all of a vendor's variants. Also, once an identifier is created, it cannot be updated without assistance and coordination from RevCascade. |
|
upc string (64) |
The UPC of the variant (if applicable) |
|
parent_identifier string (100) |
If this variant is similar to other variants, it may be grouped into parent products via the parent_identifier value. |
|
parent_name string (200) |
The name of the parent product. |
|
color string (100) |
The color of the variant. |
|
size string (100) |
The size of the variant. |
|
inventory object |
The current inventory of the variant. If inventory is specified by warehouse, the locations array will be populated with inventory by warehouse. Please contact us to discuss whether supplying inventory by warehouse if beneficial to your use case. "inventory": {
"inventory": 100,
"inventory_updated_at": ""2016-08-01T12:00:000",
"sellable": "Yes",
"sellable_updated_at": "2016-08-01T12:00:000",
"locations": []
}
|
|
media array of objects |
An array of RevCascade-hosted images associated with the variant. "media":[{
"media":"7837bIjdhyTTbd72Nhg9U3dns23bgjs3",
"priority":1,
"url": "https://images.revcascade.com/imagelink"
}]
|
|
attributes array of attributes |
An array of all attributes associated with the variant. The array's keys are attribute codes. Some common attributes (e.g. name, size, color, identifier) have been promoted to be variant properties - these attributes will be repeated in this array. "attributes": [{
"name": {
"id": ,
"code": ,
"name": ,
"grouping": ,
"description": ,
"type": "string",
"units": null
"values": [{
"id": 341324
"value":
}]
}
...
// more attributes
}]
The only attribute guaranteed to return is the "identifier" attribute. Technically, all other attributes are optional. For more information on attributes, consult the attributes documentation. |
|
is_acknowledged boolean |
Boolean flag that indicates whether the variant has been acknowledged by the retailer. When a retailer acknowledges a variant, that indicates that the retailer has received and pulled all necessary attributes. |
Operation Details & Examples
| GET | /v1/retailers/{retailer_id}/variants/ | Get a list of variants |
|---|
| Optional Query String Parameters | |
|
in_stock boolean |
1 - return variants with inventory > 0.
0 - return variants that have inventory of 0. |
|
is_acknowledged boolean |
1 - return variants that have been acknowledged.
0 - return variants that have not been acknowledged. |
|
meets_publish_rules boolean |
1 - return variants that meet merchandising specifications.
0 - return variants that that do not meet merchandising specifications |
|
created_at_{operator} timestamp |
Show variants that were created before or after an epoch timestamp in UTC.
Please substitute {operator} with "lt" (less than),"lte" (less than or equal), "gt" (greater than), or "gte" (greater than or equal). |
|
updated_at_{operator} timestamp |
Show variants that were updated before or after an epoch timestamp in UTC.
Please substitute {operator} with "lt" (less than),"lte" (less than or equal), "gt" (greater than), or "gte" (greater than or equal). |
|
limit integer(3) |
Customize the number of results return (max 250). |
|
Get a list of variants that meet merchandising specifications. GET https://api.revcascade.com/v1/retailers/500/variants/?meets_publish_rules=1 |
|
|
Retreive a list of recently approved variants that meet merchandising specifications. GET https://api.revcascade.com/v1/retailers/500/variants/?meets_publish_rules=1&is_acknowledged=0 |
|
| GET | /v1/retailers/{retailer_id}/variants/{id}/ | Get a single variant. |
|---|
|
Get a variant by its ID GET https://api.revcascade.com/v1/retailers/500/variants/100000/ |
| PATCH | /v1/retailers/{retailer_id}/variants/{id}/ | Update a single variant. |
|---|
| Input Parameters | |
|
attributes array of attributes |
When updating a variant, all input goes into the "attributes" key.
This key expects an array of attribute values.
RevCascade's list of supported attributes is growing. To get a list of available attributes, please consult the attributes documentation. |
|
Update the name of a variant GET https://api.revcascade.com/v1/retailers/500/variants/100000/
{
"attributes": [
{
"attribute": {
"code": "name"
},
"value": "The Best Thing Ever v2"
}
]
}
|
|
|
Update the variant's name AND add a retailer SKU GET https://api.revcascade.com/v1/retailers/500/variants/100000/
{
"attributes": [
{
"attribute": {
"code": "name"
},
"value": "Best Thing Ever v2"
},{
"attribute": {
"code": "retailer_sku"
},
"value": "RETSKU-123"
}
]
}
|
|
| PUT | /v1/retailers/{retailer_id}/variants/{id}/acknowledge/ | Acknowledge receipt |
|---|
|
Acknowledge receipt of a new variant. PUT https://api.revcascade.com/v1/retailers/500/variants/123645/acknowledge/ |