Products & Variants
Please note: the RevCascade variants endpoint is currently in beta. While the request & response signatures are unlikely to materially change, some optimizations may occur in the coming weeks.
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.
When creating a variant, only the identifier attribute is required - all other attributes are optional. However, if you are planning on leveraging RevCascade to post new products to retailers, many more attributes willl be required.
Operations
Click on an Operation to view requirements, options, & examples.
| POST | /v1/brands/{brand_id}/variants/ | Create a new variant |
|---|---|---|
| GET | /v1/brands/{brand_id}/variants/ | Get a list of variants |
| GET | /v1/brands/{brand_id}/variants/{id}/ | Get a single variant |
| PATCH | /v1/brands/{brand_id}/variants/{id}/ | Update a single variant |
Variant Properties
| id | A static id assigned by RevCascade. Can be used as the primary key in the url of other variant endpoints. |
|---|---|
| brand |
The Supplier that owns the variant. {
"id": "1083",
"name": "Demo Supplier"
}
|
| name | The name of the variant. |
| identifier | The supplier's internal identifier the variant. This value is expected to be unique across all of a supplier's variants. Also, once a identifier is created, it cannot be updated. |
| upc | The UPC of the variant (if applicable) |
| parent_identifier | If this variant is similar to other variants, it is grouped into parent products via the parent_identifier value. |
| parent_name | The name of the parent product. |
| color | The color of the variant. |
| size | The size of the variant. |
| inventory |
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 |
An array of RevCascade-hosted images associated with the variant. "media":[{
"media":"7837bIjdhyTTbd72Nhg9U3dns23bgjs3",
"priority":1,
"url": "https://images.revcascade.com/imagelink"
}]
|
| attributes |
An object of all attributes associated with the item. The object'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 object. "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. |
Examples
| POST | /v1/brands/variants/ | Create a Variant |
|---|
| Input Parameters | |
| attributes |
When creating a variant, all input goes into the "attibutes" key.
This key accepts an array of attribute values. The "identifier" attribute
is the only attribute that MUST be included. All other attributes are optional.
RevCascade's list of supported attributes is growing. To get a list of available attributes, please consult the attributes documentation. |
|---|---|
|
Create a new variant with only a 'name' and 'identifier' POST https://api.revcascade.com/v1/brands/500/variants/
{
"attributes": [
{
"attribute": {
"code": "name"
},
"value": "The Best Thing Ever"
},{
"attribute": {
"code": "identifier"
},
"value": "SKU-1234"
}
]
}
|
|
|
Create a new variant with a recommended, but still pretty light, set of attributes POST https://api.revcascade.com/v1/brands/500/variants/
{
"attributes": [
{
"attribute": {
"code": "name"
},
"value": "The Best Thing Ever"
},{
"attribute": {
"code": "identifier"
},
"value": "SKU-1234"
},{
"attribute": {
"code": "inventory"
},
"value": 100
},{
"attribute": {
"code": "image_1"
},
"value": "http:://imagehost.com/link-to-image-file"
},{
"attribute": {
"code": "manufacturer"
},
"value": "Best Builders"
},{
"attribute": {
"code": "manufacturer_part_number"
},
"value": "BTE-2016"
},{
"attribute": {
"code": "cost"
},
"value": 150.00
},{
"attribute": {
"code": "msrp"
},
"value": 299.00
},{
"attribute": {
"code": "lead_time"
},
"value": 2
},{
"attribute": {
"code": "ships"
},
"value": "Small Parcel"
},{
"attribute": {
"code": "shipping_width"
},
"value": 12.00
},{
"attribute": {
"code": "shipping_height"
},
"value": 6.00
},{
"attribute": {
"code": "shipping_length"
},
"value": 19.5
},{
"attribute": {
"code": "shipping_weight"
},
"value": 15.00
}
]
}
|
|
| GET | /v1/brands/{brand_id}/variants/ | Get a list of variants |
|---|
| Optional Query String Parameters | |
| short |
1 - return a limited set of attributes (can speed up requests)
0 - return all attributes associated with the variants. |
|---|---|
| in_stock |
1 - return variants with inventory > 0.
0 - return variants that have inventory of 0. |
| has_images |
1 - return only variants that have images associated with them.
0 - return variants that are missing images. |
| has_shipping |
1 - return only variants that have package sizes and weights.
0 - return variants that are missing shipping information. |
| attribute |
Filter results based on a free-text search against a limited set of attributes. The format is "attribute=code[value1||value2||value3]" Please makes sure to URL-encode the value before sending. Searchable attributes include:
|
| created_at_{operator} |
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} |
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 | Customize the number of results return (max 250). |
|
Get a list of variants missing shipping dimensions (e.g. package sizes and weights) GET https://api.revcascade.com/v1/brands/500/variants/?short=1&has_shipping=0 |
|
|
Get a list of blue and red variants in XL (remember to url encode) GET https://api.revcascade.com/v1/brands/500/variants/?short=1&attribute=color[red||blue]::size[xl] |
|
| GET | /v1/brands/{brand_id}/variants/{id}/ | Get a single variant. |
|---|
|
Get a variant by its ID GET https://api.revcascade.com/v1/brands/500/variants/100000/ |
| PATCH | /v1/brands/variants/{id}/ | Update a single variant |
|---|
| Input Parameters | |
| attributes |
When updating a variant, all input goes into the "attibutes" key.
This key accepts an array of attribute values. The "identifier" attribute
is the only attribute CANNOT BE UPDATED.
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 PATCH https://api.revcascade.com/v1/brands/500/variants/100000/
{
"attributes": [
{
"attribute": {
"code": "name"
},
"value": "The Best Thing Ever v2"
}
]
}
|
|
|
Update the variant's name AND add a retailer-specific item # & name mapping POST https://api.revcascade.com/v1/brands/500/variants/100000/
{
"attributes": [
{
"attribute": {
"code": "name"
},
"value": "Best Thing Ever v2"
},{
"attribute": {
"code": "retailer_item"
},
"retailer": {
"id": 1000
}
"value": "RETSKU-123"
},{
"attribute": {
"code": "retailer_item_name"
},
"retailer": {
"id": 1000
}
"value": "Best Thing Ever (Latest Generation)"
}
]
}
|
|
