Catalog Update API

Request Legend

Note:  All property names are case sensitive.

Example Request

[
  {
    "id": "123",
    "name": "Playstation 4",
    "categories": ["E495", "VG555"],
    "brand": "Sony",
    "price": 299.99,
    "recommendable": true,
    "image_url": "http://my.cdn.com/path/to/my/image/123.jpg",
    "link_url": "http://my.domain.com/path/to/my/product/detail/123.html",
    "start_date": "2016-02-28"
  },
  {
    "id": "124",
    "name": "XBox One",
    "categories": ["E495", "VG555"],
    "brand": "Microsoft",
    "price": 249.99,
    "recommendable": true,
    "image_url": "http://my.cdn.com/path/to/my/image/124.jpg",
    "link_url": "http://my.domain.com/path/to/my/product/detail/124.html",
    "start_date": "2016-07-28",
    "included_games": ["Destiny", "Final Fantasy XV"]
  }
]

Example Request

[
  {
    "id": "123",
    "name": "Playstation 4",
    "categories": ["E495", "VG555"],
    "brand": "Sony",
    "price": 299.99,
    "recommendable": true,
    "image_url": "http://my.cdn.com/path/to/my/image/123.jpg",
    "link_url": "http://my.domain.com/path/to/my/product/detail/123.html",
    "start_date": 2016-02-28,
    "overrides": {
      "region": {
        "CA": {
          "properties": {
            "in_stock": true
          }
        },
        "WA": {
          "properties": {
            "in_stock": false
          }
        }
      }
    }
  },
  {
    "id": "124",
    "name": "XBox One",
    "categories": ["E495", "VG555"],
    "brand": "Microsoft",
    "price": 249.99,
    "recommendable": true,
    "image_url": "http://my.cdn.com/path/to/my/image/124.jpg",
    "link_url": "http://my.domain.com/path/to/my/product/detail/124.html",
    "start_date": 2016-07-28,
    "included_games": ["Destiny", "Final Fantasy XV"],
    "overrides": {
      "region": {
        "CA": {
          "properties": {
            "in_stock": true
          }
        },
        "WA": {
          "properties": {
            "in_stock": false
          }
        }
      }
    }
  }
]

Request Legend

IMPORTANT: To include a custom attribute inside a region, it must also be present in the base product. Example:

[
  {
    "id": "123",
    "name": "Playstation 4",
    "categories": ["E495", "VG555"],
    "brand": "Sony",
    "price": 299.99,
    "recommendable": true,
    "image_url": "http://my.cdn.com/path/to/my/image/123.jpg",
    "link_url": "http://my.domain.com/path/to/my/product/detail/123.html",
    "start_date": 2016-02-28,
    "sizes": ["XS","S","M","L","XL"],
    "overrides": {
      "region": {
        "CA": {
          "properties": {
            "in_stock": true,
            "sizes": ["M","L"]
          }
        },
        "WA": {
          "properties": {
            "in_stock": false,
            "sizes": ["XS","L","XL"]
          }
        }
      }
    }
  }
]

Example Request

[
  {
    "id": "123",
    "name": "Playstation 4",
    "categories": ["E495", "VG555"],
    "brand": "Sony",
    "price": 299.99,
    "recommendable": true,
    "image_url": "http://my.cdn.com/path/to/my/image/123.jpg",
    "link_url": "http://my.domain.com/path/to/my/product/detail/123.html",
    "start_date": 2016-02-28,
    "overrides": {
      "sku": {
        "123A": {
          "properties": {
            "color": "black"
          }
        },
        "123B": {
          "properties": {
            "color": "red"
          }
        }
      }
    }
  },
  {
    "id": "124",
    "name": "XBox One",
    "categories": ["E495", "VG555"],
    "brand": "Microsoft",
    "price": 249.99,
    "recommendable": true,
    "image_url": "http://my.cdn.com/path/to/my/image/124.jpg",
    "link_url": "http://my.domain.com/path/to/my/product/detail/124.html",
    "start_date": 2016-07-28,
    "included_games": ["Destiny", "Final Fantasy XV"],
    "overrides": {
      "sku": {
        "124A": {
          "properties": {
            "size": "small",
            "color": "black"
          }
        },
        "124B": {
          "properties": {
            "size": "large",
            "color": ["black", "gold"]
          }
        }
      }
    }
  }
]

Request Legend

SKU Size Types

When you’re considering size preference for a shopper, you need to be able to differentiate between different types of sizes. A single shopper might wear size 8 shoes, size 4 dresses, and size S t-shirts. But if the only information given to the system is the sizes themselves, there may be unnecessary confusion between them.

When the shopper buys a pair of shoes, for example, it’s not enough to record that this shopper is a size 8. You need to know that the shopper is an 8 in shoes because you don’t want to later recommend size 8 dresses to that same shopper.

If you are able to send sizes as unique attributes like shirt_size, hat_size, or us_women_shoe_size for example, no further work is needed; that will be enough to keep this information appropriately separated and unconfused.

If you are not able to do this, then there is a workaround. You can create an attribute called SizeType to differentiate between the different types of sizes represented in your catalog. You then associate this parameter with each product in the SKU feed and can be log it each time a user shows a preference for a size. 

Request Legend

Note:  All property names are case sensitive.

Example Request

[
  {
    "id": "E495",
    "name": "Electronics"
  },
  {
    "id": "VG555",
    "parent_id": "E495",
    "name": "Video Games"
  }
]

Example Request

[
  {
    "id": "E495",
    "name": "Electronics",
    "link_url": "/Electronics.html",
    "image_url": "/Electronics.jpg",
    "overrides": {
      "language": {
        "en-US": {
          "properties": {
            "name": "Electronics",
            "link_url": "/en-US/Electronics.html",
            "image_url": "/en-US/Electronics.jpg"
          }
        },
        "fr-CA": {
          "properties": {
            "name": "Électronique",
            "link_url": "/fr-CA/Electronics.html",
            "image_url": "/fr-CA/Electronics.jpg"
          }
        }
      }
    }
  },
  {
    "id": "VG555",
    "parent_id": "E495",
    "name": "Video Games",
    "overrides": { ... }
  }
]

Request Legend 

Request Legend

Note: All property names are case sensitive.

Example Request

{
  "myRegion1": {
    "name": "Name of region 1",
    "description": "Description of region 1",
    "currency_code": "USD",
    "language_tag": "en-US",
    "price_multiplier": 100,
    "price_prefix": "$",
    "price_suffix": ""
  },
  "myRegion2": {
    ...
  },
  ...
}

Tip: You can confirm that this region information has been successfully added by opening a new Browse Boosting rule creation screen, choosing Region as the context, and clicking on the dropdown list of eligible regions. If the feed has run correctly, you should see all of the regions you just added, displayed by title.

Request Legend

Note:  All property names are case sensitive.

Example Request for Products or Categories

[
  {"id": "myProduct1"},
  {"id": "myProduct2"},
  ...
]

Example Request for Regions

{
  "myRegion1": null,
  "myRegion2": null,
  ...
}

Why the difference between products, categories and regions? Regions was developed after we formalized our standards for what will be the version 2 API. Regions follows these newer standards. For regions there will be fewer changes required when moving to the version 2 API.

Response Legend

Example Response

[
  {
    "trackingId": "YOUR_TRACKING_ID",
    "submitted": "2016-02-28T16:41:41.090Z",
    "statusMessage": {
      "status": "FINISHED",
      "notes": "Additional notes to explain status."
    }
  }
]

Response Legend

Example Response

{
  "status": "FINISHED",
  "notes": "Additional notes to explain status."
}