Skus

SKUs describe specific product variations that are being sold. A unique code identifies each SKU, that can be either the EAN code, the UPC or any other code format. The SKU name, description and image URL are best suited for internal usage (Commerce Layer is not a CMS).

The sku object

A sku object is returned as part of the response body of each successful create, list, retrieve or update API call. The following table contains the list of all its fields along with their type, description and example values.
Object fields:
code
string
The sku code, that uniquely identifies the sku within the organization.
Example:
TSHIRTMM000000FFFFFFXLXX
name
string
The internal name of the sku.
Example:
Black Men T-shirt with White Logo (XL)
description
string
An internal description of the sku.
Example:
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
image_url
string
The URL of an image that represents the sku.
Example:
https://img.yourbrand.com/skus/1234.png
tag_names
string
A comma separated list of tags.
Example:
Men, Black, XL
pieces_per_pack
integer
The number of pieces that compose the sku. This is useful to describe sets and bundles.
Example:
6
weight
float
The weight of the sku. If present, it will be used to calculate the shipping rates.
Example:
300
unit_of_weight
string
Can be one of 'gr' or 'oz'
Example:
gr
inventory
object
Aggregated information about the SKU's inventory. Returned only when retrieving a single SKU with a Channel application.
Example:
{"available":true,"quantity":10,"levels":[{"quantity":4,"delivery_lead_times":[{"shipping_method":{"name":"Standard Shipping","reference":null,"price_amount_cents":700,"free_over_amount_cents":9900,"formatted_price_amount":"€7,00","formatted_free_over_amount":"€99,00"},"min":{"hours":72,"days":3},"max":{"hours":120,"days":5}},{"shipping_method":{"name":"Express Delivery","reference":null,"price_amount_cents":1200,"free_over_amount_cents":null,"formatted_price_amount":"€12,00","formatted_free_over_amount":null},"min":{"hours":48,"days":2},"max":{"hours":72,"days":3}}]},{"quantity":6,"delivery_lead_times":[{"shipping_method":{"name":"Standard Shipping","reference":null,"price_amount_cents":700,"free_over_amount_cents":9900,"formatted_price_amount":"€7,00","formatted_free_over_amount":"€99,00"},"min":{"hours":96,"days":4},"max":{"hours":144,"days":6}},{"shipping_method":{"name":"Express Delivery","reference":null,"price_amount_cents":1200,"free_over_amount_cents":null,"formatted_price_amount":"€12,00","formatted_free_over_amount":null},"min":{"hours":72,"days":3},"max":{"hours":96,"days":4}}]}]}
id
integer
Unique identifier for the resource.
Example:
1234
created_at
datetime
Time at which the resource was created.
Example:
2018-01-01T12:00:00.000Z
updated_at
datetime
Time at which the resource was last updated.
Example:
2018-01-01T12:00:00.000Z
reference
string
A string that you can use to add your own identifier to the resource. This can be useful for intergrating the resource to an external system, like an ERP, a marketing tool or a CRM.
Example:
ANYREFEFERNCE
metadata
object
Set of key-value pairs that you can attach to the resource. This can be useful for storing additional information about the resource in a structured format.
Example:
{"foo":"bar"}
relationship (N:1)
The sku's shipping category
relationship (1:N)
The list of prices associated with the sku.
relationship (1:N)
The list of stock items associated with the sku.
relationship (1:N)
The list of delivery lead times associated with the sku.
relationship (1:N)
The list of sku options available for the sku.

Create a sku

To create a new sku, send a POST request to the /api/skus endpoint, passing the resource arguments in the request body. The following table contains the list of all the possible arguments, along with their type, description and examples values. All the arguments marked as required must be present in the request.
Arguments:
code
required
The sku code, that uniquely identifies the sku within the organization.
Example:
TSHIRTMM000000FFFFFFXLXX
name
required
The internal name of the sku.
Example:
Black Men T-shirt with White Logo (XL)
description
optional
An internal description of the sku.
Example:
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
image_url
optional
The URL of an image that represents the sku.
Example:
https://img.yourbrand.com/skus/1234.png
tag_names
optional
A comma separated list of tags.
Example:
Men, Black, XL
pieces_per_pack
optional
The number of pieces that compose the sku. This is useful to describe sets and bundles.
Example:
6
weight
optional
The weight of the sku. If present, it will be used to calculate the shipping rates.
Example:
300
unit_of_weight
optional
Can be one of 'gr' or 'oz'
Example:
gr
reference
optional
A string that you can use to add your own identifier to the resource. This can be useful for intergrating the resource to an external system, like an ERP, a marketing tool or a CRM.
Example:
ANYREFEFERNCE
metadata
optional
Set of key-value pairs that you can attach to the resource. This can be useful for storing additional information about the resource in a structured format.
Example:
#
The sku's shipping category
Example request:
POST /api/skus HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": {
    "type": "skus",
    "attributes": {
      "code": "TSHIRTMM000000FFFFFFXLXX",
      "name": "Black Men T-shirt with White Logo (XL)"
    },
    "relationships": {
      "shipping_category": {
        "data": {
          "type": "shipping_categories",
          "id": "1234"
        }
      }
    }
  }
}
Example response: 201 Created
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json

{
  "data": {
    "id": "1234",
    "type": "skus",
    "links": {
      "self": "https://your-brand.commercelayer.io/api/skus/1234"
    },
    "attributes": {
      "code": "TSHIRTMM000000FFFFFFXLXX",
      "name": "Black Men T-shirt with White Logo (XL)",
      "description": "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
      "image_url": "https://img.yourbrand.com/skus/1234.png",
      "tag_names": "Men, Black, XL",
      "pieces_per_pack": "6",
      "weight": "300",
      "unit_of_weight": "gr",
      "inventory": {
        "available": true,
        "quantity": 10,
        "levels": [
          {
            "quantity": 4,
            "delivery_lead_times": [
              {
                "shipping_method": {
                  "name": "Standard Shipping",
                  "reference": null,
                  "price_amount_cents": 700,
                  "free_over_amount_cents": 9900,
                  "formatted_price_amount": "€7,00",
                  "formatted_free_over_amount": "€99,00"
                },
                "min": {
                  "hours": 72,
                  "days": 3
                },
                "max": {
                  "hours": 120,
                  "days": 5
                }
              },
              {
                "shipping_method": {
                  "name": "Express Delivery",
                  "reference": null,
                  "price_amount_cents": 1200,
                  "free_over_amount_cents": null,
                  "formatted_price_amount": "€12,00",
                  "formatted_free_over_amount": null
                },
                "min": {
                  "hours": 48,
                  "days": 2
                },
                "max": {
                  "hours": 72,
                  "days": 3
                }
              }
            ]
          },
          {
            "quantity": 6,
            "delivery_lead_times": [
              {
                "shipping_method": {
                  "name": "Standard Shipping",
                  "reference": null,
                  "price_amount_cents": 700,
                  "free_over_amount_cents": 9900,
                  "formatted_price_amount": "€7,00",
                  "formatted_free_over_amount": "€99,00"
                },
                "min": {
                  "hours": 96,
                  "days": 4
                },
                "max": {
                  "hours": 144,
                  "days": 6
                }
              },
              {
                "shipping_method": {
                  "name": "Express Delivery",
                  "reference": null,
                  "price_amount_cents": 1200,
                  "free_over_amount_cents": null,
                  "formatted_price_amount": "€12,00",
                  "formatted_free_over_amount": null
                },
                "min": {
                  "hours": 72,
                  "days": 3
                },
                "max": {
                  "hours": 96,
                  "days": 4
                }
              }
            ]
          }
        ]
      },
      "id": "1234",
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": "ANYREFEFERNCE",
      "metadata": {
        "foo": "bar"
      }
    },
    "relationships": {
      "shipping_category": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/skus/1234/relationships/shipping_category",
          "related": "https://your-brand.commercelayer.io/api/skus/1234/shipping_category"
        }
      },
      "prices": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/skus/1234/relationships/prices",
          "related": "https://your-brand.commercelayer.io/api/skus/1234/prices"
        }
      },
      "stock_items": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/skus/1234/relationships/stock_items",
          "related": "https://your-brand.commercelayer.io/api/skus/1234/stock_items"
        }
      },
      "delivery_lead_times": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/skus/1234/relationships/delivery_lead_times",
          "related": "https://your-brand.commercelayer.io/api/skus/1234/delivery_lead_times"
        }
      },
      "sku_options": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/skus/1234/relationships/sku_options",
          "related": "https://your-brand.commercelayer.io/api/skus/1234/sku_options"
        }
      }
    },
    "meta": {
      "mode": "test"
    }
  }
}

List all skus

To fetch a collection of skus, send a GET request to the /api/skus endpoint.

Example request:
GET /api/skus HTTP/1.1
Accept: application/vnd.api+json
Example response: 200 OK
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": [
    {
      "id": "1234",
      "type": "skus",
      "links": {
        "self": "https://your-brand.commercelayer.io/api/skus/1234"
      },
      "attributes": {
        "code": "TSHIRTMM000000FFFFFFXLXX",
        "name": "Black Men T-shirt with White Logo (XL)",
        "description": "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
        "image_url": "https://img.yourbrand.com/skus/1234.png",
        "tag_names": "Men, Black, XL",
        "pieces_per_pack": "6",
        "weight": "300",
        "unit_of_weight": "gr",
        "id": "1234",
        "created_at": "2018-01-01T12:00:00.000Z",
        "updated_at": "2018-01-01T12:00:00.000Z",
        "reference": "ANYREFEFERNCE",
        "metadata": {
          "foo": "bar"
        }
      },
      "relationships": {
        "shipping_category": {
          "links": {
            "self": "https://your-brand.commercelayer.io/api/skus/1234/relationships/shipping_category",
            "related": "https://your-brand.commercelayer.io/api/skus/1234/shipping_category"
          }
        },
        "prices": {
          "links": {
            "self": "https://your-brand.commercelayer.io/api/skus/1234/relationships/prices",
            "related": "https://your-brand.commercelayer.io/api/skus/1234/prices"
          }
        },
        "stock_items": {
          "links": {
            "self": "https://your-brand.commercelayer.io/api/skus/1234/relationships/stock_items",
            "related": "https://your-brand.commercelayer.io/api/skus/1234/stock_items"
          }
        },
        "delivery_lead_times": {
          "links": {
            "self": "https://your-brand.commercelayer.io/api/skus/1234/relationships/delivery_lead_times",
            "related": "https://your-brand.commercelayer.io/api/skus/1234/delivery_lead_times"
          }
        },
        "sku_options": {
          "links": {
            "self": "https://your-brand.commercelayer.io/api/skus/1234/relationships/sku_options",
            "related": "https://your-brand.commercelayer.io/api/skus/1234/sku_options"
          }
        }
      },
      "meta": {
        "mode": "test"
      }
    },
    {
      "other": "... 24 skus (first page)"
    }
  ],
  "meta": {
    "record_count": 125,
    "page_count": 5
  },
  "links": {
    "first": "/api/skus?page[number]=1&page[size]=25",
    "prev": "/api/skus?page[number]=2&page[size]=25",
    "next": "/api/skus?page[number]=4&page[size]=25",
    "last": "/api/skus?page[number]=5&page[size]=25"
  }
}
Available filters
idcodereferenceshipping_category_ididscreated_at_fromcreated_at_toupdated_at_fromupdated_at_totagscodes
Sortable attributes
codeidcreated_atupdated_atreference

Retrieve a sku

To fetch a single sku, send a GET request to the /api/skus/{{id}} endpoint, where {{id}} is the id of the resource that you want to retrieve.
Example request:
GET /api/skus/1234 HTTP/1.1
Accept: application/vnd.api+json
Example response: 200 OK
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": {
    "id": "1234",
    "type": "skus",
    "links": {
      "self": "https://your-brand.commercelayer.io/api/skus/1234"
    },
    "attributes": {
      "code": "TSHIRTMM000000FFFFFFXLXX",
      "name": "Black Men T-shirt with White Logo (XL)",
      "description": "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
      "image_url": "https://img.yourbrand.com/skus/1234.png",
      "tag_names": "Men, Black, XL",
      "pieces_per_pack": "6",
      "weight": "300",
      "unit_of_weight": "gr",
      "inventory": {
        "available": true,
        "quantity": 10,
        "levels": [
          {
            "quantity": 4,
            "delivery_lead_times": [
              {
                "shipping_method": {
                  "name": "Standard Shipping",
                  "reference": null,
                  "price_amount_cents": 700,
                  "free_over_amount_cents": 9900,
                  "formatted_price_amount": "€7,00",
                  "formatted_free_over_amount": "€99,00"
                },
                "min": {
                  "hours": 72,
                  "days": 3
                },
                "max": {
                  "hours": 120,
                  "days": 5
                }
              },
              {
                "shipping_method": {
                  "name": "Express Delivery",
                  "reference": null,
                  "price_amount_cents": 1200,
                  "free_over_amount_cents": null,
                  "formatted_price_amount": "€12,00",
                  "formatted_free_over_amount": null
                },
                "min": {
                  "hours": 48,
                  "days": 2
                },
                "max": {
                  "hours": 72,
                  "days": 3
                }
              }
            ]
          },
          {
            "quantity": 6,
            "delivery_lead_times": [
              {
                "shipping_method": {
                  "name": "Standard Shipping",
                  "reference": null,
                  "price_amount_cents": 700,
                  "free_over_amount_cents": 9900,
                  "formatted_price_amount": "€7,00",
                  "formatted_free_over_amount": "€99,00"
                },
                "min": {
                  "hours": 96,
                  "days": 4
                },
                "max": {
                  "hours": 144,
                  "days": 6
                }
              },
              {
                "shipping_method": {
                  "name": "Express Delivery",
                  "reference": null,
                  "price_amount_cents": 1200,
                  "free_over_amount_cents": null,
                  "formatted_price_amount": "€12,00",
                  "formatted_free_over_amount": null
                },
                "min": {
                  "hours": 72,
                  "days": 3
                },
                "max": {
                  "hours": 96,
                  "days": 4
                }
              }
            ]
          }
        ]
      },
      "id": "1234",
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": "ANYREFEFERNCE",
      "metadata": {
        "foo": "bar"
      }
    },
    "relationships": {
      "shipping_category": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/skus/1234/relationships/shipping_category",
          "related": "https://your-brand.commercelayer.io/api/skus/1234/shipping_category"
        }
      },
      "prices": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/skus/1234/relationships/prices",
          "related": "https://your-brand.commercelayer.io/api/skus/1234/prices"
        }
      },
      "stock_items": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/skus/1234/relationships/stock_items",
          "related": "https://your-brand.commercelayer.io/api/skus/1234/stock_items"
        }
      },
      "delivery_lead_times": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/skus/1234/relationships/delivery_lead_times",
          "related": "https://your-brand.commercelayer.io/api/skus/1234/delivery_lead_times"
        }
      },
      "sku_options": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/skus/1234/relationships/sku_options",
          "related": "https://your-brand.commercelayer.io/api/skus/1234/sku_options"
        }
      }
    },
    "meta": {
      "mode": "test"
    }
  }
}

Update a sku

To update an existing sku, send a PATCH request to the /api/skus/{{id}} endpoint, where {{id}} is the id of the resource that you want to update. The following table contains the list of all the possible arguments that you can pass with the request body, along with their type, description and examples values. Please note that all arguments are optional.
Arguments:
code
optional
The sku code, that uniquely identifies the sku within the organization.
Example:
TSHIRTMM000000FFFFFFXLXX
name
optional
The internal name of the sku.
Example:
Black Men T-shirt with White Logo (XL)
description
optional
An internal description of the sku.
Example:
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
image_url
optional
The URL of an image that represents the sku.
Example:
https://img.yourbrand.com/skus/1234.png
tag_names
optional
A comma separated list of tags.
Example:
Men, Black, XL
pieces_per_pack
optional
The number of pieces that compose the sku. This is useful to describe sets and bundles.
Example:
6
weight
optional
The weight of the sku. If present, it will be used to calculate the shipping rates.
Example:
300
unit_of_weight
optional
Can be one of 'gr' or 'oz'
Example:
gr
reference
optional
A string that you can use to add your own identifier to the resource. This can be useful for intergrating the resource to an external system, like an ERP, a marketing tool or a CRM.
Example:
ANYREFEFERNCE
metadata
optional
Set of key-value pairs that you can attach to the resource. This can be useful for storing additional information about the resource in a structured format.
Example:
#
The sku's shipping category
Example request:
PATCH /api/skus/1234 HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": {
    "type": "skus",
    "id": 1234,
    "attributes": {
      "code": "TSHIRTMM000000FFFFFFXLXX"
    },
    "relationships": {
    }
  }
}
Example response: 200 OK
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": {
    "id": "1234",
    "type": "skus",
    "links": {
      "self": "https://your-brand.commercelayer.io/api/skus/1234"
    },
    "attributes": {
      "code": "TSHIRTMM000000FFFFFFXLXX",
      "name": "Black Men T-shirt with White Logo (XL)",
      "description": "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
      "image_url": "https://img.yourbrand.com/skus/1234.png",
      "tag_names": "Men, Black, XL",
      "pieces_per_pack": "6",
      "weight": "300",
      "unit_of_weight": "gr",
      "inventory": {
        "available": true,
        "quantity": 10,
        "levels": [
          {
            "quantity": 4,
            "delivery_lead_times": [
              {
                "shipping_method": {
                  "name": "Standard Shipping",
                  "reference": null,
                  "price_amount_cents": 700,
                  "free_over_amount_cents": 9900,
                  "formatted_price_amount": "€7,00",
                  "formatted_free_over_amount": "€99,00"
                },
                "min": {
                  "hours": 72,
                  "days": 3
                },
                "max": {
                  "hours": 120,
                  "days": 5
                }
              },
              {
                "shipping_method": {
                  "name": "Express Delivery",
                  "reference": null,
                  "price_amount_cents": 1200,
                  "free_over_amount_cents": null,
                  "formatted_price_amount": "€12,00",
                  "formatted_free_over_amount": null
                },
                "min": {
                  "hours": 48,
                  "days": 2
                },
                "max": {
                  "hours": 72,
                  "days": 3
                }
              }
            ]
          },
          {
            "quantity": 6,
            "delivery_lead_times": [
              {
                "shipping_method": {
                  "name": "Standard Shipping",
                  "reference": null,
                  "price_amount_cents": 700,
                  "free_over_amount_cents": 9900,
                  "formatted_price_amount": "€7,00",
                  "formatted_free_over_amount": "€99,00"
                },
                "min": {
                  "hours": 96,
                  "days": 4
                },
                "max": {
                  "hours": 144,
                  "days": 6
                }
              },
              {
                "shipping_method": {
                  "name": "Express Delivery",
                  "reference": null,
                  "price_amount_cents": 1200,
                  "free_over_amount_cents": null,
                  "formatted_price_amount": "€12,00",
                  "formatted_free_over_amount": null
                },
                "min": {
                  "hours": 72,
                  "days": 3
                },
                "max": {
                  "hours": 96,
                  "days": 4
                }
              }
            ]
          }
        ]
      },
      "id": "1234",
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": "ANYREFEFERNCE",
      "metadata": {
        "foo": "bar"
      }
    },
    "relationships": {
      "shipping_category": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/skus/1234/relationships/shipping_category",
          "related": "https://your-brand.commercelayer.io/api/skus/1234/shipping_category"
        }
      },
      "prices": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/skus/1234/relationships/prices",
          "related": "https://your-brand.commercelayer.io/api/skus/1234/prices"
        }
      },
      "stock_items": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/skus/1234/relationships/stock_items",
          "related": "https://your-brand.commercelayer.io/api/skus/1234/stock_items"
        }
      },
      "delivery_lead_times": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/skus/1234/relationships/delivery_lead_times",
          "related": "https://your-brand.commercelayer.io/api/skus/1234/delivery_lead_times"
        }
      },
      "sku_options": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/skus/1234/relationships/sku_options",
          "related": "https://your-brand.commercelayer.io/api/skus/1234/sku_options"
        }
      }
    },
    "meta": {
      "mode": "test"
    }
  }
}

Delete a sku

To delete a sku, send a DELETE request to the /api/skus/{{id}} endpoint, where {{id}} is the id of the resource that you want to delete.
Example request:
DELETE /api/skus/1234 HTTP/1.1
Accept: application/vnd.api+json
Example response: 204 No Content
HTTP/1.1 204 No Content

Get our machine-readable JSON schema that follows the OpenAPI Specification (formerly Swagger).

Get our Postman collection in one click and start making real calls to Commerce Layer API in minutes.

Get in touch with our support team if you have any questions or want to learn more about Commerce Layer.