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

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": []
}
  • inventory - the current number of units on hand and ready to ship.
  • inventory_updated_at - the timestamp when inventory was last updated.
  • sellable - always 'Yes' for now.
  • locations - inventory by warehouse location.

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"
}]
  • media - md5 hash of the media file
  • priority - the ordinal position of the image.
  • url - an "https" url to the media file hosted by RevCascade

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.

Back to Top

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

Back to Top

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/

Back to Top

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"
    }
  ]
}

Back to Top

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/

Back to Top

powered by