List Items

This endpoint allows vendors to retrieve their catalog items with pagination support.

Overview

The List Items endpoint provides a way to fetch all items in your catalog. Items are returned with their associated categories and attribute values, paginated with 100 items per page. Items are ordered by sequence (ascending), then by id (descending).

Endpoint Details

Method: GET URL: /api/developer/v1/items Purpose: Retrieve a paginated list of your catalog items

Authentication Required

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

Request Specification

Query Parameters

Parameter	Type	Required	Description
page	integer	No	Page number for pagination (default: 1)

Example Request

curl -X GET "https://api.presto.ly/api/developer/v1/items?page=1" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Response Specification

Success Response

200 OK

Returns a paginated list of items with their details.

Response Fields

Field	Type	Description
id	integer	Presto's internal ID for the item
vendor_reference_id	string	Your unique identifier for this item
name	object	Item name translations (ar, en)
description	object	Item description translations (ar, en)
price	number	The selling price of the item
discounted_price	number|null	The discounted price (if applicable)
discount_start_at	string|null	Start date/time for the discount (ISO 8601)
discount_end_at	string|null	End date/time for the discount (ISO 8601)
stock	integer	Current stock quantity
sku	string|null	Stock Keeping Unit
barcode	string|null	Item barcode
is_active	boolean	Whether the item is active in the system
is_available	boolean	Whether the item is available for sale
is_virtual	boolean	Whether the item is virtual (non-physical)
image_url	string|null	URL of the item's image
brand_id	integer|null	The ID of the brand this item belongs to
max_purchasable_quantity	integer|null	Maximum quantity per order
parent_id	integer|null	Parent item ID (for variants)
sequence	integer|null	Display order of the item (lower values appear first)
category_ids	array[integer]	IDs of categories this item belongs to
attribute_value_ids	array[integer]	IDs of attribute values for this item
created_at	string	Creation timestamp (ISO 8601)
updated_at	string	Last update timestamp (ISO 8601)

Example Response

{
  "data": [
    {
      "id": 12345,
      "vendor_reference_id": "101",
      "name": {
        "ar": "اسم المنتج",
        "en": "Product Name"
      },
      "description": {
        "ar": "وصف المنتج",
        "en": "Product Description"
      },
      "price": 100,
      "discounted_price": 70,
      "discount_start_at": "2025-01-01T00:00:00Z",
      "discount_end_at": "2025-01-10T23:59:59Z",
      "stock": 50,
      "sku": "ITEM001",
      "barcode": "1234567890123",
      "is_active": true,
      "is_available": true,
      "is_virtual": false,
      "image_url": "https://example.com/images/item1.jpg",
      "brand_id": 5,
      "max_purchasable_quantity": 10,
      "parent_id": null,
      "sequence": 1,
      "category_ids": [817, 820],
      "attribute_value_ids": [],
      "created_at": "2025-01-01T12:00:00Z",
      "updated_at": "2025-01-05T14:30:00Z"
    }
  ],
  "links": {
    "first": "https://api.presto.ly/api/developer/v1/items?page=1",
    "last": "https://api.presto.ly/api/developer/v1/items?page=5",
    "prev": null,
    "next": "https://api.presto.ly/api/developer/v1/items?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 5,
    "per_page": 100,
    "to": 100,
    "total": 450
  }
}

Error Responses

401 Unauthorized - Authentication issues

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

Implementation Tips

Best Practices

• Use pagination to efficiently retrieve large catalogs
• Cache the results on your end to reduce API calls
• Use this endpoint to sync your local inventory with Presto's catalog
• Only parent items are returned (variants are not included in the listing)

Use Cases

1. Catalog Synchronization: Periodically fetch your items to ensure your local system matches Presto's catalog
2. Inventory Audit: Review all items and their current status
3. Validation: Verify that items were created or updated correctly after bulk operations