Product imports API – Cordial Knowledge Base

How can we help?

Overview

The product imports resource creates an import Job to batch load a file of products into the Cordial database from an external location.

Additional information

Columns, headers, and nullMarker parameters will be disregarded when the import file type is JSONL. Please see below for examples of how updates are handled.

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 and use it for authorization.

File information

First row column headers describe the data for that column. Column headers are not required in CSV as they can be included as an array within the API call in the columns field.

Column Headers Required Expected values
productID Required string
productName Required string

Example CSV (with required product attribute field names)

productID,productName
exampleProduct1,exampleProduct1

Example CSV (with optional product attribute field names)

productID,productName,productType,price,sale.enabled,category,inStock,url,properties.style,variants.0.sku,variants.0.qty,variants.0.attr.color,images.0,images.1,tags.0,tags.1,tags.2
exampleProduct1,exampleProduct1,physical,10,0,shirts,1,https://mydomain.com,oxford,123456,2000,blue,image.jpg,image2.jpg,shirts,oxford,blue

All product attribute field names are provided by default as part of the schema. For a full list of product attributes view the article on adding products via the API.

{"productID": "skirt0912","productName": "Denim Skirt","price": 19.99,"variants": [{"sku": "skirt0912","attr": {"color": "blue","size": "8"}}]}
{"productID": "pants0910","productName": "Khaki Pants","price": 29.99,"variants": [{"sku": "pants0910","attr": {"color": "khaki","size": "34"}}]}

The JSONL file can store multiple products, each starting on a new line after the preceding product.

Related collections

The following collections are associated with the Products Collection.

Collection Association
products The productimports resource creates product records in the products collection.
jobs The productimports resource creates job records in the jobs collection.

Methods, parameters, and examples

POST/v2/productimports

Method URL Path
POST /v2/productimports
Creates an import job using the JSON body information.
Parameter Type Required Description Example
confirmEmail email optional Email address to send an administrative alert that the import job has been completed. joesmith@example.com
hasHeader boolean required, if columns is not included Denotes the first row column headers are present, default is false true
columns array required, if hasHeader is not explicitly set to true. Array of column headers, ordered by column positionally left to right ["productID", "productName", "productType"]
nullMarker string optional Defines the value to be used for ignoring or skipping attribute updates. Not valid when the import file is JSONL. ignore, ""
source object required See parameters for source below "source":{}
Source Parameters
transport string required Transport options include HTTPS, HTTP, FTP, SFTP, S3. https
url url if transport = HTTP URL or location of the import file. http://files.example.com/file.csv
port string if transport = ftp or sftp, and not using default The port number for the server. 44
server string if transport = FTP or SFTP domain example.com
username string if transport = FTP or SFTP An account username for gaining access to the file location. myusername
password string if transport = FTP or SFTP The account password for the above user name. Msm1th$99!
path string optional if transport = ftp, sftp or s3 optional directory path to the file /files/file.csv OR ./files/file.csv OR files/file.csv
aws_access_key_id string if transport = S3 public aws id WIfdavFHS8adsfhad98df
aws_secret_access_key string if transport = S3 secret aws key dudhKDDHE476383kdsdhdka
aws_bucket string if transport = S3 aws bucket name my_bucket
aws_region string if transport = S3 aws region us-west-2

Example JSON request for HTTP

The following will initiate an import job to load a CSV file from a secure HTTP location. A confirmation email will be sent the email address provided once the job is complete. The JSON response will provide a jobID for checking job status if needed.

{
    "source": {
        "transport": "https",
        "url": "https://example.com/product-import.csv"
    },
    "confirmEmail": "jsmith@example.com",
    "hasHeader": true
}

When import file type is JSONL, the use of "hasHeader": true parameter is currently required in order to satisfy file type validation checks.

Example JSON request for http (with columns array)

{
    "source": {
        "transport": "https",
        "url": "https://example.com/product-import.csv"
    },
    "confirmEmail": "jsmith@example.com",
    "columns": ["productID", "productName", "productType", "price", "sale.enabled", "category", "inStock", "url", "properties.style", "variants.0.sku", "variants.0.qty", "variants.0.attr.color", "images.0", "images.1", "tags.0", "tags.1", "tags.2"]
}

Example JSON request for FTP or SFTP

The following will initiate an import job to load a CSV file via a secure FTP connection. A confirmation email will be sent the email address provided once the job is complete. The JSON response will provide a jobID for checking job status if needed.

{
  "source": {
    "transport": "sftp",
    "server": "example.com",
    "username": "myusername",
    "password": "Msm1th$99!",
    "path": "./files/file.csv"
  },
  "hasHeader": true,
  "confirmEmail": "msmith@example.com"
}

Example JSON request for S3

The following will initiate an import job to load a CSV file via an S3 connection. A confirmation email will be sent the email address provided once the job is complete. The JSON response will provide a jobID for checking job status if needed.

{
  "source": {
    "transport": "s3",
    "aws_access_key_id": "AAAAAAAAAAAAAAAAAAAA",
    "aws_secret_access_key": "dudhKDDHE476383kdsdhdkasKDHDKDeiuealskjD",
    "aws_bucket": "some-bucket",
    "aws_region": "us-west-2",
    "path": "folder/products.csv"
  },
  "hasHeader": true,
  "confirmEmail": "msmith@example.com"
}

JobID will be provided if no errors are detected.

Job status can be looked up:

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

https://<path>/v2/productimports

Examples of how updates are handled

When updating a product record:

Note in the CSV example below:

Example product record before import

{
    "productID": "AC30",
    "productName": "Acme-30 Stapler",
    "price": 14.95,
    "category": "office_supplies",
    "productType": "physical"
}

Example CSV to be imported

Note in this example, the nullMarker parameter value was defined as "ignore".

"productID","productName","price","category","productType"
"AC30","Acme-30 Stapler","15.99","ignore",""

Example product record after import

{
    "productID": "AC30",
    "productName": "Acme-30 Stapler",
    "price": 15.99,
    "category": "office_supplies",
    "productType": ""
}

Test in Swagger

You can access and test Cordial's APIs in Swagger.

Error responses

The Cordial API will return an error object with an errorKey and message if there is a problem with an API call. You can find common errors on the Global API Error Responses page.