Create & update collection data

A JOOR collection (linesheet) is a grouping of products or SKU for marketing, sales or organization. A collection could be visible to all customers or a subset of customers. At the moment collections are required to place an order, which means that a single account on JOOR must have at least one collection to sell products. Most JOOR customers upload new collections every season and some have hundreds of collections that cater to different sales needs.

Creating Collections

A collection on JOOR has five distinct properties

name - a collection name
external_id - an id by which the collection is identified in the client's system
season_id - JOOR season_id
delivery - delivery dates: start_ship_date, complete_ship_date, cancel_date, minimum_shipping_window
items - product and SKUs that belong to the collection
Let's build a collection request with a single item in it.

Use GET /seasons to list all available seasons and their IDs on your JOOR account. Find the season that you are working with and save the season ID to use it in the CREATE /collections request.

You might already have the JOOR season id stored on your end if you have saved it when a season was created. If you do then there is no need to make the GET /seasons.

A delivery section in CREATE /collections request informs JOOR when products or SKUs from a given collection will start and finish shipping, how much time a buyer has to cancel an item from an order and a minimum number of days for shipping. Delivery properties

start_ship_date - when items from the collection will start shipping
complete_ship_date - when items from the collection with finished shipping
cancel_date - the last day to cancel an item from an order
minimum_shipping_window - at the minimum, this is how long the shipping takes

An items section in the CREATE /collections request contains all products or SKUs that belong to a given collection. When a product is included in the collection without specifying SKUs then all SKUs that belong to that product will be added to the collection.

Items in the collection can be ordered, if you wish to do that you can use the order_number property
(Optional) An SKU can have its own delivery window, which might be different from the collection delivery window. If an SKU delivery window is provided it will overwrite collection delivery data for this particular SKU.

Use CREATE /collections endpoint to create a collection with an SKU level delivery.

[
    {
        "name": "2022 Spring Collection",
        "external_id": "2022SC",
        "season_id": "33615",
        "delivery": {
            "start_ship_date": "2022-02-02",
            "complete_ship_date": "2022-04-30",
            "cancel_date": "2022-04-01",
            "minimum_shipping_window": 10
        },
        "items": [
            {
                "product_id": "3295521",
                "order_number": 1,
                "skus": [
                   {
                       "id" : "MHw1NTE3MDk1fDE4MjMwODYy",
                       "delivery": {
                            "start_ship_date": "2022-06-01",
                            "complete_ship_date": "2022-08-14"
                        }
                   }
                ]
            }
        ]
    }
]

CREATE /collections response will provide a JOOR collection ID, which is used in the UPDATE /collections request and in the CREATE /orders request. You can also retrieve JOOR collection IDs using the GET /collections request.

{
  "data": [
    {
      "id": "1",
      "name": "2022 Spring Collection",
      "external_id": "2022SC",
      "delivery": {
        "start_ship_date": "2022-02-02",
        "complete_ship_date": "2022-04-30",
        "cancel_date": "2022-04-01",
        "minimum_shipping_window": 10
      },
      "season": {
        "id": "33615",
        "name": "Summmer",
        "year": 2022,
        "external_id": "2342411"
      },
      "visibility": "OWNER",
      "archived": false,
      "is_custom": true,
      "made_to_order": true,
      "items": [
        {
          "product_id": "3295521",
          "order_number": 1,
          "skus": [
            {
              "id": "MHw1NTE3MDk1fDE4MjMwODYy",
              "delivery": {
                "start_ship_date": "2022-06-01",
                "complete_ship_date": "2022-08-14"
              }
            }
          ]
        }
      ]
    }
  ],
  "errors": [
    {
      "status": "VALIDATION_ERROR",
      "message": "Shipping date must be before completed date",
      "details": {
        "name": "Collection One",
        "externalId": "31431",
        "seasonId": "4",
        "ignores_inventory": false
      }
    }
  ]
}

Updating Collections

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

Let's walk through retrieving a collection id from JOOR and updating the collection:

Use the GET /collections endpoint to see available collection ids.
Insert the collection id into the UPDATE /collections endpoint to update your desired SKUs.

For example, let's update the delivery window for the 2022 Spring Collection to a new value:

[
  {
    "id": "1",
    "name": "2022 Spring Collection",
    "season_id": "33615",
    "made_to_order": false,
    "delivery": {
      "start_ship_date": "2022-03-01",
      "complete_ship_date": "2022-05-31",
      "cancel_date": "2022-05-01",
      "minimum_shipping_window": 10
    },
    "items": [
      {
        "product_id": "3295521",
        "order_number": 1,
        "skus": [
          {
            "id" : "MHw1NTE3MDk1fDE4MjMwODYy",
                       "delivery": {
                            "start_ship_date": "2022-06-01",
                            "complete_ship_date": "2022-08-14"
            }
          }
        ]
      }
    ]
  }
]

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