Commerce HQ Documentation

Welcome to the Commerce HQ developer hub. You'll find comprehensive guides and documentation to help you start working with Commerce HQ as quickly as possible, as well as support if you get stuck. Let's jump right in!

Guides    Discussions

How to use GET requests

 

Expanding relations, filtering fields, and sorting

The API provides flexible ways to fetch exactly the data that you need.

In every section of the API, you can make GET requests to fetch the list of respective items.
The basic GET request is:
GET /api/v1/entity
for example, GET /api/v1/products will return the list of products.

By default, relational data is hidden in most endpoints to improve performance. For example, products by default will load without variants and images. If you need that data, you can explicitly expand it, using:
GET /api/v1/entity?expand=relation1,relation2
You can find the names of relations that can be expanded on the reference page for each GET endpoint.
Alternatively, you can expand all relations, using:
GET /api/v1/entity?expand=all

If you need to fetch only some fields, you can use:
GET /api/v1/entity?fields=field1,field2
for example, GET /api/v1/products?fields=id,title will return products in such format:

{
  "id": 298,
  "title": "Hello kitty 1001"
}

You can sort data by almost any field using the sort property in GET, like this:
GET /api/v1/entity?sort=field1,field2
To sort in a descending order, add ! before the field name, so for example, to sort products by descending title and then ascending price, use: GET /api/v1/products?sort=!title,price

Response wrapper and pagination

Data from most GET endpoints (except those that don't require pagination) will come in a wrapper, like this:

{
  "items": [],
  "_links": {
    "self": "<String>",
    "next": "<String>",
    "prev": "<String>",
    "first": "<String>",
    "last": "<String>",
  },
  "_meta": {
    "totalCount": "<Int>", // total numer of items in set
    "perPage": "<Int>", // page size
    "currentPage": "<Int>", // current page
    "pageCount": "<Int>" // number of pages according to page size
  }
}

Actual data will be inside the items array, and the rest will be metadata that you can use for pagination.
If you wish to load another page, you can either refer to URLs in the _links section, or add ?page to the GET request, like this:
GET /api/v1/products?page=2

Sometimes, on pages like Orders, you need to find which page the order you are looking for is on. For that case, try a request like this:
GET /api/v1/orders/1000/page,
where 1000 is the order ID, and you will get back the page number.

Finally, if you wish to load a lot of items at once, you can explicitly specify the page size:
GET /api/v1/orders?size=200
will make the API load 200 orders per page. Please be aware that this might affect performance.

Helpers

 

In many places, collections, tags, types, vendors and warehouses are presented as IDs. For many usages, you will need to load their title. You can do that with this endpoint:
GET api/v1/helpers
Also, if you wish to load anything specific (such as tags), you can load just that:
GET api/v1/helpers/tags

See a sample response in the right column.

{
  "collections": [
    {
      "id": 1,
      "title": "Collection",
      "is_auto": 0
    }
  ],
  "types": [
    {
      "id": 1,
      "title": "Type"
    }
  ],
  "vendors": [
    {
      "id": 1,
      "title": "Supplier 1"
    }
  ],
  "warehouses": [
    {
      "id": 1,
      "title": "Warehouse 1"
    },
    {
      "id": 2,
      "title": "Warehouse 2"
    },
    {
      "id": 3,
      "title": "Warehouse 3"
    }
  ]
}

Error formatting

 

For invalid JSON or any other general errors, such a response will be returned:

400 Bad Request

{
    message: "Problems parsing JSON, or any another error message"
}

For failed validation:

422 Unprocessable Entity
{
    message: "Validation Failed",
    errors: {
        username: [
            'Username is required.',
            'Username must contain only word characters.'
        ],
        email: [
            'Email address is invalid.'
        ]
    }
}

Authentication

 

Private Apps

CommerceHQ allows you to create a private app, which has access to specific parts of your store. As soon as you create private app you will get "api key" and "api password".

Let's assume your API key is "key_123" and API password is "secure-password"

As a first step, you have to concatenate them into one string, having <api key>:<api password>, make sure you have colon in the middle of them.

$api_key = "key_123";
$api_password = "secure-password";

$auth_string = base64_encode($api_key . ':' . $api_password);
// make sure you have ":" between your API key and API password

And after this, you can pass it via "Authorization" header

Authorization: Basic a2V5XzEyMzpzZWN1cmUtcGFzc3dvcmQ=

GET https://store.commercehq.com/api/v1/products

Addresses

 

Address is a common object that you can find on Cart, Customers and Orders.

Attributes

Title
Type
Description

id

int

ID of the address

shipping

array

Contains shipping info. Fields:

  • first_name
  • last_name
  • company
  • street
  • suite
  • city
  • country
  • state
  • zip

billing

array

Contains billing info. Fields:

  • first_name
  • last_name
  • company
  • street
  • suite
  • city
  • country
  • state
  • zip

phone

string

Phone number

"address": [
  {
    "id": 7932,
    "shipping": {
      "first_name": "First",
      "last_name": "Last",
      "company": "Company name",
      "street": "Street",
      "suite": "1B",
      "city": "Stocktown",
      "country": "US",
      "state": "CA",
      "zip": "12345"
  },
  "billing": {
      "first_name": "First",
      "last_name": "Last",
      "company": "Company name",
      "street": "Street",
      "suite": "1B",
      "city": "Stocktown",
      "country": "US",
      "state": "CA",
      "zip": "12345"
    },
  "phone": "123456789"
}

LineItems

 

LineItems is a common object that you can find on Cart, Orders and Invoice Orders.
It contains all the info about the product in the state it was in when ordered, so changes to the current product being sold don't affect data in orders.

Attributes

Title
Type
Description

id

int

ID of the item

product_id

int

Product ID. The product might not exist anymore

title

string

Title of the product

is_multi

bool

Whether product is multi variant

type

string

Type of the product

is_giftcard

bool

Whether product is a gift card

shipping_weight

float

Shipping weight of the product

vendor

string

Vendor of the product

auto_fulfilment

bool

Whether auto fulfilment is enabled for the product

track_inventory

bool

Whether product tracks inventory

sku

string

SKU of the product

price

decimal

Price of the product

compare_price

decimal

Compare price of the product

image

string

URL to the product image

image_max_size

int

Max size of the image. Refer to Images

variant

array

Variant info.
Includes:

  • id (int)
  • variant (array of strings)
"data": {
  "id": 9554,
  "product_id": 269,
  "title": "Choker",
  "is_multi": true,
  "type": "Choker",
  "is_giftcard": false,
  "shipping_weight": 2,
  "vendor": null,
  "auto_fulfilment": false,
  "track_inventory": false,
  "sku": "M-WS1",
  "price": 13.94,
  "compare_price": 46.5,
  "image": null,
  "image_max_size": 7,
  "variant": {
    "id": 1185,
    "variant": [
      "Black"
    ]
  }
}

Load products

 

/products

Loads a list of products or information on a single product.

URL parameters

Parameters that you can append to the URL, for example: ?parameter=value

Title
Type
Description
Required?

id

int

ID of a single product to load. Can be used after the slash.
Example:
products/27
load product with ID 27

No

page

int

Number of the page to load. Defaults to 1

No

sort

string

One or more attributes to sort the items by. Defaults to id descending.
For descending, add ! before the attribute name. For multiple attributes, separate them by commas.
Example:
products?sort=!id,title
sort by descending id first, then by ascending email

No

size

int

Number of items per page. Defaults to 20

No

expand

string

Relations that should be extended.
Possible options: textareas, images, variants, options, all
You can use multiple options separated by commas.
Example:
products?expand=textareas,images
Load products with textareas and images
Use all to load all relations.

No

Response attributes

Attributes that you will receive in response from the endpoint in JSON format, for example:
{"id": 1,"title": "Product"}

Title
Type
Description

id

int

ID of the product

title

string

Title of the product

is_multi

bool

If the product is multi variant as opposed to single variant

type

string

Type of the product, for example Shirts

collections

array of ints

Array containing IDs of collections that the product belongs to. Only returns collections with manual addition of products

tags

array of strings

Tags assigned to the product

shipping_weight

float

Shipping weight of the product

auto_fulfilment

bool

Whether automatic fulfilment is enabled

track_inventory

bool

Whether product is tracked in Inventory

vendor

string

Name of the vendor that supplies the product

sku

string

SKU of the product

seo_meta

string

Meta for SEO

seo_title

string

Page title for SEO

seo_url

string

Page URL for SEO. Generates automatically from title

is_template

bool

Whether this is a template to create products from

is_draft

bool

Whether this product is a draft that is not published

price

float

Price of the product, for single variant products

compare_price

float

Compare price of the product, for single variant products

created_at

int

Timestamp of the product creation time

updated_at

int

Timestamp of the product last update time

textareas

object containing arrays

Custom pieces of text that can be displayed as tabs on the product page. Only the titles that have been pre-set on Product settings page can be used here

textareas.name

string

Title of the tab. Only the titles that have been pre-set on Product settings page can be used here

textareas.text

string

Text contents of the tab

images

object containing arrays

Images for the product. Used if no variants change product look

images.id

int

ID of the image

images.path

string

Absolute URL of the image

images.max_size

int

Max size of the image, for internal usage

options

object containing arrays

Options for multi-variant products

options.title

string

Title of the option, for example Color

options.changes_look

bool

Whether this option changes look of the product

options.values

array of strings

Values of the option, for example Red and Blue

options.thumbnails

object containing arrays

Thumbnails that will be used in the variant selector on the product page

options.thumbnails.value

string

Value of the option for which the thumbnail is used, for example Red

options.thumbnails.color

string

Color of the selector thumbnail, HEX value. Either color or image is used.

options.thumbnails.image

array of mixed

Image of the selector thumbnail. Either color or image is used.

options.thumbnails.image.id

int

ID of the image, if image is used

options.thumbnails.image.path

string

Absolute URL of the image, if image is used

options.thumbnails.image.max_size

int

Max size of the image, for internal usage

variants

object containing arrays

Variants resulting from combining of options

variants.id

int

ID of the variant

variants.variant

array of strings

A combination of options, for example Red and Big

variants.price

float

Price of the variant

variants.compare_price

float

Compare price of the variant

variants.sku

string

SKU of the variant

variants.default

bool

Whether the variant is default

variants.ignore

bool

Whether the variant should not be used

variants.images

object containing arrays

Images for the variant if it changes product look

variants.images.id

int

ID of the image

variants.images.path

string

Absolute URL of the image

variants.images.max_size

int

Max size of the image, for internal usage

GET https://mystore.commercehq.com/api/v1/products/14?expand=all
{
  "id": 14,
  "title": "Fancy bear 1000",
  "is_multi": true,
  "type": "Cats",
  "collections": [6,7],
  "tags": [
    "dog"
  ],
  "shipping_weight": 3000,
  "auto_fulfilment": false,
  "track_inventory": true,
  "vendor": "Supplier #1",
  "sku": "sku dog1000",
  "seo_meta": null,
  "seo_title": "Fancy bear 1000",
  "seo_url": "fancy-bear-1000",
  "is_template": false,
  "is_draft": false,
  "created_at": 1484929254,
  "updated_at": 1485006377,
  "textareas": [
    {
      "name": "Description",
      "text": "Great product"
    }
  ],
  // for a single variant product
  "images": [
    {
      "id": 18,
      "path": "https://s3-us-west-2.amazonaws.com/commercehq-userfiles-dev/commercehq-test/uploads/1484915452_4bc11fff36e9ed964af6163f413bcb42.jpg",
      "max_size": 6
    },
    {
      "id": 17,
      "path": "https://s3-us-west-2.amazonaws.com/commercehq-userfiles-dev/commercehq-test/uploads/1484915445_156e1fe7d4ac89c4b0567fc8c782e490.jpg",
      "max_size": 7
    }
  ],
  // for a multi variant product
  "options": [
    {
      "title": "Color",
      "changes_look": true,
      "values": [
        "Red",
        "Blue"
      ],
      "thumbnails": [{
      			value: "Red",
            color: "#BD3F3F"
      }]
    },
    {
      "title": "Size",
      "changes_look": true,
      "values": [
        "Big",
        "Small"
      ],
      "thumbnails": [{
      			value: "Big",
            image: {
                id: "6",
                path: "https://s3-us-west-2.amazonaws.com/commercehq-userfiles-dev/commercehq-test/uploads/1484915452_4bc11fff36e9ed964af6163f413bcb42.jpg",
                max_size: 6
            }
      }]
    }
  ],
  "variants": [
    {
      "id": 43,
      "variant": [
        "Red",
        "Big"
      ],
      "price": 25,
      "compare_price": 15,
      "sku": null,
      "default": true,
      "ignore": false,
      "images": [
        {
          "id": 19,
          "path": "https://s3-us-west-2.amazonaws.com/commercehq-userfiles-dev/commercehq-test/uploads/1485006363_ceef7428ba5fb55b0cb73897fb2d8720.jpg",
          "max_size": 9
        }
      ]
    },
    {
      "id": 44,
      "variant": [
        "Red",
        "Small"
      ],
      "price": 25,
      "compare_price": 15,
      "sku": null,
      "default": false,
      "ignore": false,
      "images": []
    },
    {
      "id": 45,
      "variant": [
        "Blue",
        "Big"
      ],
      "price": 25,
      "compare_price": 15,
      "sku": null,
      "default": false,
      "ignore": false,
      "images": []
    },
    {
      "id": 46,
      "variant": [
        "Blue",
        "Small"
      ],
      "price": 25,
      "compare_price": 15,
      "sku": null,
      "default": false,
      "ignore": false,
      "images": []
    }
  ]
}

Create a product

 

/products

Creates a new product.

Request body attributes

Parameters that you can send in the request body in JSON format, for example:
{"id": 1,"title": "Product"}

Title
Type
Description
Required?

title

string

Title of the product

Yes

is_multi

bool

If the product is multi variant as opposed to single variant

No

type

string

Type of the product, for example Shirts

No

collections

array of ints

Array containing IDs of collections that the product belongs to. Only returns collections with manual addition of products

No

tags

array of strings

Tags assigned to the product

No

shipping_weight

float

Shipping weight of the product

No

auto_fulfilment

bool

Whether automatic fulfilment is enabled

No

track_inventory

bool

Whether product is tracked in Inventory

No

vendor

string

Name of the vendor that supplies the product

No

sku

string

SKU of the product

No

seo_meta

string

Meta for SEO

No

seo_title

string

Page title for SEO

No

seo_url

string

Page URL for SEO. Generates automatically from title

No

is_template

bool

Whether this is a template to create products from

No

is_draft

bool

Whether this product is a draft that is not published

No

price

float

Price of the product, for single variant products

Yes, if product is single variant

compare_price

float

Compare price of the product, for single variant products

No

textareas

object containing arrays

Custom pieces of text that can be displayed as tabs on the product page. Only the titles that have been pre-set on Product settings page can be used here

No

textareas.name

string

Title of the tab. Only the titles that have been pre-set on Product settings page can be used here

Yes, if textareas are used

textareas.text

string

Text contents of the tab

Yes, if textareas are used

images

array of ints

Image IDs for the product. Used if no variants change product look. Images have to be uploaded first through the Images API

No

options

object containing arrays

Options for multi-variant products

Yes, if product is multi variant

options.title

string

Title of the option, for example Color

Yes, if options are used

options.changes_look

bool

Whether this option changes look of the product

No

options.values

array of strings

Values of the option, for example Red and Blue

Yes, if options are used

options.thumbnails

object containing arrays

Thumbnails that will be used in the variant selector on the product page

No

options.thumbnails.value

string

Value of the option for which the thumbnail is used, for example Red

Yes, if thumbnails are used

options.thumbnails.color

string

Color of the selector thumbnail, HEX value. Either color or image is used.

No

options.thumbnails.image

id

Image ID for the selector thumbnail. Either color or image is used. Images have to be uploaded first through the Images API

No

variants

object containing arrays

Variants resulting from combining of options

No

variants.variant

array of strings

A combination of options, for example Red and Big

Yes, if variants are used

variants.price

float

Price of the variant

Yes, if variants are used

variants.compare_price

float

Compare price of the variant

No

variants.sku

string

SKU of the variant

No

variants.default

bool

Whether the variant is default

No

variants.ignore

bool

Whether the variant should not be used

No

variants.images

array of ints

Array containing image IDs for the variant if it changes product look. Images have to be uploaded first through the Images API

No

Response attributes

Attributes that you will receive in response from the endpoint in JSON format, for example:
{"id": 1,"title": "Product"}

Title
Type
Description

id

int

ID of the product

title

string

Title of the product

is_multi

bool

If the product is multi variant as opposed to single variant

type

string

Type of the product, for example Shirts

collections

array of ints

Array containing IDs of collections that the product belongs to. Only returns collections with manual addition of products

tags

array of strings

Tags assigned to the product

shipping_weight

float

Shipping weight of the product

auto_fulfilment

bool

Whether automatic fulfilment is enabled

track_inventory

bool

Whether product is tracked in Inventory

vendor

string

Name of the vendor that supplies the product

sku

string

SKU of the product

seo_meta

string

Meta for SEO

seo_title

string

Page title for SEO

seo_url

string

Page URL for SEO. Generates automatically from title

is_template

bool

Whether this is a template to create products from

is_draft

bool

Whether this product is a draft that is not published

POST https://mystore.commercehq.com/api/v1/products/

{
    "title": "Good product 123",
    "price": 1,
    "collections": [1],
    "images": [8],
    "tags":["tag1", "tag heuer"],
    "type":"Shoes",
    "vendor":"abidas",
    "is_multi": true,
    "options":[
        {
            "title": "Color",
            "changes_look": false,
            "values": ["red"]
        },
        {
            "title": "Size",
            "changes_look": false,
            "values": ["S", "XL"],
            "thumbnails": [
                {
                    "value": "S",
                    "color": "#000",
                    "image": 7
                }
            ]
        }
    ],
    "variants":[
        {
            "variant": ["red"],
            "price": 1,
            "compare_price": 1,
            "sku": "abc",
            "default": true,
            "ignore": true,
            "images": [12]
        }
    ],
    "seo_url": "good-product-123"
}
{
  "id": 18,
  "title": "Good product 123",
  "is_multi": true,
  "type": "Shoes",
  "collections": [
    1
  ],
  "tags": [],
  "shipping_weight": null,
  "auto_fulfilment": false,
  "track_inventory": false,
  "vendor": "abidas",
  "sku": null,
  "seo_meta": null,
  "seo_title": null,
  "seo_url": "good-product-123",
  "is_template": false,
  "is_draft": false,
  "created_at": 1485010678,
  "updated_at": 1485010678
}

Update a product

 

/products/id

Updates an existing product. If it has been purchased before, its data will remain untouched in orders.

URL parameters

Parameters that you can append to the URL, for example: ?parameter=value

Title
Type
Description
Required?

id

int

ID of a single product to update. Can be used after the slash.
Example:
products/27
update product with ID 27

Yes

Request body attributes

Parameters that you can send in the request body in JSON format, for example:
{"id": 1,"title": "Product"}

Title
Type
Description
Required?

title

string

Title of the product

No

is_multi

bool

If the product is multi variant as opposed to single variant

No

type

string

Type of the product, for example Shirts

No

collections

array of ints

Array containing IDs of collections that the product belongs to. Only returns collections with manual addition of products

No

tags

array of strings

Tags assigned to the product

No

shipping_weight

float

Shipping weight of the product

No

auto_fulfilment

bool

Whether automatic fulfilment is enabled

No

track_inventory

bool

Whether product is tracked in Inventory

No

vendor

string

Name of the vendor that supplies the product

No

sku

string

SKU of the product

No

seo_meta

string

Meta for SEO

No

seo_title

string

Page title for SEO

No

seo_url

string

Page URL for SEO. Generates automatically from title

No

is_template

bool

Whether this is a template to create products from

No

is_draft

bool

Whether this product is a draft that is not published

No

price

float

Price of the product, for single variant products

No

compare_price

float

Compare price of the product, for single variant products

No

textareas

object containing arrays

Custom pieces of text that can be displayed as tabs on the product page. Only the titles that have been pre-set on Product settings page can be used here

No

textareas.name

string

Title of the tab. Only the titles that have been pre-set on Product settings page can be used here

Yes, if textareas are used

textareas.text

string

Text contents of the tab

Yes, if textareas are used

images

array of ints

Image IDs for the product. Used if no variants change product look. Images have to be uploaded first through the Images API

No

options

object containing arrays

Options for multi-variant products

Yes, if product is multi variant

options.title

string

Title of the option, for example Color

Yes, if options are used

options.changes_look

bool

Whether this option changes look of the product

No

options.values

array of strings

Values of the option, for example Red and Blue

Yes, if options are used

options.thumbnails

object containing arrays

Thumbnails that will be used in the variant selector on the product page

No

options.thumbnails.value

string

Value of the option for which the thumbnail is used, for example Red

Yes, if thumbnails are used

options.thumbnails.color

string

Color of the selector thumbnail, HEX value. Either color or image is used.

No

options.thumbnails.image

id

Image ID for the selector thumbnail. Either color or image is used. Images have to be uploaded first through the Images API

No

variants

object containing arrays

Variants resulting from combining of options

No

variants.variant

array of strings

A combination of options, for example Red and Big

Yes, if variants are used

variants.price

float

Price of the variant

Yes, if variants are used

variants.compare_price

float

Compare price of the variant

No

variants.sku

string

SKU of the variant

No

variants.default

bool

Whether the variant is default

No

variants.ignore

bool

Whether the variant should not be used

No

variants.images

array of ints

Array containing image IDs for the variant if it changes product look. Images have to be uploaded first through the Images API

No

Response attributes

Attributes that you will receive in response from the endpoint in JSON format, for example:
{"id": 1,"title": "Product"}

Title
Type
Description

id

int

ID of the product

title

string

Title of the product

is_multi

bool

If the product is multi variant as opposed to single variant

type

string

Type of the product, for example Shirts

collections

array of ints

Array containing IDs of collections that the product belongs to. Only returns collections with manual addition of products

tags

array of strings

Tags assigned to the product

shipping_weight

float

Shipping weight of the product

auto_fulfilment

bool

Whether automatic fulfilment is enabled

track_inventory

bool

Whether product is tracked in Inventory

vendor

string

Name of the vendor that supplies the product

sku

string

SKU of the product

seo_meta

string

Meta for SEO

seo_title

string

Page title for SEO

seo_url

string

Page URL for SEO. Generates automatically from title

is_template

bool

Whether this is a template to create products from

is_draft

bool

Whether this product is a draft that is not published

PATCH https://mystore.commercehq.com/api/v1/products/18

{
    "title": "Good product 123",
    "price": 1,
    "collections": [1],
    "images": [8],
    "tags":["tag1", "tag heuer"],
    "type":"Shoes",
    "vendor":"abidas",
    "is_multi": true,
    "options":[
        {
            "title": "Color",
            "changes_look": false,
            "values": ["red"]
        },
        {
            "title": "Size",
            "changes_look": false,
            "values": ["S", "XL"],
            "thumbnails": [
                {
                    "value": "S",
                    "color": "#000",
                    "image": 7
                }
            ]
        }
    ],
    "variants":[
        {
            "variant": ["red"],
            "price": 1,
            "compare_price": 1,
            "sku": "abc",
            "default": true,
            "ignore": true,
            "images": [12]
        }
    ],
    "seo_url": "good-product-123"
}
{
  "id": 18,
  "title": "Good product 123",
  "is_multi": true,
  "type": "Shoes",
  "collections": [
    1
  ],
  "tags": [],
  "shipping_weight": null,
  "auto_fulfilment": false,
  "track_inventory": false,
  "vendor": "abidas",
  "sku": null,
  "seo_meta": null,
  "seo_title": null,
  "seo_url": "good-product-123",
  "is_template": false,
  "is_draft": false,
  "created_at": 1485010678,
  "updated_at": 1485010678
}

Delete a product

 

/product/id

Delete an existing product. If it has been purchased before, its data will remain untouched in orders.

URL parameters

Parameters that you can append to the URL, for example: ?parameter=value

Title
Type
Description
Required?

id

int

ID of a single product to delete. Can be used after the slash.
Example:
products/27
delete customer with ID 27

Yes

DELETE https://mystore.commercehq.com/api/v1/products/30
204 No Content
[]

Load customers

 

/customers

Loads a list of customers or information on a single customer.

URL parameters

Parameters that you can append to the URL, for example: ?parameter=value

Title
Type
Description
Required?

id

int

ID of a single customer to load. Can be used after the slash.
Example:
customers/27
load customer with ID 27

No

page

int

Number of the page to load. Defaults to 1

No

sort

string

One or more attributes to sort the items by. Defaults to id descending.
For descending, add ! before the attribute name. For multiple attributes, separate them by commas.
Example:
customers?sort=!id,email
sort by descending id first, then by ascending email

No

size

int

Number of items per page. Defaults to 20

No

Response attributes

Attributes that you will receive in response from the endpoint in JSON format, for example:
{"email": "hello@world.com","first_name": "James"}

Title
Type
Description

id

int

ID of the customer

email

string

Email of the customer

first_name

string

First name of the customer

last_name

string

Last name of the customer

address

object containing arrays

One or multiple addresses assigned to the customer

address.id

id

ID of the address

address.shipping.first_name

string

First name for shipping

address.shipping.last_name

string

Last name for shipping

address.shipping.company

string

Company for shipping

address.shipping.street

string

Street name for shipping

address.shipping.suite

string

Suite for shipping

address.shipping.city

string

City for shipping

address.shipping.country

string

Country for shipping, 2-letter code as per ISO 3166-1

address.shipping.state

string

State/province/region for shipping, 2-letter code as per ISO 3166-2

address.shipping.zip

string

Zip/postal code for shipping

address.billing.first_name

string

First name for billing

address.billing.last_name

string

Last name for billing

address.billing.street

string

Street name for billing

address.billing.suite

string

Suite for billing

address.billing.city

string

City for billing

address.billing.country

string

Country for billing, 2-letter code as per ISO 3166-1

address.billing.state

string

State/province/region for billing, 2-letter code as per ISO 3166-2

address.billing.zip

string

Zip/postal code for billing

address.phone

string

Phone for the address

payment.type

string

Type of payment method. Can be: Visa, American Express, MasterCard, Discover, JCB, Diners Club, PayPal

payment.last4

string

Last 4 digits of the card number, if paid by card

notes

string

Notes about the customer, optionally set by the store owner

statistics.last_purchase

int

Timestamp of last purchase by the customer

statistics.order_count

int

Number of orders the customer has placed

statistics.lifetime_spent

int

Amount of money spent by customer on this store

orders

array of ints

Array of the customer's order IDs

tags

array of strings

Array containing the tags of all the products that the customer bought

created_at

int

Timestamp of the customer creation time

updated_at

int

Timestamp of the customer last update time

Notes

  • Addresses can be managed manually from the customer profile or flow from orders. Changing an address in a customer profile does not affect orders, but changing the address in an order may affect it in the customer profile.
GET https://mystore.commercehq.com/api/v1/customers/30
{
  "id": 30,
  "email": "developer@commercehq.com",
  "first_name": "Donald",
  "last_name": "Duck",
  "address": [
    {
      "id": 67,
      "shipping": {
        "first_name": "Donald",
        "last_name": "Duck",
        "company": null,
        "street": "47 Duck Street",
        "suite": "1",
        "city": "Duckland",
        "country": "US",
        "state": "CA",
        "zip": "12345"
      },
      "billing": {
        "first_name": "Donald",
        "last_name": "Duck",
        "street": "47 Duck Street",
        "suite": "1",
        "city": "Duckland",
        "country": "US",
        "state": "CA",
        "zip": "12345"
      },
      "phone": "123456789"
    }
  ],
  "payment": [
    {
      "type": "Visa",
      "last4": "4242"
    }
  ],
  "notes": null,
  "statistics": {
    "last_purchase": 1484313925,
    "order_count": 1,
    "lifetime_spent": 34
  },
  "orders": [
    91
  ],
  "tags": [],
  "created_at": 1484313922,
  "updated_at": 1484313922
}

Create a customer

 

/customers

Creates a new customer.

Request body parameters

Parameters that you can send in the request body in JSON format, for example:
{"email": "hello@world.com","first_name": "James"}

Title
Type
Description
Required?

email

string

Email of the customer

Yes

first_name

string

First name of the customer

No

last_name

string

Last name of the customer

No

address

object containing arrays

One or multiple addresses assigned to the customer

No

address.shipping.first_name

string

First name for shipping

No

address.shipping.last_name

string

Last name for shipping

No

address.shipping.company

string

Company for shipping

No

address.shipping.street

string

Street name for shipping

No

address.shipping.suite

string

Suite for shipping

No

address.shipping.city

string

City for shipping

No

address.shipping.country

string

Country for shipping, 2-letter code as per ISO 3166-1

No

address.shipping.state

string

State/province/region for shipping, 2-letter code as per ISO 3166-2

No

address.shipping.zip

string

Zip/postal code for shipping

No

address.billing.first_name

string

First name for billing

No

address.billing.last_name

string

Last name for billing

No

address.billing.street

string

Street name for billing

No

address.billing.suite

string

Suite for billing

No

address.billing.city

string

City for billing

No

address.billing.country

string

Country for billing, 2-letter code as per ISO 3166-1

No

address.billing.state

string

State/province/region for billing, 2-letter code as per ISO 3166-2

No

address.billing.zip

string

Zip/postal code for billing

No

address.phone

string

Phone for the address

No

notes

string

Notes about the customer, optionally set by the store owner

No

Response attributes

Attributes that you will receive in response from the endpoint in JSON format, for example:
{"email": "hello@world.com","first_name": "James"}

Title
Type
Description

id

int

ID of the customer

email

string

Email of the customer

first_name

string

First name of the customer

last_name

string

Last name of the customer

address

object containing arrays

One or multiple addresses assigned to the customer

address.id

id

ID of the address

address.shipping.first_name

string

First name for shipping

address.shipping.last_name

string

Last name for shipping

address.shipping.company

string

Company for shipping

address.shipping.street

string

Street name for shipping

address.shipping.suite

string

Suite for shipping

address.shipping.city

string

City for shipping

address.shipping.country

string

Country for shipping, 2-letter code as per ISO 3166-1

address.shipping.state

string

State/province/region for shipping, 2-letter code as per ISO 3166-2

address.shipping.zip

string

Zip/postal code for shipping

address.billing.first_name

string

First name for billing

address.billing.last_name

string

Last name for billing

address.billing.street

string

Street name for billing

address.billing.suite

string

Suite for billing

address.billing.city

string

City for billing

address.billing.country

string

Country for billing, 2-letter code as per ISO 3166-1

address.billing.state

string

State/province/region for billing, 2-letter code as per ISO 3166-2

address.billing.zip

string

Zip/postal code for billing

address.phone

string

Phone for the address

payment.type

string

Type of payment method. Can be: Visa, American Express, MasterCard, Discover, JCB, Diners Club, PayPal

payment.last4

string

Last 4 digits of the card number, if paid by card

notes

string

Notes about the customer, optionally set by the store owner

statistics.last_purchase

int

Timestamp of last purchase by the customer

statistics.order_count

int

Number of orders the customer has placed

statistics.lifetime_spent

int

Amount of money spent by customer on this store

orders

array of ints

Array of the customer's order IDs

tags

array of strings

Array containing the tags of all the products that the customer bought

created_at

int

Timestamp of the customer creation time

updated_at

int

Timestamp of the customer last update time

Notes

  • Addresses can be managed manually from the customer profile or flow from orders. Changing an address in a customer profile does not affect orders, but changing the address in an order may affect it in the customer profile.
POST https://mystore.commercehq.com/api/v1/customers
{
  "email": "hello@world.com",
  "first_name": "James",
  "last_name": "C Smith",
  "address": {
    "shipping": {
      "first_name": "James",
      "last_name": "C Smith",
      "street": "46 Leatherwood St.",
      "suite": "1432",
      "city": "North Hollywood",
      "country": "US",
      "state": "CA",
      "zip": "91605"
    },
    "billing": {
      "first_name": "James",
      "last_name": "C Smith",
      "street": "46 Leatherwood St.",
      "suite": "1432",
      "city": "North Hollywood",
      "country": "US",
      "state": "CA",
      "zip": "91605"
    },
    "phone": "any string here"
  },
  "notes": "Some Notes about customer"
}
{
  "id": 6,
  "email": "hello@world.com",
  "first_name": "James",
  "last_name": "C Smith",
  "address": [
    {
      "id": 7,
      "shipping": {
        "first_name": "James",
        "last_name": "C Smith",
        "company": null,
        "street": "46 Leatherwood St.",
        "suite": "1432",
        "city": "North Hollywood",
        "country": "US",
        "state": "CA",
        "zip": "91605"
      },
      "billing": {
        "first_name": "James",
        "last_name": "C Smith",
        "street": "46 Leatherwood St.",
        "suite": "1432",
        "city": "North Hollywood",
        "country": "US",
        "state": "CA",
        "zip": "91605"
      },
      "phone": "any string here"
    }
  ],
  "payment": [],
  "notes": "Some Notes about customer",
  "statistics": {
    "last_purchase": null,
    "order_count": null,
    "lifetime_spent": 0
  },
  "orders": [],
  "tags": [],
  "created_at": 1485004452,
  "updated_at": null
}

Update a customer

 

/customers/id

Update an existing customer.

URL parameters

Parameters that you can append to the URL, for example: ?parameter=value

Title
Type
Description
Required?

id

int

ID of a single customer to update. Can be used after the slash.
Example:
customers/27
update customer with ID 27

Yes

Request body parameters

Parameters that you can send in the request body in JSON format, for example:
{"email": "hello@world.com","first_name": "James"}

Title
Type
Description
Required?

email

string

Email of the customer

No

first_name

string

First name of the customer

No

last_name

string

Last name of the customer

No

address

object containing arrays

One or multiple addresses assigned to the customer

No

address.shipping.first_name

string

First name for shipping

No

address.shipping.last_name

string

Last name for shipping

No

address.shipping.company

string

Company for shipping

No

address.shipping.street

string

Street name for shipping

No

address.shipping.suite

string

Suite for shipping

No

address.shipping.city

string

City for shipping

No

address.shipping.country

string

Country for shipping, 2-letter code as per ISO 3166-1

No

address.shipping.state

string

State/province/region for shipping, 2-letter code as per ISO 3166-2

No

address.shipping.zip

string

Zip/postal code for shipping

No

address.billing.first_name

string

First name for billing

No

address.billing.last_name

string

Last name for billing

No

address.billing.street

string

Street name for billing

No

address.billing.suite

string

Suite for billing

No

address.billing.city

string

City for billing

No

address.billing.country

string

Country for billing, 2-letter code as per ISO 3166-1

No

address.billing.state

string

State/province/region for billing, 2-letter code as per ISO 3166-2

No

address.billing.zip

string

Zip/postal code for billing

No

address.phone

string

Phone for the address

No

notes

string

Notes about the customer, optionally set by the store owner

No

Response attributes

Attributes that you will receive in response from the endpoint in JSON format, for example:
{"email": "hello@world.com","first_name": "James"}

Title
Type
Description

id

int

ID of the customer

email

string

Email of the customer

first_name

string

First name of the customer

last_name

string

Last name of the customer

address

object containing arrays

One or multiple addresses assigned to the customer

address.id

id

ID of the address

address.shipping.first_name

string

First name for shipping

address.shipping.last_name

string

Last name for shipping

address.shipping.company

string

Company for shipping

address.shipping.street

string

Street name for shipping

address.shipping.suite

string

Suite for shipping

address.shipping.city

string

City for shipping

address.shipping.country

string

Country for shipping, 2-letter code as per ISO 3166-1

address.shipping.state

string

State/province/region for shipping, 2-letter code as per ISO 3166-2

address.shipping.zip

string

Zip/postal code for shipping

address.billing.first_name

string

First name for billing

address.billing.last_name

string

Last name for billing

address.billing.street

string

Street name for billing

address.billing.suite

string

Suite for billing

address.billing.city

string

City for billing

address.billing.country

string

Country for billing, 2-letter code as per ISO 3166-1

address.billing.state

string

State/province/region for billing, 2-letter code as per ISO 3166-2

address.billing.zip

string

Zip/postal code for billing

address.phone

string

Phone for the address

payment.type

string

Type of payment method. Can be: Visa, American Express, MasterCard, Discover, JCB, Diners Club, PayPal

payment.last4

string

Last 4 digits of the card number, if paid by card

notes

string

Notes about the customer, optionally set by the store owner

statistics.last_purchase

int

Timestamp of last purchase by the customer

statistics.order_count

int

Number of orders the customer has placed

statistics.lifetime_spent

int

Amount of money spent by customer on this store

orders

array of ints

Array of the customer's order IDs

tags

array of strings

Array containing the tags of all the products that the customer bought

created_at

int

Timestamp of the customer creation time

updated_at

int

Timestamp of the customer last update time

Notes

  • Addresses can be managed manually from the customer profile or flow from orders. Changing an address in a customer profile does not affect orders, but changing the address in an order may affect it in the customer profile.
PATCH https://mystore.commercehq.com/api/v1/customers/30
{
  "email": "hello@world.com",
  "first_name": "James",
  "last_name": "C Smith",
  "address": {
    "shipping": {
      "first_name": "James",
      "last_name": "C Smith",
      "street": "46 Leatherwood St.",
      "suite": "1432",
      "city": "North Hollywood",
      "country": "US",
      "state": "CA",
      "zip": "91605"
    },
    "billing": {
      "first_name": "James",
      "last_name": "C Smith",
      "street": "46 Leatherwood St.",
      "suite": "1432",
      "city": "North Hollywood",
      "country": "US",
      "state": "CA",
      "zip": "91605"
    },
    "phone": "any string here"
  },
  "notes": "Some Notes about customer"
}
{
  "id": 6,
  "email": "hello@world.com",
  "first_name": "James",
  "last_name": "C Smith",
  "address": [
    {
      "id": 7,
      "shipping": {
        "first_name": "James",
        "last_name": "C Smith",
        "company": null,
        "street": "46 Leatherwood St.",
        "suite": "1432",
        "city": "North Hollywood",
        "country": "US",
        "state": "CA",
        "zip": "91605"
      },
      "billing": {
        "first_name": "James",
        "last_name": "C Smith",
        "street": "46 Leatherwood St.",
        "suite": "1432",
        "city": "North Hollywood",
        "country": "US",
        "state": "CA",
        "zip": "91605"
      },
      "phone": "any string here"
    }
  ],
  "payment": [],
  "notes": "Some Notes about customer",
  "statistics": {
    "last_purchase": null,
    "order_count": null,
    "lifetime_spent": 0
  },
  "orders": [],
  "tags": [],
  "created_at": 1485004452,
  "updated_at": 1485004452
}

Update an address

 

/customers/id

Update a single address of an existing customer.
Addresses can be managed manually from the customer profile or flow from orders. Changing an address in a customer profile does not affect orders, but changing the address in an order may affect it in the customer profile.

URL parameters

Parameters that you can append to the URL, for example: ?parameter=value

Title
Type
Description
Required?

id

int

ID of a single customer to update. Can be used after the slash.
Example:
customers/27
update customer with ID 27

Yes

Request body parameters

Parameters that you can send in the request body in JSON format, for example:
{"email": "hello@world.com","first_name": "James"}

Title
Type
Description
Required?

address

array

Array containing the details of the address that should be updated

Yes

address.id

int

ID of the address to update

Yes

address.shipping.first_name

string

First name for shipping

No

address.shipping.last_name

string

Last name for shipping

No

address.shipping.company

string

Company for shipping

No

address.shipping.street

string

Street name for shipping

No

address.shipping.suite

string

Suite for shipping

No

address.shipping.city

string

City for shipping

No

address.shipping.country

string

Country for shipping, 2-letter code as per ISO 3166-1

No

address.shipping.state

string

State/province/region for shipping, 2-letter code as per ISO 3166-2

No

address.shipping.zip

string

Zip/postal code for shipping

No

address.billing.first_name

string

First name for billing

No

address.billing.last_name

string

Last name for billing

No

address.billing.street

string

Street name for billing

No

address.billing.suite

string

Suite for billing

No

address.billing.city

string

City for billing

No

address.billing.country

string

Country for billing, 2-letter code as per ISO 3166-1

No

address.billing.state

string

State/province/region for billing, 2-letter code as per ISO 3166-2

No

address.billing.zip

string

Zip/postal code for billing

No

address.phone

string

Phone for the address

No

Response attributes

Attributes that you will receive in response from the endpoint in JSON format, for example:
{"email": "hello@world.com","first_name": "James"}

Title
Type
Description

id

int

ID of the customer

email

string

Email of the customer

first_name

string

First name of the customer

last_name

string

Last name of the customer

address

object containing arrays

One or multiple addresses assigned to the customer

address.id

id

ID of the address

address.shipping.first_name

string

First name for shipping

address.shipping.last_name

string

Last name for shipping

address.shipping.company

string

Company for shipping

address.shipping.street

string

Street name for shipping

address.shipping.suite

string

Suite for shipping

address.shipping.city

string

City for shipping

address.shipping.country

string

Country for shipping, 2-letter code as per ISO 3166-1

address.shipping.state

string

State/province/region for shipping, 2-letter code as per ISO 3166-2

address.shipping.zip

string

Zip/postal code for shipping

address.billing.first_name

string

First name for billing

address.billing.last_name

string

Last name for billing

address.billing.street

string

Street name for billing

address.billing.suite

string

Suite for billing

address.billing.city

string

City for billing

address.billing.country

string

Country for billing, 2-letter code as per ISO 3166-1

address.billing.state

string

State/province/region for billing, 2-letter code as per ISO 3166-2

address.billing.zip

string

Zip/postal code for billing

address.phone

string

Phone for the address

payment.type

string

Type of payment method. Can be: Visa, American Express, MasterCard, Discover, JCB, Diners Club, PayPal

payment.last4

string

Last 4 digits of the card number, if paid by card

notes

string

Notes about the customer, optionally set by the store owner

statistics.last_purchase

int

Timestamp of last purchase by the customer

statistics.order_count

int

Number of orders the customer has placed

statistics.lifetime_spent

int

Amount of money spent by customer on this store

orders

array of ints

Array of the customer's order IDs

tags

array of strings

Array containing the tags of all the products that the customer bought

created_at

int

Timestamp of the customer creation time

updated_at

int

Timestamp of the customer last update time

PATCH https://mystore.commercehq.com/api/v1/customers/30
{
  "address": {
    "id": 77,
    "shipping": {
      "first_name": "jamie"
    },
    "phone": "123"
  }
}
{
  "id": 6,
  "email": "hello@world.com",
  "first_name": "James",
  "last_name": "C Smith",
  "address": [
    {
      "id": 7,
      "shipping": {
        "first_name": "James",
        "last_name": "C Smith",
        "company": null,
        "street": "46 Leatherwood St.",
        "suite": "1432",
        "city": "North Hollywood",
        "country": "US",
        "state": "CA",
        "zip": "91605"
      },
      "billing": {
        "first_name": "James",
        "last_name": "C Smith",
        "street": "46 Leatherwood St.",
        "suite": "1432",
        "city": "North Hollywood",
        "country": "US",
        "state": "CA",
        "zip": "91605"
      },
      "phone": "any string here"
    }
  ],
  "payment": [],
  "notes": "Some Notes about customer",
  "statistics": {
    "last_purchase": null,
    "order_count": null,
    "lifetime_spent": 0
  },
  "orders": [],
  "tags": [],
  "created_at": 1485004452,
  "updated_at": 1485004452
}

Search customers

 

/customers/search

Search for customers by specified parameters.

Request body parameters

Parameters that you can send in the request body in JSON format, for example:
{"email": "hello@world.com","first_name": "James"}

Title
Type
Description
Required?

email

string

Email of the customer

No

first_name

string

First name of the customer

No

last_name

string

Last name of the customer

No

address

object containing arrays

One or multiple addresses assigned to the customer

No

address.shipping.first_name

string

First name for shipping

No

address.shipping.last_name

string

Last name for shipping

No

address.shipping.company

string

Company for shipping

No

address.shipping.street

string

Street name for shipping

No

address.shipping.suite

string

Suite for shipping

No

address.shipping.city

string

City for shipping

No

address.shipping.country

string

Country for shipping, 2-letter code as per ISO 3166-1

No

address.shipping.state

string

State/province/region for shipping, 2-letter code as per ISO 3166-2

No

address.shipping.zip

string

Zip/postal code for shipping

No

address.billing.first_name

string

First name for billing

No

address.billing.last_name

string

Last name for billing

No

address.billing.street

string

Street name for billing

No

address.billing.suite

string

Suite for billing

No

address.billing.city

string

City for billing

No

address.billing.country

string

Country for billing, 2-letter code as per ISO 3166-1

No

address.billing.state

string

State/province/region for billing, 2-letter code as per ISO 3166-2

No

address.billing.zip

string

Zip/postal code for billing

No

address.phone

string

Phone for the address

No

notes

string

Notes about the customer, optionally set by the store owner

No

Response attributes

Attributes that you will receive in response from the endpoint in JSON format, for example:
{"email": "hello@world.com","first_name": "James"}

Title
Type
Description

id

int

ID of the customer

email

string

Email of the customer

first_name

string

First name of the customer

last_name

string

Last name of the customer

address

object containing arrays

One or multiple addresses assigned to the customer

address.id

id

ID of the address

address.shipping.first_name

string

First name for shipping

address.shipping.last_name

string

Last name for shipping

address.shipping.company

string

Company for shipping

address.shipping.street

string

Street name for shipping

address.shipping.suite

string

Suite for shipping

address.shipping.city

string

City for shipping

address.shipping.country

string

Country for shipping, 2-letter code as per ISO 3166-1

address.shipping.state

string

State/province/region for shipping, 2-letter code as per ISO 3166-2

address.shipping.zip

string

Zip/postal code for shipping

address.billing.first_name

string

First name for billing

address.billing.last_name

string

Last name for billing

address.billing.street

string

Street name for billing

address.billing.suite

string

Suite for billing

address.billing.city

string

City for billing

address.billing.country

string

Country for billing, 2-letter code as per ISO 3166-1

address.billing.state

string

State/province/region for billing, 2-letter code as per ISO 3166-2

address.billing.zip

string

Zip/postal code for billing

address.phone

string

Phone for the address

payment.type

string

Type of payment method. Can be: Visa, American Express, MasterCard, Discover, JCB, Diners Club, PayPal

payment.last4

string

Last 4 digits of the card number, if paid by card

notes

string

Notes about the customer, optionally set by the store owner

statistics.last_purchase

int

Timestamp of last purchase by the customer

statistics.order_count

int

Number of orders the customer has placed

statistics.lifetime_spent

int

Amount of money spent by customer on this store

orders

array of ints

Array of the customer's order IDs

tags

array of strings

Array containing the tags of all the products that the customer bought

created_at

int

Timestamp of the customer creation time

updated_at

int

Timestamp of the customer last update time

Notes

  • Addresses can be managed manually from the customer profile or flow from orders. Changing an address in a customer profile does not affect orders, but changing the address in an order may affect it in the customer profile.
Find the customer with shipping country United States who placed order ID 339 and has 7 orders in total.

POST https://mystore.commercehq.com/api/v1/customers/search
{
    "address": {
        "shipping_country": "US"
    },
    "orders": [339],
    "order_count": 7
}
{
  "items": [
    {
      "id": 6,
      "email": "hello@world.com",
      "first_name": "James",
      "last_name": "C Smith",
      "address": [
        {
          "id": 7,
          "shipping": {
            "first_name": "James",
            "last_name": "C Smith",
            "company": null,
            "street": "46 Leatherwood St.",
            "suite": "1432",
            "city": "North Hollywood",
            "country": "US",
            "state": "CA",
            "zip": "91605"
          },
          "billing": {
            "first_name": "James",
            "last_name": "C Smith",
            "street": "46 Leatherwood St.",
            "suite": "1432",
            "city": "North Hollywood",
            "country": "US",
            "state": "CA",
            "zip": "91605"
          },
          "phone": "any string here"
        }
      ],
      "payment": [],
      "notes": "Some Notes about customer",
      "statistics": {
        "last_purchase": null,
        "order_count": 0,
        "lifetime_spent": 0
      },
      "orders": [],
      "tags": [],
      "created_at": 1485004452,
      "updated_at": 0
    },
    {
      "id": 3,
      "email": "temp5@iwoooky.me",
      "first_name": "Ahmet",
      "last_name": "Zahmut",
      "address": [
        {
          "id": 3,
          "shipping": {
            "first_name": "Ahmet",
            "last_name": "Zahmut",
            "company": null,
            "street": "12 Bomber av.",
            "suite": "suite 1322",
            "city": "New York",
            "country": "US",
            "state": "NY",
            "zip": "M4G 2K6"
          },
          "billing": {
            "first_name": "Ahmet",
            "last_name": "Zahmut",
            "street": "12 Bomber av.",
            "suite": "suite 1322",
            "city": "New York",
            "country": "US",
            "state": null,
            "zip": "M4G 2K6"
          },
          "phone": ""
        }
      ],
      "payment": [
        {
          "type": "Visa",
          "last4": "1111"
        }
      ],
      "notes": null,
      "statistics": {
        "last_purchase": 1484826373,
        "order_count": 1,
        "lifetime_spent": 52
      },
      "orders": [
        4
      ],
      "tags": [],
      "created_at": 1484826370,
      "updated_at": 0
    }
  ],
  "_links": {
    "self": {
      "href": "http://dummy-api.com/api/v1/customers/search?page=1"
    }
  },
  "_meta": {
    "totalCount": 2,
    "pageCount": 1,
    "currentPage": 1,
    "perPage": 20
  }
}

Delete a customer

 

/customers/id

Delete an existing customer.
Only customers without orders can be deleted.

URL parameters

Parameters that you can append to the URL, for example: ?parameter=value

Title
Type
Description
Required?

id

int

ID of a single customer to delete. Can be used after the slash.
Example:
customers/27
delete customer with ID 27

Yes

DELETE https://mystore.commercehq.com/api/v1/customers/30
204 No Content
[]

Load orders

 

/orders

Loads a list of orders or information on a single order.

URL parameters

Parameters that you can append to the URL, for example: ?parameter=value

Title
Type
Description
Required?

id

int

ID of a single orders to load. Can be used after the slash.
Example:
orders/27
load order with ID 27

No

page

int

Number of the page to load. Defaults to 1

No

sort

string

One or more attributes to sort the items by. Defaults to id descending.
For descending, add ! before the attribute name. For multiple attributes, separate them by commas.
Example:
orders?sort=!id,title
sort by descending id first, then by ascending email

No

size

int

Number of items per page. Defaults to 20

No

Response attributes

Attributes that you will receive in response from the endpoint in JSON format, for example:
{"id": 1,"title": "Order"}

Title
Type
Description

id

int

ID of the order, same as the order number. Example: 4041

display_number

string

Order number together with the display prefix/suffix. Example: CH-4041

email

string

Email of the customer

status

int

Fulfilment status. Can be:
0 - Not sent to fulfilment
1 - Partially sent to fulfilment
2 - Partially sent to fulfilment and shipped
3 - Sent to fulfilment
4 - Partially shipped
5 - Shipped

paid

int

Payment status. Can be:
0 - Not paid
1 - Paid
-1 - Partially refunded
-2 - Fully refunded

discounts

object

Discounts related to the order

shipping

array

Shipping details of the order

shipping.description

string

Shipping method description

shipping.price

decimal

Price of shipping

tax

decimal

Tax paid

total

decimal

Total amount of the order

ip

string

IP used to make the order

items

object

Items ordered

items.data

array

Instance of LineItems

items.status

array

Fulfilment status of the item
Includes counter fields:
quantity
not_fulfilled
fulfilled
shipped
restocked

fulfilments

object

Array of Fulfilments for the order

shipments

object

Array of Shipments for the order

restocks

object

Array of Restocks for the order

customer

array

Data about the customer that made the order
Includes fields:
id
email
first_name
last_name

address

array

Instance of Addresses

payment

array

Payment info
Includes fields:
type (e.g. Visa, MasterCard, PayPal)
last4 (last 4 digits of the card, if applicable)

conversion

array

Conversion info
Includes fields:
landing_page
referrer

risk_level

array

Info on fraud risk level
Includes boolean fields:
ip_fail
address_fail
zip_fail
cvc_fail
True values indicate greater risk.

refunded

decimal

Amount refunded

refund_possible

bool

If refunding this order is still possible

order_date

timestamp

Timestamp of when the order was made

updated_at

timestamp

When the order was updated, if at all

notes

string

Field to put optional info in

Loading page number

If you need to load the page number that the order is on using the order ID, you can use this request:

GET https://mystore.commercehq.com/api/v1/orders/1400/page
GET https://mystore.commercehq.com/api/v1/orders/1400
{
      "id": 4041,
      "display_number": "RH4041",
      "email": "tester@testmailhq.com",
      "status": 0,
      "paid": 1,
      "discounts": [],
      "shipping": {
        "description": "Super fast shipping",
        "price": "7.95"
      },
      "tax": 0,
      "total": 21.89,
      "ip": "::1",
      "items": [
        {
          "data": {
            "id": 9550,
            "product_id": 47,
            "title": "Amazing necklace",
            "is_multi": true,
            "type": "Necklace",
            "is_giftcard": false,
            "shipping_weight": 2,
            "vendor": null,
            "auto_fulfilment": false,
            "track_inventory": false,
            "sku": "0170301",
            "price": 13.94,
            "compare_price": 46.5,
            "image": null,
            "image_max_size": 8,
            "variant": {
              "id": 36,
              "variant": [
                "Purple"
              ]
            }
          },
          "status": {
            "quantity": 1,
            "not_fulfilled": 1,
            "fulfilled": 0,
            "shipped": 0,
            "restocked": 0
          }
        }
      ],
      "fulfilments": [],
      "shipments": [],
      "restocks": [],
      "customer": {
        "id": 2819,
        "email": "tester@testmailhq.com",
        "first_name": "Jack",
        "last_name": "Black"
      },
      "address": {
        "shipping": {
          "first_name": "Jack",
          "last_name": "Black",
          "company": null,
          "street": "Grove str.",
          "suite": null,
          "city": "Los Santos",
          "country": "US",
          "state": "San Andreas",
          "zip": "90250"
        },
        "billing": {
          "first_name": "Jack",
          "last_name": "Black",
          "company": null,
          "street": "Long str.",
          "suite": null,
          "city": "Los Santos",
          "country": "US",
          "state": "San Andreas",
          "zip": "90250"
        },
        "phone": null
      },
      "payment": {
        "type": "Visa",
        "last4": "4242"
      },
      "conversion": {
        "landing_page": "http://dummy-client.com/product/amazing-necklace",
        "referrer": "dummy-client.com"
      },
      "risk_level": {
        "ip_fail": false,
        "address_fail": false,
        "zip_fail": false,
        "cvc_fail": false
      },
      "refunded": 0,
      "refund_possible": true,
      "order_date": 1494594582,
      "updated_at": null,
      "notes": null
    },

Search orders

 

/orders/search

Search for orders by specified parameters.

URL parameters

Parameters that you can append to the URL, for example: ?parameter=value

Title
Type
Description
Required?

id

int

ID of a single orders to load. Can be used after the slash.
Example:
orders/27
load order with ID 27

No

page

int

Number of the page to load. Defaults to 1

No

sort

string

One or more attributes to sort the items by. Defaults to id descending.
For descending, add ! before the attribute name. For multiple attributes, separate them by commas.
Example:
orders?sort=!id,title
sort by descending id first, then by ascending email

No

size

int

Number of items per page. Defaults to 20

No

Request body parameters

Parameters that you can send in the request body in JSON format, for example:
{"email": "hello@world.com","first_name": "James"}

Title
Type
Description

id

int

ID of the order, same as the order number. Example: 4041

display_number

string

Order number together with the display prefix/suffix. Example: CH-4041

email

string

Email of the customer

status

int

Fulfilment status. Can be:
0 - Not sent to fulfilment
1 - Partially sent to fulfilment
2 - Partially sent to fulfilment and shipped
3 - Sent to fulfilment
4 - Partially shipped
5 - Shipped

paid

int

Payment status. Can be:
0 - Not paid
1 - Paid
-1 - Partially refunded
-2 - Fully refunded

shipping_description

string

Shipping method description

shipping_price

decimal

Price of shipping

tax

decimal

Tax paid

cart_price

decimal

Sum of all items' prices

total

decimal

Total amount of the order

ip

string

IP used to make the order

customer_id

id

ID of the customer

payment_method

string

e.g. Visa, MasterCard, PayPal

last4

string

Last 4 digits of the card used, if applicable

ip_fail

bool

Whether the IP fraud check failed

address_fail

bool

Whether the address fraud check failed

zip_fail

bool

Whether the zip fraud check failed

cvc_fail

bool

Whether the CVC fraud check failed

refunded

decimal

Amount refunded

refund_possible

bool

If refunding this order is still possible

order_date

timestamp

Timestamp of when the order was made

updated_at

timestamp

When the order was updated, if at all

notes

string

Field to put optional info in

Response

Returns an array of Order objects. Refer to Load orders

Find all orders where the name includes Andrew or Mike
POST https://mystore.commercehq.com/api/v1/orders/1400/search

{
	"full_name": ["Andrew", "Mike"]
}
{
      "id": 4041,
      "display_number": "RH4041",
      "email": "tester@testmailhq.com",
      "status": 0,
      "paid": 1,
      "discounts": [],
      "shipping": {
        "description": "Super fast shipping",
        "price": "7.95"
      },
      "tax": 0,
      "total": 21.89,
      "ip": "::1",
      "items": [
        {
          "data": {
            "id": 9550,
            "product_id": 47,
            "title": "Amazing necklace",
            "is_multi": true,
            "type": "Necklace",
            "is_giftcard": false,
            "shipping_weight": 2,
            "vendor": null,
            "auto_fulfilment": false,
            "track_inventory": false,
            "sku": "0170301",
            "price": 13.94,
            "compare_price": 46.5,
            "image": null,
            "image_max_size": 8,
            "variant": {
              "id": 36,
              "variant": [
                "Purple"
              ]
            }
          },
          "status": {
            "quantity": 1,
            "not_fulfilled": 1,
            "fulfilled": 0,
            "shipped": 0,
            "restocked": 0
          }
        }
      ],
      "fulfilments": [],
      "shipments": [],
      "restocks": [],
      "customer": {
        "id": 2819,
        "email": "tester@testmailhq.com",
        "first_name": "Jack",
        "last_name": "Black"
      },
      "address": {
        "shipping": {
          "first_name": "Jack",
          "last_name": "Black",
          "company": null,
          "street": "Grove str.",
          "suite": null,
          "city": "Los Santos",
          "country": "US",
          "state": "San Andreas",
          "zip": "90250"
        },
        "billing": {
          "first_name": "Jack",
          "last_name": "Black",
          "company": null,
          "street": "Long str.",
          "suite": null,
          "city": "Los Santos",
          "country": "US",
          "state": "San Andreas",
          "zip": "90250"
        },
        "phone": null
      },
      "payment": {
        "type": "Visa",
        "last4": "4242"
      },
      "conversion": {
        "landing_page": "http://dummy-client.com/product/amazing-necklace",
        "referrer": "dummy-client.com"
      },
      "risk_level": {
        "ip_fail": false,
        "address_fail": false,
        "zip_fail": false,
        "cvc_fail": false
      },
      "refunded": 0,
      "refund_possible": true,
      "order_date": 1494594582,
      "updated_at": null,
      "notes": null
    },

Manage fulfilments

 

Create a new fulfilment
POST /orders/ID/fulfilments

{
  "items": [
    {
      "id": "<Int>", // ID of the line item from the order
      "quantity": "<Int>",
      "warehouse": "<Int>" // required when product is track_inventory
    }
  ]
}

Edit all fulfilments
PATCH /orders/ID/fulfilments

[
  {
    "id": 1, // ID of the fulfilment you want to edit
    "items": [
      {
        "id": 11,
        "quantity": 1
      },
      {
        "id": 12,
        "quantity": 1
      }
    ]
  },
  {
    "id": 2,
    "items": [
      {
        "id": 11,
        "quantity": 2
      },
      {
        "id": 12,
        "quantity": 3
      }
    ]
  }
]

Edit a single fulfilment
PATCH /orders/ID/fulfilments/ID

{
  "items": [
    {
      "id": 11,
      "quantity": 1
    },
    {
      "id": 12,
      "quantity": 1
    }
  ],
  "warehouse": "<Int>"
}

Unmark fulfilled
Use this if you wish to delete a fulfilment and set the products back to not fulfilled.
DELETE /orders/ID/fulfilments/ID

Manage shipments

 

For each shipment you create, you need to have a created fulfilment.
You can use a fulfilment for one shipment, as well as create several shipments out of a single fulfilment.

Create a new shipment
POST /orders/ID/shipments

{
  "data": {
    "fulfilment_id": "<Int>", // ID of the fulfilment that is used for the shipment
    "tracking_number": "<String>",
    "shipping_carrier": "<Int>"
  },
  "notify": "<Bool>" // whether user should get an email notification about the shipment
}

Create multiple shipments
POST /orders/ID/shipments

{
  "data": [
    {
      "fulfilment_id": 12, // ID of the fulfilment that is used for the shipment
      "items": [
        {
          "id": 54,
          "quantity": 3,
        }
      ],
      "tracking_number": "<String>",
      "shipping_carrier": "<Int>"
    },
    {
      "fulfilment_id": 12,
      "items": [
        {
          "id": 54,
          "quantity": 1
        }
      ],
      "tracking_number": "<String>",
      "shipping_carrier": "<Int>"
    },
    {
      "fulfilment_id": 13,
      "tracking_number": "<String>",
      "shipping_carrier": "<Int>"
    }
  ],
  "notify": "<Bool>" // whether user should get an email notification about the shipment
}

Edit multiple shipments
PATCH /orders/ID/shipments

{
  "data": [
    {
      "id": "<Int>", // ID of the shipment you wish to edit
      "tracking_number": "<String>",
      "shipping_carrier": "<Int>"
    }
  ],
  "notify": "<Bool>" // whether user should get an email notification about the shipment
}

Edit a single shipment
PATCH /orders/ID/shipments/ID

{
  "data": {
    "tracking_number": "<String>",
    "shipping_carrier": "<Int>"
  },
  "notify": "<Bool>" // whether user should get an email notification about the shipment
}

Unmark shipped
Use this if you wish to delete a shipment and set the products back to fulfilled status.
DELETE /orders/ID/shipments/ID

Refund

 

You can refund an order multiple times until all the money in it is refunded.
Refer to refund_possible in the order object to check if refunding is still possible.
If you wish to restock products in inventory, submit shipments array along with the refund request.

Submit a refund
POST /orders/ID/refund

{
  // shipments are optional, use if you wish to restock products
  "shipments": [
    {
      "id": "<Int>", // ID of the shipment
      // list of products in this shipment, with quantity to restock
      "items": [
        {
          "id": "<Int>", // ID of the line item from the order
          "quantity": "<Int>"
        }
      ]
    }
  ],
  "refund": "<Float>", // amount to refund
  "notify": "<Bool>" // whether customer should be notified by email
}

Edit order

 

At the moment, you can only edit the address, the notes and change the customer in an order.

Edit address
PATCH /orders/ID/address

{
  "shipping": {
    "street": "46 Leatherwood St.",
    "suite": "1432",
    "zip": "91605"
  },
  "billing": {
    "first_name": "James",
    "last_name": "C Smith",
    "street": "46 Leatherwood St."
  }
}

Edit notes
PATCH /orders/ID

{
  "notes": "You can write anything here"
}

Change customer
Changing the customer will set their primary address in the order.
PATCH /orders/ID/customer

{
	"id": 4071 // ID of the new customer to use
}

Export CSV

 

You can export orders into a pre-created CSV template. You can create and manage CSV templates separately, using the CSV API.

Export CSV
POST /orders/ID/exportcsv

{
	"order_ids": [84], // array of order IDs
	"template_id": 1 // ID of the CSV template you wish to use
}

Load shipping carriers

 

/shipping-carriers

Response attributes

Attributes that you will receive in response from the endpoint in JSON format, for example:
{"id": 1,"title": "Order"}.
Data will be wrapped in an items array with _links and _meta appended after it. See How to use get requests.
To use search with custom filters, see How to use search. Refer to field names in the Search field column.

Title
Type
Description
Search field

id

int

ID of the carrier

id

title

string

Title of the carrier

title

url

string

Website URL

url

is_deleted

bool

If the carrier is deleted

is_deleted

GET https://mystore.commercehq.com/api/v1/shipping-carriers
{
  "items": [
    {
      "id": 7,
      "title": "Canada Post",
      "url": "http://www.canadapost.ca/cpotools/apps/track/personal/findByTrackNumber?trackingNumber=",
      "is_deleted": false
    },
    {
      "id": 6,
      "title": "DHL Global",
      "url": "http://webtrack.dhlglobalmail.com/?trackingnumber=",
      "is_deleted": false
    },
    {
      "id": 5,
      "title": "DHL US",
      "url": "http://track.dhl-usa.com/TrackByNbr.asp?ShipmentNumber=",
      "is_deleted": false
    },
    {
      "id": 4,
      "title": "LaserShip",
      "url": "http://www.lasership.com/track/",
      "is_deleted": false
    },
    {
      "id": 3,
      "title": "FedEx",
      "url": "http://www.fedex.com/Tracking?action=track&tracknumbers=",
      "is_deleted": false
    },
    {
      "id": 2,
      "title": "UPS",
      "url": "http://wwwapps.ups.com/WebTracking/track?track=yes&trackNums=",
      "is_deleted": false
    },
    {
      "id": 1,
      "title": "USPS",
      "url": "https://tools.usps.com/go/TrackConfirmAction_input?qtc_tLabels1=",
      "is_deleted": false
    }
  ],
  "_links": {
    "self": {
      "href": "http://dummy-api.com/api/v1/shipping-carriers?page=1"
    }
  },
  "_meta": {
    "totalCount": 7,
    "pageCount": 1,
    "currentPage": 1,
    "perPage": 20
  }
}

Create/update shipping carrier

 

Request body for creating and updating a shipping carrier is the same.

For creating, send a POST request to shipping-carriers
For updating, send a PATCH request to shipping-carriers/ID

Request body parameters

Parameters that you can send in the request body in JSON format, for example:
{"email": "hello@world.com","first_name": "James"}

Title
Type
Description

title

string

Title of the carrier

url

string

Website URL of the carrier

POST https://mystore.commercehq.com/api/v1/shipping-carriers

{
  "title": "UPS",
  "url": "ups.com"
}

Delete shipping carrier

 

To delete a carrier, use the following request:

DELETE shipping-carriers/ID

with an empty request body.

Create a collection

 

/collections

Creates a new collection.

Request body attributes

Parameters that you can send in the request body in JSON format, for example:
{"id": 1,"title": "Campaign"}

Title
Type
Description
Required?

title

string

Title

Yes

is_draft

bool

Defines whether collection is draft or published

No

description

string

Collection description

No

images

array of integers

Array of uploaded images

No

type

integer

Type of collection:
0 - manually added products
1 - rules based

Yes

seo_title

string

SEO title

Yes

seo_url

string

SEO url (e.g. collections/<:value>)

Yes

seo_meta

string

SEO meta description

No

match_products

array of integers

Array of products that were manually added to this collection

Yes, when collection is manual, otherwise NO

rules_match_condition

integer

Defines the way of matching product rules:
0 - match at least one
1 - match all

Yes, when collection is rules-based, otherwise NO

rules

array of objects

Contains array of object defining rules

Yes, when collection is rules-based, otherwise NO

rules.type

integer

Field name
0 - product title
1 - product vendor
2 - product type
3 - product price
4 - product tag
5 - weight
6 - variant title

Yes, when collection is rules-based, otherwise NO

rules.condition

integer

Condition
0 - is exactly
1 - starts with
2 - ends with
3 - contains
4 - does not contain
5 - is equal to
6 - not equal to
7 - greater than
8 - less than

Yes, when collection is rules-based, otherwise NO

rules.value

string|integer

Value

Yes, when collection is rules-based, otherwise NO

Response attributes

Attributes that you will receive in response from the endpoint in JSON format, for example:
{"id": 1,"title": "Campaign"}

Title
Type
Description
Required?

title

string

Title

Yes

is_draft

bool

Defines whether collection is draft or published

No

description

string

Collection description

No

images

array of integers

Array of uploaded images

No

type

integer

Type of collection:
0 - manually added products
1 - rules based

Yes

seo_title

string

SEO title

Yes

seo_url

string

SEO url (e.g. collections/<:value>)

Yes

seo_meta

string

SEO meta description

No

match_products

array of integers

Array of products that were manually added to this collection

Yes, when collection is manual, otherwise NO

rules_match_condition

integer

Defines the way of matching product rules:
0 - match at least one
1 - match all

Yes, when collection is rules-based, otherwise NO

rules

array of objects

Contains array of object defining rules

Yes, when collection is rules-based, otherwise NO

rules.type

integer

Field name
0 - product title
1 - product vendor
2 - product type
3 - product price
4 - product tag
5 - weight
6 - variant title

Yes, when collection is rules-based, otherwise NO

rules.condition

integer

Condition
0 - is exactly
1 - starts with
2 - ends with
3 - contains
4 - does not contain
5 - is equal to
6 - not equal to
7 - greater than
8 - less than

Yes, when collection is rules-based, otherwise NO

rules.value

string|integer

Value

Yes, when collection is rules-based, otherwise NO

POST https://mystore.commercehq.com/api/v1/collections/

{
  "type": 1,
  "seo_url": "rules-based",
  "seo_title": "rules based",
  "title": "rules based",
  "description": "whatever",
  "rules_match_condition": 0,
  "rules": [
    {
      "type": 0,
      "condition": 3,
      "value": "cat"
    }
  ],
  "is_draft": false
}
{
  "id": 10,
  "type": 1,
  "seo_url": "rules-based",
  "seo_title": "rules based",
  "title": "rules based",
  "description": "whatever",
  "rules_match_condition": 0,
  "rules": [
    {
      "type": 0,
      "condition": 3,
      "value": "cat"
    }
  ],
  "is_draft": false
}

Delete a collection

 

/collections/<:id>

Delete an existing campaign.

URL parameters

Parameters that you can append to the URL, for example: ?parameter=value

Title
Type
Description
Required?

id

int

ID of a single collection to delete. Can be used after the slash.
Example:
collections/2
delete collection with ID 2

Yes

DELETE https://mystore.commercehq.com/api/v1/collections/2
204 No Content
[]

Update a collection

 

/collections/<:id>

Update an existing collection.

URL parameters

Parameters that you can append to the URL, for example: ?parameter=value

Title
Type
Description
Required?

id

int

ID of a single collection to update. Can be used after the slash.
Example:
collections/2
update collection with ID 2

Yes

Request body attributes

Parameters that you can send in the request body in JSON format, for example:
{"id": 1,"title": "Campaign"}

Title
Type
Description
Required?

title

string

Title

Yes

is_draft

bool

Defines whether collection is draft or published

No

description

string

Collection description

No

images

array of integers

Array of uploaded images

No

type

integer

Type of collection:
0 - manually added products
1 - rules based

Yes

seo_title

string

SEO title

Yes

seo_url

string

SEO url (e.g. collections/<:value>)

Yes

seo_meta

string

SEO meta description

No

match_products

array of integers

Array of products that were manually added to this collection

Yes, when collection is manual, otherwise NO

rules_match_condition

integer

Defines the way of matching product rules:
0 - match at least one
1 - match all

Yes, when collection is rules-based, otherwise NO

rules

array of objects

Contains array of object defining rules

Yes, when collection is rules-based, otherwise NO

rules.type

integer

Field name
0 - product title
1 - product vendor
2 - product type
3 - product price
4 - product tag
5 - weight
6 - variant title

Yes, when collection is rules-based, otherwise NO

rules.condition

integer

Condition
0 - is exactly
1 - starts with
2 - ends with
3 - contains
4 - does not contain
5 - is equal to
6 - not equal to
7 - greater than
8 - less than

Yes, when collection is rules-based, otherwise NO

rules.value

string|integer

Value

Yes, when collection is rules-based, otherwise NO

Response attributes

Attributes that you will receive in response from the endpoint in JSON format, for example:
{"id": 1,"title": "Campaign"}

Title
Type
Description
Required?

title

string

Title

Yes

is_draft

bool

Defines whether collection is draft or published

No

description

string

Collection description

No

images

array of integers

Array of uploaded images

No

type

integer

Type of collection:
0 - manually added products
1 - rules based

Yes

seo_title

string

SEO title

Yes

seo_url

string

SEO url (e.g. collections/<:value>)

Yes

seo_meta

string

SEO meta description

No

match_products

array of integers

Array of products that were manually added to this collection

Yes, when collection is manual, otherwise NO

rules_match_condition

integer

Defines the way of matching product rules:
0 - match at least one
1 - match all

Yes, when collection is rules-based, otherwise NO

rules

array of objects

Contains array of object defining rules

Yes, when collection is rules-based, otherwise NO

rules.type

integer

Field name
0 - product title
1 - product vendor
2 - product type
3 - product price
4 - product tag
5 - weight
6 - variant title

Yes, when collection is rules-based, otherwise NO

rules.condition

integer

Condition
0 - is exactly
1 - starts with
2 - ends with
3 - contains
4 - does not contain
5 - is equal to
6 - not equal to
7 - greater than
8 - less than

Yes, when collection is rules-based, otherwise NO

rules.value

string|integer

Value

Yes, when collection is rules-based, otherwise NO

PATCH https://mystore.commercehq.com/api/v1/collections/2

{
  "type": 1,
  "seo_url": "rules-based",
  "seo_title": "rules based",
  "title": "rules based",
  "description": "whatever",
  "rules_match_condition": 0,
  "rules": [
    {
      "type": 0,
      "condition": 3,
      "value": "cat"
    }
  ],
  "is_draft": false
}
{
  "id": 2,
  "type": 1,
  "seo_url": "rules-based",
  "seo_title": "rules based",
  "title": "rules based",
  "description": "whatever",
  "rules_match_condition": 0,
  "rules": [
    {
      "type": 0,
      "condition": 3,
      "value": "cat"
    }
  ],
  "is_draft": false
}

Load collections

 

/collections

Loads a list of customers or information on a single customer.

URL parameters

Parameters that you can append to the URL, for example: ?parameter=value

Title
Type
Description
Required?

id

int

ID of a single collection to load. Can be used after the slash.
Example:
collections/27
load collection with ID 27

No

page

int

Number of the page to load. Defaults to 1

No

sort

string

One or more attributes to sort the items by. Defaults to id descending.
For descending, add ! before the attribute name. For multiple attributes, separate them by commas.
Example:
collections?sort=!id
sort by descending id

No

size

int

Number of items per page. Defaults to 20

No

expand

string

Relations that should be extended.
Possible options: products, all
You can use multiple options separated by commas.
Example:
collections?expand=products
Load collections with products
Use all to load all relations.

No

Response attributes

Attributes that you will receive in response from the endpoint in JSON format, for example:
{"email": "hello@world.com","first_name": "James"}

Title
Type
Description
Required?

title

string

Title

Yes

is_draft

bool

Defines whether collection is draft or published

No

description

string

Collection description

No

images

array of integers

Array of uploaded images

No

type

integer

Type of collection:
0 - manually added products
1 - rules based

Yes

seo_title

string

SEO title

Yes

seo_url

string

SEO url (e.g. collections/<:value>)

Yes

seo_meta

string

SEO meta description

No

match_products

array of integers

Array of products that were manually added to this collection

Yes, when collection is manual, otherwise NO

rules_match_condition

integer

Defines the way of matching product rules:
0 - match at least one
1 - match all

Yes, when collection is rules-based, otherwise NO

rules

array of objects

Contains array of object defining rules

Yes, when collection is rules-based, otherwise NO

rules.type

integer

Field name
0 - product title
1 - product vendor
2 - product type
3 - product price
4 - product tag
5 - weight
6 - variant title

Yes, when collection is rules-based, otherwise NO

rules.condition

integer

Condition
0 - is exactly
1 - starts with
2 - ends with
3 - contains
4 - does not contain
5 - is equal to
6 - not equal to
7 - greater than
8 - less than

Yes, when collection is rules-based, otherwise NO

rules.value

string|integer

Value

Yes, when collection is rules-based, otherwise NO

{
  "id": 10,
  "type": 1,
  "seo_url": "rules-based",
  "seo_title": "rules based",
  "title": "rules based",
  "description": "whatever",
  "rules_match_condition": 0,
  "rules": [
    {
      "type": 0,
      "condition": 3,
      "value": "cat"
    }
  ],
  "is_draft": false
}

Upload a file

 

/files

Uploads a new file

Request body attributes

You have to send data with multipart/form-data type

Title
Type
Description
Required?

files

array of files

Files itself

Yes

type

string

Type of files, possible values:
thumbnails, product_images,
variant_images,
abandoned_email_logo,
review_email_logo,
review_image,
collection_images,
checkout_settings_logo,
security_badge_images

No

Response attributes

Attributes that you will receive in response from the endpoint in JSON format, for example:
{"id": 1,"title": "Campaign"}

Title
Type
Description
Required?

id

integer

File id

Yes

mime

bool

Whether this campaign is published or not

Yes

is_image

string

Title of the campaign

Yes

image_max_size_available

integer

Maximum available size constant, possible values:
0 - original
1 - tiny
2 - icon
3 - thumbnail
4 - mini
5 - small
6 - medium
7 - large
8 - jumbo
9 - full
10 - master

Yes

name

string

Name of the file

Yes

url

string

Relative path

Yes

size

integer

File size in bytes

Yes

image_width

integer

Image width

Yes

image_height

integer

Image height

Yes

theme_id

integer

ID of theme file was uploaded for

No

type

string

Type of file, possible values:
thumbnails, product_images,
variant_images,
abandoned_email_logo,
review_email_logo,
review_image,
collection_images,
checkout_settings_logo,
security_badge_images

Yes

full_url

string

Full url to this file

Yes

[
  {
    "id": 453,
    "mime": "image\/jpeg",
    "is_image": 1,
    "image_max_size_available": 8,
    "name": "perfectly-timed-cat-photos-funny-cover.jpg",
    "url": "uploads\/1497530431_03c309ebc4af299f4ab3572b2fc1005481571327.jpg",
    "size": 65206,
    "image_width": 750,
    "image_height": 420,
    "theme_id": null,
    "type": "files",
    "full_url": "https:\/\/s3-us-west-2.amazonaws.com\/commercehq-userfiles-dev\/commercehq-test\/uploads\/1497530431_03c309ebc4af299f4ab3572b2fc1005481571327.jpg"
  }
]

Load files

 

/files

Loads a list of abandoned checkout campaigns or information on a single campaign.

URL parameters

Parameters that you can append to the URL, for example: ?parameter=value

Title
Type
Description
Required?

page

int

Number of the page to load. Defaults to 1

No

size

int

Number of items per page. Defaults to 20

No

Response attributes

Attributes that you will receive in response from the endpoint in JSON format, for example:
{"id": 1,"title": "Campaign"}

Title
Type
Description
Required?

id

integer

File id

Yes

mime

bool

Whether this campaign is published or not

Yes

is_image

string

Title of the campaign

Yes

image_max_size_available

integer

Maximum available size constant, possible values:
0 - original
1 - tiny
2 - icon
3 - thumbnail
4 - mini
5 - small
6 - medium
7 - large
8 - jumbo
9 - full
10 - master

Yes

name

string

Name of the file

Yes

url

string

Relative path

Yes

size

integer

File size in bytes

Yes

image_width

integer

Image width

Yes

image_height

integer

Image height

Yes

theme_id

integer

ID of theme file was uploaded for

No

type

string

Type of file, possible values:
thumbnails, product_images,
variant_images,
abandoned_email_logo,
review_email_logo,
review_image,
collection_images,
checkout_settings_logo,
security_badge_images

Yes

full_url

string

Full url to this file

Yes

GET https://mystore.commercehq.com/api/v1/files
[
  {
    "id": 453,
    "mime": "image\/jpeg",
    "is_image": 1,
    "image_max_size_available": 8,
    "name": "perfectly-timed-cat-photos-funny-cover.jpg",
    "url": "uploads\/1497530431_03c309ebc4af299f4ab3572b2fc1005481571327.jpg",
    "size": 65206,
    "image_width": 750,
    "image_height": 420,
    "theme_id": null,
    "type": "files",
    "full_url": "https:\/\/s3-us-west-2.amazonaws.com\/commercehq-userfiles-dev\/commercehq-test\/uploads\/1497530431_03c309ebc4af299f4ab3572b2fc1005481571327.jpg"
  }
]

Delete a file

 

/files/<:id>

Delete an existing campaign.

URL parameters

Parameters that you can append to the URL, for example: ?parameter=value

Title
Type
Description
Required?

id

int

ID of a single campaign to delete. Can be used after the slash.
Example:
files/2
delete file with ID 2

Yes

DELETE https://mystore.commercehq.com/api/v1/files/2
204 No Content
[]