Overview

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

• API set name: productimports

Additional information

• This resource uses the JSON request information to define the host location of the data file, the transport protocol, and the host login authentication information.
• It is important to note that this resource is not a collection of imports, but is a resource that initiates import processing by creating an import job.
• Import status information is available through the Jobs widget using the returned jobID.

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.

• Learn more about Cordial API authentication here.

File information

• Permissible import file types: CSV and JSONL
• Column headers need to be the product attribute field names.

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.

• 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.

Methods, parameters, and examples

• POST/v2/productimports

POST/v2/productimports

• 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. Upon import, if an attribute contains the nullMarker value (i.e. ignore), then the attribute value will not be updated.  Not valid when the import file is JSONL.See example below. Note: This parameter cannot be used to change an attribute value into an empty string.	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

  • If hasHeader is true then API is instructed that the first record in the CSV file is not a product record.
  • If hasHeader is true then the columns array becomes optional.
  • If columns array is populated then these columns are used to map the data in the CSV to product attributes.
  • If columns array is populated and hasHeader is true then the data in first row of the CSV is ignored.

• 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:

  • Via the API with a GET /v2/jobs/{id} call.
  • Via the UI by navigating to the jobs page.
    To access the jobs page in the UI, click on the icon at the top of the system header.

• 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:

• If providing an attribute key with a value, the attribute will be updated with the new value in the database.
• If providing an attribute key with an empty string, the attribute will be updated with the empty string in the database.
• If providing an attribute key with a nullMarker value, the attribute will be skipped and not updated in the database.
• If an attribute key is not provided, the attribute will be ignored and not updated in the database.

Note in the CSV example below:

• The price attribute with the value "15.99" will update the attribute in the database to "15.99".
• The category attribute with the defined nullMarker value "ignore" will ignore updating the attribute and leave it as "office_supplies" in the database.
• The productType attribute with an empty string value will update the attribute in the database to an empty string.

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.