Overview

The order imports resource creates an import job to batch load a file of orders into the Cordial database from an external location.

Only the JSONL file type is permissible for imports using this API endpoint. Compared to CSV, the JSONL file format allows for greater flexibility when working with large sets of multi-layered data, making it an ideal format for importing order data.

• You can learn more about JSONL file format here.
• You can find an example JSONL file below.

API set name: ordersimport

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.
• This resource is not a collection of imports—it's a resource that initiates import processing by creating an import job.
• Import status information is available through the Jobs page in the UI using the returned job ID.

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

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.

Related collection

The following collections are associated with the orders collection.

Example JSONL file

{"orderID":"20250225-b23","email":"jsmith@example.com","properties":{"a_num": 1},"purchaseDate":"2025-01-25T00:00:00+0000","items":[{"productID":"123id","description":"Blue shirt","sku":"123SKU","category":"Shirts","name":"Blue button down","qty":1,"itemPrice":49.00}]}
{"orderID":"51190447-b10","email":"mjoy@example.com","properties":{"a_num": 1},"purchaseDate":"2025-02-12T00:00:00+0000","items":[{"productID":"456id","description":"Khaki pants","sku":"456SKU","category":"Pants","name":"Fashionable khaki pants","qty":1,"itemPrice":29.99}]}

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

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

Methods, parameters, and examples

• POST/v2/ordersimport

POST/v2/ordersimport

• 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
  suppressTriggers	boolean	optional	If true, this will suppress any triggered messages set to fire based on updates to values in the import. Default is true.	false
  source	object	required	See parameters for the source object below.	"source": {}
  source parameters
  transport	string	required	Transport options include HTTPS, HTTP, FTP, SFTP, S3, GCS.	https
  url	url	if transport = HTTPS	URL or location of the import file.	https://files.kb.com/file.jsonl
  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, S3 or GCS	optional directory path to the file	/files/file.jsonl OR ./files/file.jsonl OR files/file.jsonl
  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
  bucket	string	if transport = GCS	Defines the bucket name if transport is Google Cloud Storage. Be sure to use the same name from the setup process in Cordial marketplace.	name_used_in_marketplace_setup

• Example JSON request for HTTPS

  The following will initiate an import job to load a JSONL 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/orders-import.jsonl"
    },
   "confirmEmail": "jsmith@example.com",
   "suppressTriggers": true,
   "hasHeader": true
  }

  The use of hasHeader: true parameter is currently required in order to satisfy file type validation checks.

  Example JSON request for FTP or SFTP

  The following will initiate an import job to load a JSONL 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/orders-import.jsonl"
    },
    "confirmEmail": "jsmith@example.com"
  }
  

  Example JSON request for S3

  The following will initiate an import job to load a JSNL 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/orders-import.jsonl"
    },
    "confirmEmail": "jsmith@example.com"
  }
  

  Example JSON request for Google Cloud Storage

  The following will initiate an import job to load a JSNL file via a GCS 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.

  Your Google Could Storage integration must be enabled in the Cordial Marketplace.

  {
    "source": {
      "transport": "gcs",
      "bucket": "same_name_used_in_marketplace_setup",
      "path": "/folder/orders-import.jsonl"
    },
    "confirmEmail": "msmith@example.com"
  }
  

• API response body

  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/ordersimport
  

Examples of how updates are handled

When updating an order 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 an attribute key is not provided, the attribute will be ignored and not updated in the database.

Note in the JSONL import example below:

• The itemPrice attribute with the value "39.99" will update the attribute in the database to "39.99".
• The description attribute with an empty string value will update the attribute in the database to an empty string.
• The category attribute has been left out entirely and will retain the same value currently in the database.

Example order record before import

{
  "orderID": "20250225-b23",
  "properties": {
    "a_num": 1
  },
  "purchaseDate": "2025-01-25T00:00:00+0000",
  "items": [
    {
      "productID": "123id",
      "description": "Blue Shirt",
      "sku": "123SKU",
      "category": "Shirts",
      "name": "Blue button down",
      "qty": 1,
      "itemPrice": 49,
      "amount": 49
    }]
}

Example JSONL to be imported

{"orderID":"20250225-b23","email":"jsmith@example.com","properties":{"a_num": 1},"purchaseDate":"2025-01-25T00:00:00+0000","items":[{"productID":"123id","description":"","sku":"123SKU","name":"Blue button down","qty":1,"itemPrice":39.99}]}

Example product record after import

{
  "orderID": "20250225-b23",
  "properties": {
    "a_num": 1
  },
  "purchaseDate": "2025-01-25T00:00:00+0000",
  "items": [
    {
      "productID": "123id",
      "description": "",
      "sku": "123SKU",
      "category": "Shirts",
      "name": "Blue button down",
      "qty": 1,
      "itemPrice": 39.99,
      "amount": 39.99
    }]
}

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 accompanying message if there's a problem with an API call. You can find examples of common errors on the Global API error responses page.