question

Hi @AndyMeer! I'm glad you decided to ask this question here, because I'm sure the answer is able to help someone else as well!

To answer your question, to create a new category, you'll need to do following (note: "name" is required):

POST {
                {url}}/v3/merchants/{
                {mId}}/categories?access_token={
                {api_token}}	
JSON: {"name": "Fizzy Drinks"}

You can only create one category at a time so you'll need multiple calls to create multiple categories:

POST {
                {url}}/v3/merchants/{
                {mId}}/categories?access_token={
                {api_token}}
JSON: {"name": "Non-Caffeinated"}

Once you've made these calls, they will have IDs assigned to them. You can use these IDs with item IDs to add items to your desired categories.

Categories:
- Fizzy Drinks: Y6T63E6198AH0
- Non-Caffeinated: 9VFZQJ2F3VBP8

Items:
- Lemonade: Q07ZF0VJHTC96
- Sprite: 7Q0QWFVPG20PJ
- Coke: PWZ3AHR9ZJ8G4
- Pepsi: 5RY970Y2ZSC8M

Using the above information, we can create the category-item associations like so:

POST {
                {url}}/v3/merchants/{
                {mId}}/category_items?access_token={
                {api_token}}
JSON: {
  "elements": [
    { "category": {"id": "Y6T63E6198AH0"}, "item": {"id": "5RY970Y2ZSC8M"} }, # Add Pepsi to Fizzy Drinks
    { "category": {"id": "Y6T63E6198AH0"}, "item": {"id": "7Q0QWFVPG20PJ"} }, # Add Sprite to Fizzy Drinks
    { "category": {"id": "Y6T63E6198AH0"}, "item": {"id": "PWZ3AHR9ZJ8G4"} }, # Add Coke to Fizzy Drinks
    { "category": {"id": "9VFZQJ2F3VBP8"}, "item": {"id": "7Q0QWFVPG20PJ"} }, # Add Sprite to Non-Caffeinated
    { "category": {"id": "9VFZQJ2F3VBP8"}, "item": {"id": "Q07ZF0VJHTC96"} }  # Add Lemonade to Non-Caffeinated
  ]
}

You will simply get back a 200 OK on success. Notice that the items now have the appropriate categories:

GET {
                {url}}/v3/merchants/{
                {mId}}/items/7Q0QWFVPG20PJ?access_token={
                {api_token}}&expand=categories
Result:
{
  "id": "7Q0QWFVPG20PJ",
    "name": "Sprite",
    ...
    "categories": {
      "elements": [
        {
          "id": "Y6T63E6198AH0",
          "name": "Fizzy Drinks"
        },
        {
          "id": "9VFZQJ2F3VBP8",
          "name": "Non-Caffeinated"
        }
     ]
   }
}