Create & update SKU data

Create and update SKUs and assign their attributes

Creating SKUs

  1. A SKU is always associated with a parent product, which means that a product_id is required to create an SKU. Use the GET /products endpoint to see a list of products. Choose and store IDs for products you wish to create SKUs for. Insert the encoded product_id when creating your SKU.
  • Product id is also provided in the create a product response CREATE /products, which can be saved and used as a reference when updating products or creating SKUs, removing the need to make a GET /products request.
  1. Use the GET /traits endpoint to see available SKU traits.
  • At the moment the SKU level traits are Size and Color. Each SKU must have both traits. For example, let's say our SKU has sizes Small and Medium and colors Red and Blue. Below would be the traits for the Small Blue SKU.
trait_idtrait_namevalueexternal_id
U0tVVHJhaXQ6U3R5bGVDb2xvcg==ColorBlueBLU
U0tVVHJhaXQ6U2l6ZQ==SizeSmallS
  • All Color and Size combinations must be sent explicitly. For example, if you send only Color: Blue with Size: Small and Color: Red with Size: Medium, we will return an error asking for the full list to be sent:

    • Color: Blue | Size: Small
    • Color: Blue | Size: Medium
    • Color: Red | Size: Small
    • Color: Red | Size: Medium

      📘

      NOTE:

      The size value is case sensitive. Size names "Small" and "small" will be considered as different unique sizes to avoid duplicates.

  • The status flag for each trait can be set to ACTIVE (by default) or INACTIVE.

    • If INACTIVE, the color or size will no longer be shoppable for that product. It will also be removed from all orders (Cart/In Progress, Notes, Pending, Approved, Cancelled).
    • If ACTIVE, the color or size will become shoppable for that product. It will also be reinstated to all orders (Cart/In Progress, Notes, Pending, Approved, Cancelled).
  1. The last part of the request are SKU identifiers such as UPC, GTIN, EAN or MPN. SKU identifiers are one of the most sought after data points by retailers that shop on JOOR.
  • For example:
typevalue
upc03338300740
  1. Use the CREATE /skus endpoint to create an SKU, and map it to the product_id.
  • Here is a sample create SKU request for the New York Yankees baseball hat in size Small and color blue. As you can see we have included:
    • product_id - to identify parent product for this SKU
    • external_id - an id by which the SKU is identified in the client's system
    • sku_identifier - similar to external_id, a unique SKU id from a client's system, we will use this id later when adding images to the SKU
    • trait_values - color and size for our SKU
    • identifiers - UPC
[
  {
    "product_id": "3295521",
    "external_id": "nyhat0001",
    "sku_identifier": "nyhatblue001s1",
     "trait_values": [
      {
        "trait_id": "U0tVVHJhaXQ6U3R5bGVDb2xvcg==",
        "value": "Blue",
        "external_id": "blue001",
        "order_minimum": 0,
        "status": "ACTIVE"
      },
      {
        "trait_id": "U0tVVHJhaXQ6U2l6ZQ==",
        "value": "Small",
        "external_id": "S1",
        "order_minimum": 0,
        "status": "ACTIVE"
      }
    ],
    "identifiers": [
      {
        "type": "upc",
        "value": "03338300740"
      }
    ]
   
  }
]
  1. The CREATE /skus response will provide a JOOR SKU id. JOOR SKU ids are used in the UPDATE /skus, CREATE /prices, and CREATE /collections requests. You can choose to store the SKU id or ask JOOR to provide it whenever you need it using the GET /skus endpoint.
{
    "data": [
        {
            "id": "MHw1NTE3MDk1fDE4MjMwODYy",
            "product_id": "3295521",
            "external_id": "nyhat0001",
            "sku_identifier": "nyhatblue001s1",
            "trait_values": [
                {
                    "trait": {
                        "id": "U0tVVHJhaXQ6U3R5bGVDb2xvcg==",
                        "name": "Color"
                    },
                    "value": "Blue",
                    "external_id": "blue001",
                    "order_minimum": 0,
                    "order_nbr": 1,
                    "status": "ACTIVE",
                    "hexColor": null,
                    "swatch": null,
                    "images": null
                },
                {
                    "trait": {
                        "id": "U0tVVHJhaXQ6U2l6ZQ==",
                        "name": "Size"
                    },
                    "value": "Small",
                    "external_id": "S1",
                    "order_minimum": null,
                    "order_nbr": 1,
                    "status": "ACTIVE",
                    "hexColor": null,
                    "swatch": null,
                    "images": null
                }
            ],
            "identifiers": [
                {
                    "type": "upc",
                    "value": "03338300740"
                }
            ]
        }
    ],
    "errors": []
}

Updating SKUs

The UPDATE /skus request is essentially the same as a create SKU request with one exception, it requires a JOOR SKU id so the system knows which product to update. If you saved the JOOR SKU id when the SKU was created then you can use it in the update SKU request; however, if you don't have it then you will have to use the GET /skus endpoint.

Let's walk through retrieving an SKU id from JOOR and updating the SKU:

  1. Use the GET /skus endpoint to see available SKU ids for products.
    a. You can use the product_id to filter only SKUs that belong to the product that you wish to update. To retreive product_id you can use the GET /products endpoint.
  • For example: https://apisandbox.jooraccess.com/v4/skus?product_ids=3295521&account=[your_account_id]

  • The GET /skus response looks exactly the same as the create SKU response.

  1. Insert the SKU id into the UPDATE /skus endpoint to update your desired SKUs.
  • For example, let's update the UPC for the New York Yankees hat in size small and color Blue to a new value:
[
  {
    "id": "MHw1NTE3MDk1fDE4MjMwODYy",
    "external_id": "nyhat0001",
    "sku_identifier": "nyhatblue001s1",
     "trait_values": [
      {
        "trait_id": "U0tVVHJhaXQ6U3R5bGVDb2xvcg==",
        "value": "Blue",
        "external_id": "blue001",
        "order_minimum": 0,
        "status": "ACTIVE"
      },
      {
        "trait_id": "U0tVVHJhaXQ6U2l6ZQ==",
        "value": "Small",
        "external_id": "S1",
        "order_minimum": 0,
        "status": "ACTIVE"
      }
    ],
    "identifiers": [
      {
        "type": "upc",
        "value": "03338312120"
      }
    ]
   
  }
]

(Optional)You may also update SKUs using your own external_id using the UPDATE /skus by external id endpoint.