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.
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 |
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 When retrieving a large amount of products in the response, it is possible to apply the |
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 For example, /products/112233 would return the response data for the product with the |
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 For example, /products/112233 would update the the product with the |
Required and 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 For example, /products/112233 would remove the product with the |
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's 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. |
Comments
0 comments
Please sign in to leave a comment.