In This Section

Products

API Set Name: products

API Description and Functional Purpose:

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

POST /products

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",
    "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"
     }
}
Method URI Path
POST /products
Creates a new product in the Cordial database using the appropriate JSON body.

A product can include one or more variants. Posting the same product more than one time with the same "productID" value will update the current product. This is helpful for reloading and or updating product information when batch processing multiple records.

Required Parameters

Parameter Type Description Example
Product
productID string Unique identifier for a product. AC30
productName string The name of the product. Acme-30 Stapler

Optional Parameters

Parameter Type Description Example
Product
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
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

Example Request URIs

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

http://<path>/products

GET /products

Method URI Path
GET /products
Retrieves all products from the Cordial database.

Using query string parameters, it is also possible to filter the field set returned using a query string for the parameter "fields".

When retrieving a large amount of products in the response, it is possible to apply the "per_page" and "page" query string parameters to limit the count returned and page position.

Example Request URIs

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

http://<path>/products

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

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

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

http://<path>/products?fields=productName%2Ccategory

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}

Method URI Path
GET /products/{id}
Retrieves a specific product from the Cordial database.

The product is defined by the unique "productID" value.

For example, /products/112233 would return the response data for the product with the "productID" value of "112233".

Example Request URIs

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}

Method URI Path
PUT /products/{id}
Updates a product in the Cordial database using the appropriate JSON body.

The product is defined by the unique "productID" value.

For example, /products/112233 would update the the product with the "productID" value of "112233".

Required & Optional Parameters

Same requirements and schema as the POST method above.

Example JSON Requests

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,
}

Example Request URIs

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}

Method URI Path
DELETE /products/{id}
Deletes a product from the Cordial database.

The product is defined by the products's unique "productID" value.

For example, /products/112233 would remove the product with the "productID" value of "112233".

Example Request URIs

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

http://<path>/products/112233

Other related method calls:

The following resource collections are associated to this collection.

Collection Association
orders A post to the order method will write to the products collection, where the order items are each added as a specific product variants.

Related articles

Comments

0 comments

Please sign in to leave a comment.