Create or Update Items

This endpoint allows vendors to create new items or update existing ones in bulk. Items are matched based on the vendor_reference_id.

Overview

The Create or Update Items endpoint provides a way to manage your product catalog by adding new items or modifying existing ones. This is typically used for initial catalog setup and periodic menu updates.

Endpoint Details

Method: POST
URL: /api/developer/v1/items
Purpose: Create new items or update existing ones in your catalog

Authentication Required

All API calls require a valid authentication token. Invalid or expired tokens will result in a 401 Unauthorized response.

Request Specification

Request Parameters

The request body should be an array of item objects.

Field	Type	Required	Description
name	object	Yes	Contains the item name in different languages
name.ar	string	Yes	Item name in Arabic
name.en	string	Yes	Item name in English
description	object	Yes	Contains the item description in different languages
description.ar	string	Yes	Description in Arabic
description.en	string	Yes	Description in English
image_url	string	No	Publicly accessible URL of the item's image
price	number	Yes	The selling price of the item
discounted_price	number	No	The discounted selling price of the item (if applicable)
discount_start_at	string (ISO 8601)	No	The start date and time for the discount (e.g., "2025-01-01T00:00:00Z")
discount_end_at	string (ISO 8601)	No	The end date and time for the discount (e.g., "2025-01-10T23:59:59Z")
stock	integer	Yes	The initial stock quantity
is_active	boolean	Yes	Whether the item is generally active in the system
is_available	boolean	Yes	Whether the item is initially available for sale
is_virtual	boolean	No	Whether the item is virtual (non-physical / digital)
max_purchasable_quantity	integer	No	Maximum quantity a customer can purchase per order
vendor_reference_id	string / integer	Yes	Your unique identifier for this item
sku	string	No	Stock Keeping Unit
barcode	string	No	Item barcode (e.g., EAN, UPC)
category_ids	array[integer]	Yes	An array of category IDs this item belongs to
brand_id	integer	No	The ID of the brand this item belongs to
variants	array[object]	No	Optional list of variant objects for this item (see example)

Request Limits

You can upload up to 100 items in the root array. Each item may include up to 10 variants.

• Maximum items per request: 100
• Maximum variants per item: 10
• Maximum total variants per request (if every item has 10 variants): 1000

Consider sending updates in smaller batches to avoid request size or timeout issues.

Example Request

[
  {
    "name": {
      "ar": "Item 1 ar",
      "en": "Item 1 en"
    },
    "description": {
      "ar": "A description for Item 1 ar",
      "en": "A description for Item 1 en"
    },
    "price": 100,
    "discounted_price": 70,
    "discount_start_at": "2025-01-01T00:00:00Z",
    "discount_end_at": "2025-01-10T23:59:59Z",
    "stock": 50,
    "is_active": true,
    "is_available": true,
    "is_virtual": false,
    "max_purchasable_quantity": 10,
    "vendor_reference_id": "101",
    "sku": "ITEM001",
    "barcode": "1234567890123",
    "category_ids": [817],
    "image_url": "https://example.com/images/item1.jpg",
    "variants": [
      {
        "vendor_reference_id": "101-V1",
        "name": { "ar": "Variant 1 ar", "en": "Variant 1 en" },
        "description": { "ar": "Variant 1 description ar", "en": "Variant 1 description en" },
        "price": 110,
        "discounted_price": 70,
        "discount_start_at": "2025-01-01T00:00:00Z",
        "discount_end_at": "2025-01-10T23:59:59Z",
        "stock": 20,
        "is_active": true,
        "is_available": true,
        "sku": "ITEM001-V1",
        "barcode": "1234567890123-V1",
        "image_url": "https://example.com/images/item1-variant1.jpg",
        "attribute_value_ids":[2]
      },
      {
        "vendor_reference_id": "101-V2",
        "name": { "ar": "Variant 2 ar", "en": "Variant 2 en" },
        "description": { "ar": "Variant 2 description ar", "en": "Variant 2 description en" },
        "price": 120,
        "discounted_price": 80,
        "discount_start_at": "2025-01-01T00:00:00Z",
        "discount_end_at": "2025-01-10T23:59:59Z",
        "stock": 30,
        "is_active": true,
        "is_available": true,
        "sku": "ITEM001-V2",
        "barcode": "1234567890123-V2",
        "image_url": "https://example.com/images/item1-variant2.jpg",
         "attribute_value_ids":[2]
      }
    ]
  }
]

Response Specification

Success Response

201 Created

A successful request indicates that the items were created or updated. The response body is typically empty for this bulk operation.

Error Responses

401 Unauthorized - Authentication issues

{
  "status": "error",
  "message": "Unauthenticated."
}

422 Unprocessable Content - Validation errors

{
  "status": "error",
  "message": "Validation failed",
  "errors": {
    "0.price": ["The price field must be a number."],
    "0.category_ids": ["The category_ids field is required."]
  }
}

Implementation Tips

Best Practices

• Use the vendor_reference_id consistently to ensure updates apply to the correct items
• Send updates in batches to improve efficiency, but stay within request size limits
• Validate data on your end before sending to reduce API errors
• Use the Update Item Availability endpoint for frequent stock/availability changes

Use Cases

1. Initial Catalog Setup: Create your entire product catalog when first integrating with Presto
2. Menu Updates: Modify prices, descriptions or other details when your menu changes
3. New Product Introduction: Add new items when expanding your offerings
4. Product Retirement: Update items to make them inactive when discontinued