products

The products API retrieves a list of products for an account.

Parameters

api_key (string) Required - The API key for the account
last_updated_at (datetime) Optional - If this parameter is supplied, only products whose last edited date is after the supplied date and time will be returned. The parameter should be formatted as "YYYY-MM-DD HH:MM:SS" and will be interpreted as a UTC date and time value.
page (int) Optional - This is ignored if per_page is not supplied. Asks for the page derived from the pagination behavior triggered off by the per_page parameter.
per_page (int) Optional - If this parameter is supplied, the response object will be split into pages, each with per_page products. Each page can be retrieved by supplying the appropriate page attribute. If this parameter is not supplied, all products are returned.

Notes on Pagination Parameters

It is expected that clients calling the products API must always:

call successive pages sequentially, and commit all changes to a page before calling the next page
only call for page X+1 after page X, never skipping a page number
supply a last_updated_at parameter for every request after page 1.

Relationship to Product SKUs

product_skus are retrieved via the /product_list_groups API. Each product can have many product_skus, but each product_sku must belong to a single product.

Response

The products API returns a JSON array of products objects. Each member object of the array includes these attributes:

accolades (array) - Array of accolades for this product. Each accolade is characterized by the accolade attributes below.
characteristics (array) - Array of objects to display as important characteristics of the SKU. See below for more details
details (array) - Array of objects to display as details on the 1-up view. See below.
hidden_search_terms (string) - Search terms for which this product should be returned. This attribute is not displayed on the Tastevin iOS user interface.
id (int) - Unique identifier.
paired_menu_item_ids (array) - Array of integers, where each integer is a menu item ID with which this product is paired. The order of pairings is determined by the ordinal of the specific menu_items and its corresponding menu_section.
rating_source (string) - Source of the rating (if any).
rating_value (string) - Single alphanumeric rating.
secondary_image_text (string) - Text to display with secondary image, if any (such as "this cocktail features").
should_display_secondary_image_1up - Boolean that indicates whether to display the secondary image on the 1-up view.
subtitle_1 (string) - First subtitle for the SKU
subtitle_2 (string) - Second subtitle for the SKU
subtitle_3 (string) - Third subtitle for the SKU
subtitle_4 (string) - Fourth subtitle for the SKU
tags (array) - Array of integer tags for the SKU
title (string) - The main title for the SKU
updated_at (string) - The date that this SKU was last edited.

Characteristic attributes

There can be from zero to four characteristics describing a product. If the product has a secondary image, then at most the first two characteristics will be displayed.

key - The display name of the characteristic.
value - The value of the characteristic, properly formatted for the iOS user interface.
ordinal - The order of the characteristic in the list of characteristics.

Unit attributes

If only a single unit is given, then the name of that unit will display on the iOS user interface. If an array of units is given, the iOS user interface will build a table of units.

id (int) - Identifier for a beverage SKU unit for this SKU.
ordinal (int) - The order of the unit in the list of units.

Accolade attributes

id (int) - Unique identifier.
updated_at (string) - The date that this accolade was last edited.
author (string) - The author of the accolade.
body (string) - The text of the accolade.
published_at (string) - The date of publication of this accolade.
source (string) - The source of this accolade.
title (string) - The title of this accolade.

Details attributes

title (string) - The title of the detail section.
text (string) - The text of the detail section.
footer (string) - The footer of the detail section.
style (int) - An enumeration specifying the format of the detail section. This can be 0 for default format or 1 for sommellier notes format.
ordinal (int) - The order of this detail object with respect to all other details objects

Sample Request

https://dashboard.onpremisewine.com/products.json?api_key=ABCDEF123456&page=2&per_page=100

Sample Response

{
  "products": [
    {
      "accolades": [
        {
          "id": 3784,
          "updated_at": "2012-06-30T18:27:33-07:00",
          "author": "John Johnson",
          "body": "This is an amazing pizza",
          "published_at": null,
          "source": null,
          "title": null
          }
      ],
      "characteristics": [
        {
          "key": "protein",
          "value": "20g",
          "ordinal": 1
        },
        {
          "key": "fat",
          "value": "30g",
          "ordinal": 2
        },
        {
          "key": "carbs",
          "value": "70g",
          "ordinal": 3
        }
      ],
      "details": [
        {
          "title": "description",
          "text": "This is a fabulous slice, piled high with meat!",
          "footer": null,
          "style": 0
        },
        {
          "title": "nutrition info",
          "text": "Don't ask, don't tell",
          "footer": null,
          "style": 1
        }
      ],
      "id": 17843,
      "hidden_search_terms": "stroke heartburn",
      "paired_menu_item_ids": [
        23554,
        23557
      ],
      "rating_source": "Pizza Advocate",
      "rating_value": "A+",
      "secondary_image_text": null,
      "should_display_secondary_image_1up": false,
      "subtitle1": "US Pepperoni Company",
      "subtitle2": "1985 calories per slice",
      "subtitle3": null,
      "subtitle4", null,
      "tags": [
        1,
        10
      ],
      "title": "Great Meat Pizza",
      "updated_at": "2012-06-30T18:27:33-07:00",
    }
  ]
}