Benchmark Product API - V3.0.1 (5/6/2022)

Necessary Headers

The following headers should be sent with each request. Any headers specific to a single endpoint will be noted below.

api-token: '<your-token>'
accept-encoding: 'gzip, deflate, br'

https://api.benchmarkrings.com/v3/products

Returns all active products.

• sku - unique to simple product and can be used as primary key
• price - retail price (In previous versions of the API this field was called cost and markups were applied on the vendors' side; however, this value can now be displayed as is.)
• size - finger size
• brand - most people call this designer
• style - group simple products to create a configurable product based on this field
• title - displayable name of product
• video - optional and may be returned as null or empty string for some products
• width - width of ring
• family - used to group related products (typically shown on each product page)
• images - length will vary from product to product (We do not guarantee deliverability, so please continue to download and host these images.)
  • url - download location
  • updatedAt - used to determine when image should be refetched
• gemStones - gem stone info (diamond, ruby, sapphire, etc)
• metalTypes - metals contained in product
• previewID - use this value to build the preview url (template is provided in brand map)
• isPreviewable - indicates whether preview link should be shown or not
• collection - used to group products in each brand
• isActive - indicates whether product should be listed or unlisted
• description - displayable description of product
• prices - displayable prices with conversion rates and markups applied (Currently only CAD and USD. Rates updated every night at 12:00 AM)

Any images not included in the array should be removed from the product. ring_<style_number>_<image_number> can be used as the image key. Images will not be renumbered upon deletion. e.g. Given the product response below, suppose image 1 had been deleted. The next response would return ring_CF98486CC_2, ring_CF98486CC_3, and ring_CF98486CC_4.

[
  {
    "previewID": 6206,
    "sku": "CF98486CC06",
    "size": 6.0,
    "brand": "Forge",
    "collection": "Cobalt",
    "price": 1080.0,
    "style": "CF98486CC",
    "title": "THE CARTER",
    "video": "https://youtu.be/K9ByWfEJHTE",
    "width": 8.0,
    "family": 583,
    "images": [
      {
        "url": "https://assets.benchmarkrings.com/benchmark_rings/ring_CF98486CC_1_original.jpg?1612808357",
        "updatedAt": "2021-02-08T18:19:17.268Z"
      },
      {
        "url": "https://assets.benchmarkrings.com/benchmark_rings/ring_CF98486CC_2_original.jpg?1612808357",
        "updatedAt": "2021-02-08T18:19:17.815Z"
      },
      {
        "url": "https://assets.benchmarkrings.com/benchmark_rings/ring_CF98486CC_3_original.jpg?1612808358",
        "updatedAt": "2021-02-08T18:19:18.575Z"
      },
      {
        "url": "https://assets.benchmarkrings.com/benchmark_rings/ring_CF98486CC_4_original.jpg?1613154720",
        "updatedAt": "2021-02-12T18:32:00.429Z"
      }
    ],
    "gemStones": [
      {
        "type": "Diamond",
        "count": 3,
        "properties": {
          "color": "GH",
          "weight": 0.18,
          "clarity": "SI1-2",
          "setting": "burnish"
        }
      }
    ],
    "metalTypes": [
      "Cobalt"
    ],
    "description": "8mm, Comfort fit\nWhite Cobalt\nSatin finish center, polished bevel edges\n3 burnish set diamonds \nCarat weight is .18ct\nClarity SI1-2, Color GH\n",
    "isPreviewable": true,
    "isActive": true,
    "prices": [
      {
        "price": 1840,
        "currencyCode": "CAD"
      },
      {
        "price": 1080,
        "currencyCode": "USD"
      }
    ]
  }
]

https://api.benchmarkrings.com/v3/products/2022-03-20T0:00:00

Returns all products created/updated after the provided datetime.

Note that inactivated products will only have a SKU and isActive flag.

[
  {
    "previewID": 6206,
    "sku": "CF98486CC06",
    "size": 6.0,
    "brand": "Forge",
    "collection": "Cobalt",
    "price": 1080.0,
    "style": "CF98486CC",
    "title": "THE CARTER",
    "video": "https://youtu.be/K9ByWfEJHTE",
    "width": 8.0,
    "family": 583,
    "images": [
      {
        "url": "https://assets.benchmarkrings.com/benchmark_rings/ring_CF98486CC_1_original.jpg?1612808357",
        "updatedAt": "2021-02-08T18:19:17.268Z"
      },
      {
        "url": "https://assets.benchmarkrings.com/benchmark_rings/ring_CF98486CC_2_original.jpg?1612808357",
        "updatedAt": "2021-02-08T18:19:17.815Z"
      },
      {
        "url": "https://assets.benchmarkrings.com/benchmark_rings/ring_CF98486CC_3_original.jpg?1612808358",
        "updatedAt": "2021-02-08T18:19:18.575Z"
      },
      {
        "url": "https://assets.benchmarkrings.com/benchmark_rings/ring_CF98486CC_4_original.jpg?1613154720",
        "updatedAt": "2021-02-12T18:32:00.429Z"
      }
    ],
    "gemStones": [
      {
        "type": "Diamond",
        "count": 3,
        "properties": {
          "color": "GH",
          "weight": 0.18,
          "clarity": "SI1-2",
          "setting": "burnish"
        }
      }
    ],
    "metalTypes": [
      "Cobalt"
    ],
    "description": "8mm, Comfort fit\nWhite Cobalt\nSatin finish center, polished bevel edges\n3 burnish set diamonds \nCarat weight is .18ct\nClarity SI1-2, Color GH\n",
    "isPreviewable": true,
    "isActive": true,
    "prices": [
      {
        "price": 1840,
        "currencyCode": "CAD"
      },
      {
        "price": 1080,
        "currencyCode": "USD"
      }
    ],
  },
  {
    "sku": "CFBP846561314KW04",
    "isActive": false
  }
]

https://api.benchmarkrings.com/v3/brands

Returns each of the retailers (and their standard info) associated with your API token

• name - name of retailer
• website - retailer's online storefront
• brands - brands that retailer has access to
• previewURLTemplate - to be displayed on each product page (when given and ring.isPreviewable = true)
  • If a retailer has access to an in store preview for a given brand, the in store preview URL will be returned and the <ringPreviewID> should be replaced with each product's previewID. Otherwise, the value will be null
• appointmentURL - to be displayed on each product page (when no previewURLTemplate or ring.isPreviewable = false)
  • This key will always exist with a value. The url does not need to be transformed.

[
  {
    "name": "Test Store",
    "website": "teststore.com",
    "brands": ["Brand 1", "Brand 2"],
    "previewURLTemplate": "https://www.benchmarkrings.com/in-store-preview?ring_id=<ringPreviewID>&retailer_id=1234",
    "appointmentURL": "https://www.benchmarkrings.com/book-appointment?retailer_id=1234"
  },
  {
    "name": "Test Store 2",
    "website": "teststore2.com",
    "brands": ["Brand 2"],
    "previewURLTemplate": null,
    "appointmentURL": "https://www.benchmarkrings.com/book-appointment?retailer_id=1235"
  }
]