# How can we help?

## Search

## 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 with 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 specific product variants. |

## Authentication

Cordial's core APIs use HTTPS Basic Authentication (BA). From within the Cordial platform, you can generate an encoded [API key for your account](https://support.cordial.com/hc/en-us/articles/115005365087) and use it for authorization.

- [Learn more about Cordial API authentication here](httpss://support.cordial.com/hc/en-us/articles/203885498-RESTful-API-summary-and-usage#authentication).

## Methods, parameters, and examples

- [POST/v2/products](https://support.cordial.com/hc/en-us/articles/203886098-Products-API#postProducts)
- [GET/v2/products](https://support.cordial.com/hc/en-us/articles/203886098-Products-API#getProducts)
- [GET/v2/products/{id}](https://support.cordial.com/hc/en-us/articles/203886098-Products-API#getProductsId)
- [PUT/v2/products/{id}](https://support.cordial.com/hc/en-us/articles/203886098-Products-API#putProductsId)
- [DELETE/v2/products/{id}](https://support.cordial.com/hc/en-us/articles/203886098-Products-API#deleteProductsId)

## POST/v2/products

| Method | URL Path |
| --- | --- |
| POST | /v2/products |
| - Creates a new product in the Cordial database using the appropriate JSON body.<br>- 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](https://support.cordial.com/hc/en-us/articles/203886098-Products-API#zp-1-0)
- [Example JSON requests](https://support.cordial.com/hc/en-us/articles/203886098-Products-API#zp-1-1)
- [Example request URL](https://support.cordial.com/hc/en-us/articles/203886098-Products-API#zp-1-2)

\* 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 | https://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 | https://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"
}
```

#### 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": [\
        "https://acmeofficesupplies.com/img/ac30-red", "https://acmeofficesupplies.com/img/ac30-blue"\
    ],
    "manufacturerName": "Acme Office Supplies",
    "inStock": true,
    "taxable": true,
    "enabled": true,
    "url": "https://acmeofficesupplies.com/AC30",
    "tags": [\
        "office",\
        "office supplies",\
        "stapler",\
        "stationary"\
      ],
    "properties": {
        "some-key1":"value1",
        "some-key2":"value2"
     }
}
```

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

```
https://<path>/v2/products
```

## GET/v2/products

| Method | URL Path |
| --- | --- |
| GET | /v2/products |
| - Retrieves all products from the Cordial database.<br>- Using query string parameters, it is also possible to filter the field set returned using a query string for the parameter `fields`.<br>- When retrieving a large number 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](https://support.cordial.com/hc/en-us/articles/203886098-Products-API#zp-2-0)
- [Example request URLs](https://support.cordial.com/hc/en-us/articles/203886098-Products-API#zp-2-1)

| 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 URL will retrieve all products and include all fields.

```
https://<path>/v2/products
```

#### Return records filtered by a field

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

```
https://<path>/v2/products?fields=productName
```

#### Return records filtered by multiple fields

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

```
https://<path>/v2/products?fields=productName,category
```

#### Return records filtered by page number and records per page

The following URL 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.

```
https://<path>/v2/products?page=3&per_page=10
```

## GET/v2/products/{id}

| Method | URL Path |
| --- | --- |
| GET | /v2/products/{id} |
| - Retrieves a specific product from the Cordial database.<br>- The product is defined by the unique `productID` value.<br>- For example, /products/112233 would return the response data for the product with the `productID` value of **112233**. |

The following URL will retrieve the product where the product id is **112233**. It will include all fields.

```
https://<path>/v2/products/112233
```

## PUT/v2/products/{id}

| Method | URL Path |
| --- | --- |
| PUT | /v2/products/{id} |
| - Updates a product in the Cordial database using the appropriate JSON body.<br>- The product is defined by the unique `productID` value.<br>- For example, /products/112233 would update the product with the `productID` value of **112233**. |

- [Parameters](https://support.cordial.com/hc/en-us/articles/203886098-Products-API#zp-4-0)
- [Example JSON request](https://support.cordial.com/hc/en-us/articles/203886098-Products-API#zp-4-1)
- [Example request URL](https://support.cordial.com/hc/en-us/articles/203886098-Products-API#zp-4-2)

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 URL in conjunction with the JSON will perform the PUT for the product with the `productID` of **AC30**.

```
https://<path>/v2/products/AC30
```

## DELETE/v2/products/{id}

| Method | URL Path |
| --- | --- |
| DELETE | /v2/products/{id} |
| - Deletes a product from the Cordial database.<br>- The product is defined by the products's unique `productID` value.<br>- For example, /products/112233 would remove the product with the `productID` value of **112233**. |

The following URL will delete the product where the product id is **112233**.

```
https://<path>/v2/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](https://support.cordial.com/hc/en-us/articles/4402427843597-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.