Products

The Products resource allows users to add their products to the BoxC system. A product can have one or more Stock Keeping Units (SKUs). This gives users the ability to link their different shops' SKUs to the same product. There can only be one active SKU per shop per product. Orders won't be fulfilled until the warehouse accepts and processes your products. This includes measuring the weight and dimensions, and updating the quantity.

Note: Products and SKUs linked to orders can't be deleted. Existing SKUs can't be assigned to a different shop.

Actions

GET /products Retrieves a paginated list of products
GET /products/{id} Retrieves a product
POST /products Creates a product
POST /products/barcodes Create a PDF with up to 100 barcodes
PUT /products/{id} Updates a product
DELETE /products/{id} Deletes a product
POST /products/{id}/skus Adds a SKU to a product
PUT /products/{id}/shop/{id}/sku/{id} Updates a SKU
DELETE /products/{id}/shop/{id}/sku/{id} Deletes a SKU

Properties

backordered

{"backordered": 43}

Integer - The quantity that's backordered for this product. Set by the system.
barcode

{"barcode": "4011200296908"}

String - The barcode for this product such as UPC, EAN, ISBN, etc. Max length: 32. Default: product ID.
coo

{"coo": "CN"}

String - The country of origin or where the product was manufactured in ISO 3166-1 alpha-2 format for Customs. Required.
cost

{"cost": 4.20}

Decimal - The product cost value in USD. Important for insurance claims. Default: 0.
created

{"created": "2020-10-20 10:11:12"}

String - The datetime in UTC the product was created. Set by the system.
description

{"description": "100% Cotton Shirt"}

String - The product description for reference. Required. Max length: 64.
dg_code

{"dg_code": "0966"}

String - A code that identifies dangerous goods. Required if shipping lithium batteries, ORM-D, or other dangerous goods. Refer to this page for a list of codes and further information. Default: null.
dimensions 

{
    "dimensions": {
        "width": 1.5,
        "height": 0.75
    }
}

Object - The dimensions of the barcode in inches. Only used for bulk printing barcode labels.

height: The height of the PDF. Min: 0.5, Max: 4, Default: 1
width: The width of the PDF. Min: 0.5, Max: 4, Default: 2
height

{"height": 5}

Integer - The product height in CM. Set by the system.
hs_codes 

{
    "hs_codes": [
        {
            "country": "US",
            "hs_code": "3109165102"
        },
        {
            "country": "CN",
            "hs_code": "0302410090"
        }
    ]
}

Array - An array of objects containing HS codes used for Customs clearance in different countries. Some countries or services require an HS code for import and/or export. Optional. Remove countries' HS codes from the product by omitting the objects you no longer want associated in an update request. Remove all HS codes by passing an empty array.

country: String - The country code. Required.
hs_code: String - Harmonized System classification number. Required.
id

{"id": 20191}

Integer - The product ID. Set by the system.
is_packaging

{"is_packaging": true}

Boolean - Indicates if this product is using for packaging at the warehouse. Immutable. Optional. Default: false.
length

{"length": 12}

Integer - The product length in CM. Set by the system.
local_descriptions 

{
    "local_descriptions": [
        {
            "description": "100% Cotton T-Shirt",
            "language_code": "en"
        },
        {
            "description": "\u6bdb\u8863",
            "language_code": "zh"
        }
    ]
}

Array - A list of product descriptions in different languages. Only used to update the description in a warehouse's local language. It will update all descriptions with a matching language_code. Required if the product is actually inventoried at warehouses.

description: String - The product description in the language indicated by language_code. Required. Max length: 64
language_code: String - The local language code for the warehouse in ISO 639-1 format. Required.
name

{"name": "XL Pink T-Shirt"}

String - The product name to help identify the product. Required. Min length: 3. Max length: 64.
quantity

{"quantity": 544}

Integer - The quantity on hand across all warehouses. Set by the system.
skus 

{
    "skus": [
        {
            "active": true,
            "shop_id": "my-shop",
            "sku": "SK10291"
        },
        {
            "active": false,
            "shop_id": "my-shop",
            "sku": "08X092"
        }
    ]
}

Array - An array of SKUs that reference this product. Required.

active: Boolean - Whether or not this SKU is active. Orders with an inactive SKU will not be imported or created. Default: true.
shop_id: String - The shop ID associated with this SKU. Required.
sku: String - The SKU identifier. Required. Min length: 3. Max length: 32.
value

{"value": 19.99}

Decimal - The product retail value in USD. Required.
warehouses 

{
    "warehouses": [
        {
            "description": "\u6bdb\u8863",
            "id": "WH0HK001",
            "language": "Chinese",
            "language_code": "zh",
            "quantity": 102
        },
        {
            "description": "\u6bdb\u8863",
            "id": "WH0SZ001",
            "language": "Chinese",
            "language_code": "zh",
            "quantity": 0
        }
    ]
}

Array - An array of warehouses and their inventory for this product. Only present when retrieving a single product. Set by the system.

description: String - The product description in the local language.
id: String - The unique warehouse ID.
language: String - The local language for the warehouse.
language_code: String - The local language code for the warehouse in ISO 639-1 format.
quantity: Integer - The quantity on hand.
weight

{"weight": 0.325}

Decimal - The product weight in KG. Set by the system.
width

{"width": 10}

Integer - The product width in CM. Set by the system.
GET
/products/{id}
Retrieves a product
type The data stream type for printing the product barcode. Only PDF is accepted.
height The height of the barcode in inches. Default: 1. Min: 0.5, Max: 4
width The width of the barcode in inches. Default: 2. Min: 0.5, Max: 4
request
GET /products/1946
response

HTTP/1.1 200 OK

{
    "product": {
        "backordered": 0,
        "barcode": "1946",
        "coo": "CN",
        "cost": "4.55",
        "created": "2020-10-20 16:18:08",
        "description": "Black bikini swimwear - SM",
        "dg_code": null,
        "height": "0",
        "hs_codes": [
            {
                "country": "US",
                "hs_code": "1234567890"
            }
        ],
        "id": 1946,
        "length": "0",
        "name": "Bikini - SM",
        "quantity": 0,
        "skus": [
            {
                "active": true,
                "shop_id": "boxctestshop",
                "sku": "SKU12345678"
            }
        ],
        "value": "25.00",
        "warehouses": [],
        "weight": "0.000",
        "width": "0"
    }
}
request
GET /products/20192 
type=pdf&size=1.5x0.75
response

HTTP/1.1 200 OK

[blob]
POST
/products
Creates a product
request
POST /products 
{
    "product": {
        "barcode": null,
        "cost": 4.20,
        "coo": "CN",
        "dg_code": null,
        "name": "Bikini - XS",
        "value": 29.95,
        "description": "Red bikini swimwear - XS",
        "hs_codes": [
            {
                "country": "US",
                "hs_code": "12345668"
            },
            {
                "country": "US",
                "hs_code": "12345669"
            },
            {
                "country": "CN",
                "hs_code": "98762212"
            }
        ]
    }
}
response

HTTP/1.1 201 Created

{
    "product": {
        "backordered": 0,
        "barcode": "1946",
        "coo": "CN",
        "cost": 4.2,
        "created": "2020-10-20 16:18:08",
        "description": "Red bikini swimwear - XS",
        "dg_code": null,
        "height": 0,
        "hs_codes": [
            {
                "country": "CN",
                "hs_code": "98762212"
            },
            {
                "country": "US",
                "hs_code": "12345669"
            }
        ],
        "id": 1946,
        "length": 0,
        "name": "Bikini - XS",
        "quantity": 0,
        "skus": [],
        "value": 29.95,
        "warehouses": [],
        "weight": 0,
        "width": 0
    }
}
request
POST /products 
{
    "product": {
        "barcode": null,
        "cost": 4.20,
        "coo": "CN",
        "dg_code": null,
        "name": "Bikini - SM",
        "value": 29.95,
        "description": "Blue bikini swimwear - SM",
        "local_descriptions": [
            {
                "description": "Cotton blue bikini swimwear",
                "language_code": "en"
            },
            {
                "description": "棉蓝色比基尼泳装",
                "language_code": "zh"
            }
        ],
        "hs_codes": []
    }
}
response

HTTP/1.1 201 Created

{
    "product": {
        "backordered": 0,
        "barcode": "1947",
        "coo": "CN",
        "cost": 4.2,
        "created": "2020-10-20 16:28:59",
        "description": "Blue bikini swimwear - SM",
        "dg_code": null,
        "height": 0,
        "hs_codes": [],
        "id": 1947,
        "length": 0,
        "name": "Bikini - SM",
        "quantity": 0,
        "skus": [],
        "value": 29.95,
        "warehouses": [
            {
                "description": "Cotton blue bikini swimwear",
                "id": "WH0CVG01",
                "language": "English",
                "language_code": "en",
                "quantity": 0
            },
            {
                "description": "Cotton blue bikini swimwear",
                "id": "WH0JFK01",
                "language": "English",
                "language_code": "en",
                "quantity": 0
            },
            {
                "description": "棉蓝色比基尼泳装",
                "id": "WH0HKG01",
                "language": "Chinese",
                "language_code": "zh",
                "quantity": 0
            },
            {
                "description": "棉蓝色比基尼泳装",
                "id": "WH0SZX02",
                "language": "Chinese",
                "language_code": "zh",
                "quantity": 0
            }
        ],
        "weight": 0,
        "width": 0
    }
}
POST
/products/barcodes
Create a PDF with up to 100 barcodes
request
POST /products/barcodes 
{
    "barcodes": {
        "dimensions": {
            "width": 1.5,
            "height": 0.75
        },
        "products": [
            100001,
            100002,
            100003,
            "..."
        ]
    }
}
response

HTTP/1.1 201 Created

[blob]
PUT
/products/{id}
Updates a product
request
PUT /products/1946 
{
    "product": {
        "cost": 4.55,
        "coo": "CN",
        "dg_code": null,
        "name": "Bikini - SM",
        "value": 25,
        "description": "Black bikini swimwear - SM",
        "hs_codes": [
            {
                "country": "US",
                "hs_code": "1234567890"
            }
        ]
    }
}
response

HTTP/1.1 200 OK

{
    "product": {
        "backordered": 0,
        "barcode": "1946",
        "coo": "CN",
        "cost": 4.55,
        "created": "2020-10-20 16:18:08",
        "description": "Black bikini swimwear - SM",
        "dg_code": null,
        "height": "0",
        "hs_codes": [
            {
                "country": "US",
                "hs_code": "1234567890"
            }
        ],
        "id": 1946,
        "length": "0",
        "name": "Bikini - SM",
        "quantity": 0,
        "skus": [
            {
                "active": true,
                "shop_id": "boxctestshop",
                "sku": "SKU12345678"
            }
        ],
        "value": 25,
        "warehouses": [],
        "weight": "0.000",
        "width": "0"
    }
}
response
PUT /products/1946 
{
    "product": {
        "cost": 4.55,
        "coo": "CN",
        "dg_code": null,
        "name": "Bikini - SM",
        "value": 25,
        "description": "Black bikini swimwear - SM",
        "hs_codes": []
    }
}
response

HTTP/1.1 200 OK

{
    "product": {
        "backordered": 0,
        "barcode": "1946",
        "coo": "CN",
        "cost": 4.55,
        "created": "2020-10-20 16:18:08",
        "description": "Black bikini swimwear - SM",
        "dg_code": null,
        "height": "0",
        "hs_codes": [],
        "id": 1946,
        "length": "0",
        "name": "Bikini - SM",
        "quantity": 0,
        "skus": [
            {
                "active": true,
                "shop_id": "boxctestshop",
                "sku": "SKU12345678"
            }
        ],
        "value": 25,
        "warehouses": [],
        "weight": "0.000",
        "width": "0"
    }
}
DELETE
/products/{id}
Deletes a product
request
DELETE /products/20192
response

HTTP/1.1 200 OK


		

	






	

		
POST

		
/products/{id}/skus

	

	

		Adds a SKU to a product
	

	

		

			
request

			POST /products/1946/skus
			
{
    "sku": {
        "active": true,
        "shop_id": "boxctestshop",
        "sku": "SKU123456"
    }
}

		

		

		

			
response

			
HTTP/1.1 201 Created

			
{
    "product": {
        "backordered": 0,
        "barcode": "1946",
        "coo": "CN",
        "cost": "4.20",
        "created": "2020-10-20 16:18:08",
        "description": "Red bikini swimwear - XS",
        "dg_code": null,
        "height": "0",
        "hs_codes": [
            {
                "country": "CN",
                "hs_code": "98762212"
            },
            {
                "country": "US",
                "hs_code": "12345669"
            }
        ],
        "id": 1946,
        "length": "0",
        "name": "Bikini - XS",
        "quantity": 0,
        "skus": [
            {
                "active": true,
                "shop_id": "boxctestshop",
                "sku": "SKU123456"
            }
        ],
        "value": "29.95",
        "warehouses": [],
        "weight": "0.000",
        "width": "0"
    }
}

		

	






	

		
PUT

		
/products/{id}/shop/{id}/sku/{id}

	

	

		Updates an existing SKU for a given product and shop.
	

	

		

			
request

			PUT /products/1946/shop/boxctestshop/sku/SKU123456
			
{
    "sku": {
        "active": true,
        "sku": "SKU12345678"
    }
}

		

		

		

			
response

			
HTTP/1.1 200 OK

			
{
    "product": {
        "backordered": 0,
        "barcode": "1946",
        "coo": "CN",
        "cost": "4.20",
        "created": "2020-10-20 16:18:08",
        "description": "Red bikini swimwear - XS",
        "dg_code": null,
        "height": "0",
        "hs_codes": [
            {
                "country": "CN",
                "hs_code": "98762212"
            },
            {
                "country": "US",
                "hs_code": "12345669"
            }
        ],
        "id": 1946,
        "length": "0",
        "name": "Bikini - XS",
        "quantity": 0,
        "skus": [
            {
                "active": true,
                "shop_id": "boxctestshop",
                "sku": "SKU12345678"
            }
        ],
        "value": "29.95",
        "warehouses": [],
        "weight": "0.000",
        "width": "0"
    }
}

		

	






	

		
DELETE

		
/products/{id}/shop/{id}/sku/{id}

	

	

		Deletes a SKU if it's not being used by orders.
	

	

		

			
request

			DELETE /products/1946/shop/boxctestshop/sku/SKU12345678
		

		

		

			
response

			
HTTP/1.1 200 OK