Overview

The products collection contains all product data related to a product catalog. It's a supplemental collection designed specifically to accommodate product data. The most common product-related attributes are provided by default as part of the schema.

• API set name: products

Related collections

The following resource collections are associated to this collection.

POST/products

• *Required

  Parameter	Type	Description	Example
  Product
  *productID	string	Unique identifier for a product.	AC30
  *productName	string	The name of the product.	Acme-30 Stapler
  productType	string	The product type. Options include physical, digital, subscription and event.	physical
  price	float	The current price of the product.	35.99
  UPCCode	string	The Universal Product Code assigned to the product.	8 34460 00372 4
  category	string	The category given to the particular item.	Office Supplies
  description	string	A description of the product.	Reliable for up to 20 pages!
  images	array	An array of image file locations	http://example.com/images/123
  manufacturerName	string	The name of the manufacturer.	Acme Supplies
  inStock	boolean	Flags product as in stock. Options are true or false or 1 or 0. The default is false.	1
  taxable	boolean	Flags product as taxable. Options are true or false or 1 or 0. The default is false.	1
  enabled	boolean	Flags product as enabled. Options are true or false or 1 or 0. The default is false.	1
  url	string	A URL to the product page	http://acme.com/ac30
  tags	array	A comma separated array of values to describe the product	"office","office supplies"
  properties	object	An schema-less object of metadata about a product (as key value pairs).	{"hasVideo": true, "ratings": "5 stars"}
  Variants (array)
  *sku	string	The Stock Keeping Unit value for the product.	RF-WP33286-21
  attr	object	An schema-less object of metadata about a variant (as key value pairs).	{"color": "blue", "size": "medium"}
  qty	integer	The available inventory.	1
  Sale (object)
  enabled	boolean	Flag to determine if the sale is enabled or active. Options are true or false or 1 or 0. The default is false.	false
  price	float	The item's sale price.	12.95
  start	date	The date and time the sale is in effect or active.	2015-01-09 17:47:43
  end	date	The date and time the sale ends or goes inactive.	2015-01-09 17:47:43

• Simple example (minimum requirements)

  {
      "productID": "AC30",
      "productName": "Acme-30 Stapler"
  }

  Kitchen sink example (optional fields included)

  {
      "productID": "AC30",
      "productName": "Acme-30 Stapler",
      "variants": [
          {
              "sku": "AC30-1000R",
              "attr": {
                  "color": "red",
                  "size": "10-inch"
              },
              "qty": 100
          },
          {
              "sku": "AC30-1000B",
              "attr": {
                  "color": "blue",
                  "size": "10-inch"
              },
              "qty": 100
          }
      ],
      "productType": "physical",
      "price": 14.95,
      "sale": {
  	    "enabled": true,
  	    "price": 12.95,
  	    "start": "2016-09-13",
  	    "end": "2016-10-13"
  	  },
      "UPCCode": "8 34460 00372 4",
      "category": "office_supplies",
      "description": "Reliable for up to 20 pages!",
      "images": [
          "http://acmeofficesupplies.com/img/ac30-red", "http://acmeofficesupplies.com/img/ac30-blue"
      ],
      "manufacturerName": "Acme Office Supplies",
      "inStock": true,
      "taxable": true,
      "enabled": true,
      "url": "http://acmeofficesupplies.com/AC30",
      "tags": [
          "office",
          "office supplies",
          "stapler",
          "stationary"
        ],
      "properties": {
          "some-key1":"value1",
          "some-key2":"value2"
       }
  }

• The following URI in conjunction with the JSON will perform the POST.

  http://<path>/products

GET/products

• Parameter	Type	Description	Example
  fields	string	Sets which data fields will be returned.	?fields=productName
  page	number	Page number of results.	?page=3
  per_page	number	Number of results per page.	?per_page=10

• Return all records

  The following URI will retrieve all products and include all fields.

  http://<path>/products

  Return records filtered by a field

  The following URI will retrieve all orders, but only include the field data for the productName.

  http://<path>/products?fields=productName

  Return records filtered by multiple fields

  The following URI will retrieve all orders, and include the field data for both productName and category.

  http://<path>/products?fields=productName,category

  Return records filtered by page number and records per page

  The following URI will retrieve all products starting from the third page grouping contacts by 10. For example, page 1 would have included the first 10, page 2 the second group of 10 and so on.

  http://<path>/products?page=3&per_page=10

GET/products/{id}

• The following URI will retrieve the product where the product id is 112233. It will include all fields.

  http://<path>/products/112233

PUT/products/{id}

• Same requirements and schema as the POST method above.

• The following will update the Acme-30 Stapler, changing the price to 16.95 and marking it as not in stock.

  {
      "productID": "AC30",
      "productName": "Acme-30 Stapler",
      "price": "16.95",
      "inStock": false
  }

• The following URI in conjunction with the JSON will perform the PUT for the product with the productID of AC30.

  http://<path>/products/AC30

DELETE/products/{id}

• The following URI will delete the product where the product id is 112233.

  http://<path>/products/112233

Error responses

The Cordial API will return an error object with an errorKey and message if there is a problem with an API call. Below is a list of errors specific to the Products API endpoint, along with suggested modifications to resolve each error. If you receive an error from this API endpoint that is not listed in this table, it's likely recorded within the Global API Error Responses page.