Update Item

Update an existing auction item. Only include the fields you want to change.

PATCH /datatable-items/{id}
Writable Fields

All fields that can be set during item creation (POST) can also be updated via PATCH. Only include the fields you want to modify.

Item History Fields

When updating Item History fields (e.g., field_sold_for_amount, field_winner_bidder), the system creates or updates Item History records rather than modifying the item directly. PATCH with only Item History fields skips parent class validation.

Example Request - Update Basic Information
PATCH /api/v1.0/datatable-items/5678
{
  "subtitle": "Updated: Rare 1920s European Stamp Collection",
  "published": 1
}
Example Request - Update Description
{
  "description": "
Fully authenticated collection with certificates.
",
  "literature": "Referenced in Stanley Gibbons Catalogue 2025",
  "provenance": "Ex collection: Royal Philatelic Society"
}
Example Request - Update Pricing
{
  "opening_price": 75000,
  "estimate_low": 100000,
  "estimate_high": 150000,
  "reserve_price": 90000
}
Example Request - Update Categories
{
  "categories": ["Stamps", "European", "Vintage"],
  "search_tags": ["Rare", "Collectible"],
  "topics": ["Postal History"]
}
Example Request - Update Images
{
  "images": [12345, 12346, 12347, 12348]
}

Note: Images field is optimized - won't resave if file IDs are unchanged

Example Request - Update Dimensions
{
  "dimensions": [
    {
      "number_on_box": "BOX-002",
      "height": 15.0,
      "width": 12.0,
      "depth": 4.0,
      "weight": 3.5,
      "type": "boxed"
    }
  ]
}
Example Request - Update Catalogs
{
  "catalogs": [
    {
      "catalog_number": "SG-456",
      "catalog_name": "Stanley Gibbons",
      "ordering_number": 1,
      "catalog_value": 18000
    },
    {
      "catalog_number": "M-789",
      "catalog_name": "Michel Catalogue",
      "ordering_number": 2,
      "catalog_value": 17500
    }
  ]
}
Example Request - Update Item History (Sold Information)
{
  "field_sold_for_amount": 125000,
  "field_winner_bidder": 456,
  "field_bidder_alias": "Paddle 23",
  "field_sold_status": "sold",
  "field_sold_agent": 10
}

Note: This creates a new Item History record

Example Request - Update Consignor Payment
{
  "field_consignor_price": 100000,
  "field_dont_pay_consignor": 0
}
Example Request - Withdraw Item
{
  "field_withdrawn": 1,
  "auctioneer_notes": "Withdrawn at consignor's request"
}
Example Request - Update Lot Number and Position
{
  "lot_number": 150,
  "lot_letter": "A",
  "position_of_consignment": 5
}
Example Request - Update Media Links
{
  "video_url": "https://youtube.com/watch?v=example",
  "pdf_url": "https://example.com/catalog.pdf",
  "certificate_link": "https://example.com/cert/67890"
}
Response
{
  "data": [{
    "id": "5678",
    "display_id": "150A",
    "subtitle": "Updated: Rare 1920s European Stamp Collection",
    "published": true,
    "lot": "150A",
    "opening_price": 75000,
    "estimate_low": 100000,
    "estimate_high": 150000,
    "current_price": 125000,
    "status": {
      "value": "sold",
      "label": "Sold"
    },
    "updated": "2025-12-31T15:30:00Z"
  }]
}
Updatable Field Categories

subtitle, published, type, collectible_type, grade, consignment, uuid, year, country

description, footer, caption, literature, essay, provenance, ex

categories, destinations, search_tags, catalogue_parts, postal_thematics, symbols, sub_symbol, grouping_category, topics, tags, mediums

opening_price, minimum_price, buy_now_price, buy_now_setting, estimate_low, estimate_high, estimate_internal, retail_price, reserve_price, reserve_type

images, video_url, pdf_url, certificate_link, reference_link

catalogs (multifield), dimensions (multifield), product_tax_code, harmonized_code, signed_locations, art_work_type

lot_number, lot_letter, position_of_consignment, start_lot_numbering_at

field_consignor_price, field_dont_pay_consignor, field_sold_agent, field_sold_for_amount, field_sold_to_bidder_id, field_bidder_alias, field_sold_status, field_under_extension_status, field_winner_bidder, field_withdrawn

shipping_id, post_sale, consignor_reference_number, responsible_user, public_message, auctioneer_notes, additional_charges, dont_pay_consignor_note, hide_sold_information, printing_options
Read-Only Fields (Cannot be Updated)

The following fields are read-only and will be ignored if included in PATCH requests:

  • id, display_id, lot (formatted)
  • current_price, consignor_price (from Item History)
  • withdrawn, dont_pay_consignor, winner_bidder, bidder_number, bidder_alias (from IH - use field_* versions to update)
  • user_agent, sold_status (from IH - use field_* versions to update)
  • current_order, current_consignment_statement (from IH)
  • sale (reference from context)
  • previous_lot, next_lot (navigation)
  • sync_status, itemWebsiteLink (computed)
  • created, updated timestamps
Important Notes
  • PATCH requests are partial updates - only send fields you want to change
  • All monetary values are in cents
  • Dates are in milliseconds (JavaScript timestamps)
  • Taxonomy terms can be sent as IDs (integers) or labels (strings)
  • Multifield arrays completely replace existing values - not merged
  • images field is optimized - won't resave if file IDs are unchanged
  • Item History fields create separate item_history nodes - use field_* prefix for these
  • Latest Item History is promoted and values are fetched from it on GET
  • PATCH with only Item History fields skips parent class validation
  • position_of_consignment is cast to unsigned integer during query
  • See Create Item for detailed field descriptions and structures
Back to Items View Create Documentation Back to API Home