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.

Related Collections:

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.

POST /products

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.

Parameters

*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

Example JSON Requests

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

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.

Parameters

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

Example Request URIs

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}

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

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 is likely recorded within the Global API Error Responses page.

errorKey Message Modifications
PRODUCT_NOT_FOUND Product not found Make sure the unique productID provided was input correctly.
PRODUCT_IS_IN_USE Product exists in existing automation template, scheduled message or audience rule The product you are attempting to remove is currently being actively used.

Related articles

Comments

0 comments

Please sign in to leave a comment.