Create & update product data

Creating Products

1. Use the GET /traits endpoint to see a list of product traits. Choose and store IDs or names for traits supported by your products. Insert the encoded trait_id (or 'trait_name') and value when creating your product. If the trait has an ID in your system you can send it to JOOR via the external_id optional element instead.

• Products can have none or many traits. For example, let's say that our sample product has one trait: materials.

2. Use the GET /categories endpoint to see a list of category ids. Choose and store the category id that has the most accurate categorization of the product.

• For example, let use the New York Yankees baseball hat for children. There will be a few category options to choose from depending on age and gender. In this case let's say the hat was meant for babies and it's gender-neutral, which means that it might fit into the below category:

3. (Optional) JOOR supports product tags that categorize and sort your products for later reporting; you can learn more about tags and how to manage them on the JOOR help centre or from your CSM.

• When using the CREATE /products endpoint, you also pass tags in the create request. Tags have four components:
  • name - tag name, ex. fit
  • value - tag value, ex. wide
  • code - tag code by which the tag is identified in clients system ex. F2
  • parent_id - a tag must be assigned to a parent_id (please check with your Integrations Manager to retrieve the list of parent_ids in your account)

4. Use the CREATE /products endpoint to create products and add product level traits and categories.

• Here is a sample create product request for the New York Yankees baseball hat. As you can see we have included product:
  • name
  • description
  • order_min - minimum quantity of the product per order
  • external_id - an id by which the product is identified in the client's system
  • the trait and the category
  • optional custom tags

[
    {
        "name": "NY Hat",
        "description": "The New York Yankees baseball hat",
        "order_minimum": 0,
        "external_id": "test_id_0001",
        "product_trait_values": [
            {
                "trait_id": "UHJvZHVjdFRyYWl0Ok1BVA==",
                "value": "COTONE 96%-ELASTAM/SPANDEX 4%",
                "external_id": "012"
            }
        ],
        "category_ids": [
            "490"
        ],
        "tags": [
            {
                "name": "Fit",
                "value": "Wide",
                "code": "F2",
                "parent_id": "116554"
            }
        ]
    } 
]

4. CREATE /products response will provide a JOOR product id, which is extremely important. JOOR product ids are used in the UPDATE /products, CREATE /skus, and CREATE /collections requests. You can choose to store the product id or ask JOOR to provide it whenever you need it using the GET /products endpoint.

• Here is a sample response

{
    "data": [
        {
            "id": "3295521",
            "name": "NY Hat",
            "external_id": "test_id_0001",
            "product_identifier": "",
            "description": "The New York Yankees baseball hat",
            "order_minimum": 0,
            "images": [],
            "categories": [
                {
                    "id": "490",
                    "name": "Hats",
                    "parent_name": "Accessories",
                    "department": "BABY_ACCESSORIES"
                }
            ],
            "tags": [
                {
                    "id": "2082967",
                    "name": "Fit",
                    "value": "Wide",
                    "code": "F2",
                    "parent_id": "116554"
                }
            ],
            "product_trait_values": [
                {
                    "trait": {
                        "id": "UHJvZHVjdFRyYWl0Ok1BVA==",
                        "name": "Materials"
                    },
                    "value": "COTONE 96%-ELASTAM/SPANDEX 4%",
                    "external_id": ""
                }
            ]
        }
    ],
    "errors": []
}

Updating Products

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

Let's walk through retrieving a product ID from JOOR and updating the product:

1. Use the GET /products endpoint to see all available products and their IDs. This endpoint will provide a list of products in the same format as the create and update product requests. Once you get the response, capture the id of the product that you want to update.

2. Insert the id into the UPDATE /products endpoint to update your desired products.

• For example, let update the description for our hat to "The New York Yankees baseball hat 2021"

[
    {
        "id": "3295521",
        "name": "NY Hat",
        "description": "The New York Yankees baseball hat 2021",
        "order_minimum": 0,
        "external_id": "test_id_0001",
        "product_trait_values": [
            {
                "trait_id": "UHJvZHVjdFRyYWl0Ok1BVA==",
                "value": "COTONE 96%-ELASTAM/SPANDEX 4%",
                "external_id": "012"
            }
        ],
        "category_ids": [
            "452"
        ],
        "tags": [
            {
                "name": "Fit",
                "value": "Wide",
                "code": "F2",
                "parent_id": "116554"
            }
        ]
    } 
]

(Optional) If your products have external IDs then you may also update products using your own external_id using the UPDATE /products by external id endpoint.