YOyoco
Items

Update an item

Changed on

Replace an item. The request carries every field, and null clears a value unless the field says otherwise.

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

put/v1/items/{item_id}

Request

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

Path parameters

item_idstring required

The unique identifier of the item.

Request body

namestring required

The name of the item.

descriptionstring nullable required

A description of the item.

default_barcodestring nullable required

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

default_durationinteger nullable required

The duration of the service, in minutes.

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

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 required

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 required

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

tax_idsstring[] nullable required

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

      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
    • breaking

      added the new required request property ///