YOyoco
Items

Create an item

Changed on

Create an item

Required scopes: business/catalogue:read, business/catalogue:write

post/v1/items/

Request

  • Base URL
    https://api.yoco.com
  • Auth
    HTTP bearer

Request body

namestring required

The name of the item.

descriptionstring nullable

A description of the item.

default_barcodestring nullable

The barcode of the item. A variant without a barcode of its own reports this value as its barcode.

default_durationinteger nullable

The duration of the service, in minutes.

type'product' | 'service' required
stock_tracking'item' | 'none' | 'variant'

StockTracking is whether the Yoco Point of Sale (POS) app tracks stock for an item.

none doesn't track stock. item keeps one count shared by all of the item's variants. variant keeps a separate count for each variant.

category_idstring nullable

The unique identifier of the category the item belongs to.

brand_idstring nullable

The unique identifier of the brand the item belongs to. Only a product can belong to a brand, so a service may leave it out.

image_idstring nullable

The unique identifier of the item's image: the id of a media item uploaded with POST /v1/media/.

tax_idsstring[] nullable

The unique identifiers of the taxes to apply to the item. null or [] removes the item's own taxes, so the business's default tax applies. To charge no tax, send the id of a tax from GET /v1/taxes whose percentage is 0, such as No Tax if the business has one.

Example request

{
  "brand_id": "1757511249592-ab46acf9-7c86-4ee0-92b9-6b43e1429337",
  "category_id": "1757511249593-dd25e17c-5541-4276-a078-8c3dcca296de",
  "default_barcode": "6001234567890",
  "default_cost_price": {
    "amount": 1200,
    "currency": "ZAR"
  },
  "default_price": {
    "amount": 1500,
    "currency": "ZAR"
  },
  "description": "A rich espresso with silky steamed milk and microfoam, smooth and balanced.",
  "image_id": "1757511249595-8b2e4c1d-6a7f-4d93-b5e0-2c9f1a3d7e64",
  "location_availability": {
    "excluded_location_ids": [
      "1757511249596-4c2d8e1f-6a7b-4c9d-8e0f-1a2b3c4d5e6f"
    ],
    "included_location_ids": [],
    "is_available_at_all_locations": true
  },
  "modifier_groups": [
    {
      "id": "1729001234567-aa11bb22-3344-4cdd-99ee-1122334455ff",
      "ordinal": 0
    }
  ],
  "name": "Flat White",
  "options": [
    {
      "name": "Size",
      "values": [
        {
          "name": "Small"
        },
        {
          "name": "Large"
        }
      ]
    }
  ],
  "price_overrides": [
    {
      "location_ids": [
        "1757511249595-9b3f7b3e-3b3f-4b3f-9b3f-3b3f7b3e9b3f"
      ],
      "price": {
        "amount": 4200,
        "currency": "ZAR"
      }
    }
  ],
  "stock_tracking": "variant",
  "tax_ids": [
    "1757511249594-3f1c8b7a-2d54-4e19-9c02-7b6de4f1a852"
  ],
  "type": "product",
  "variants": [
    {
      "barcode": "12345678",
      "cost_price": {
        "amount": 1200,
        "currency": "ZAR"
      },
      "is_enabled": true,
      "location_availability": {
        "excluded_location_ids": [
          "1757511249596-4c2d8e1f-6a7b-4c9d-8e0f-1a2b3c4d5e6f"
        ],
        "included_location_ids": [],
        "is_available_at_all_locations": true
      },
      "price": {
        "amount": 1500,
        "currency": "ZAR"
      },
      "selected_options": [
        {
          "name": "Size",
          "value": "Small"
        }
      ],
      "sku": "FW-SML"
    },
    {
      "cost_price": {
        "amount": 1500,
        "currency": "ZAR"
      },
      "is_enabled": true,
      "price": {
        "amount": 4500,
        "currency": "ZAR"
      },
      "selected_options": [
        {
          "name": "Size",
          "value": "Large"
        }
      ],
      "sku": "FW-LRG"
    }
  ]
}

Response

Successful Response

OR

Example response

{
  "brand_id": "1757511249592-ab46acf9-7c86-4ee0-92b9-6b43e1429337",
  "category_id": "1757511249593-dd25e17c-5541-4276-a078-8c3dcca296de",
  "created_at": "2024-11-19T15:27:02+00:00",
  "default_barcode": "6009800000015",
  "default_cost_price": {
    "amount": 1200,
    "currency": "ZAR"
  },
  "default_price": {
    "amount": 3800,
    "currency": "ZAR"
  },
  "description": "A rich espresso with silky steamed milk and microfoam, smooth and balanced.",
  "has_multiple_variants": false,
  "id": "1584347797665-e75edf46-394c-446a-8d25-5a6e0f244cef",
  "images": [
    {
      "created_at": "2024-11-19T15:27:02+00:00",
      "id": "1757533814961-58f649da-81e3-4877-8769-f407cfba8aff",
      "mime_type": "image/jpeg",
      "type": "image",
      "updated_at": "2024-11-19T16:27:23+00:00",
      "url": "https://images.yoco.com/foo/bar.jpg"
    }
  ],
  "is_taxable": true,
  "modifier_groups": [],
  "name": "Flat White",
  "options": [],
  "stock_tracking": "item",
  "taxes": [
    {
      "id": "1757511249594-3f1c8b7a-2d54-4e19-9c02-7b6de4f1a852",
      "name": "VAT",
      "percentage": "15.00",
      "type": "inclusive"
    }
  ],
  "type": "product",
  "updated_at": "2024-11-19T16:27:23+00:00",
  "variants": []
}

Changes

  • f961bea3a9a4Revision changes
    • breaking

      the request property format changed from int32 to no format

    • breaking

      the / request property format changed from no format to int32

    • breaking

      the /// request property format changed from int32 to no format

    • breaking

      the //// request property format changed from no format to int32

    • info

      added the new optional request property ///

    • info

      added the new optional request property ///

    • info

      added the new optional request property ///

    • info

      the /// response's property pattern ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ was removed for the status

    • info

      the /// response's property pattern ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ was removed for the status

  • ed6f9d39b4ebRevision changes
    • info

      added the new optional request property ///