GET /v3/auction/:id/items — subsequent page

GET

/v3/auction/{auctionId}/items

const url = 'https://api-ha-prod-p8.handbid.dev/v3/auction/example/items?limit=20&offset=20&manager=true&search=trophy';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://api-ha-prod-p8.handbid.dev/v3/auction/example/items?limit=20&offset=20&manager=true&search=trophy' \
  --header 'Authorization: Bearer <token>'

NEW (HAN-1685). offset > 0 returns ONLY {auctionStatus, endTime, items, totalCount} — no categories[] and no featuredItems[] (those don’t change between pages, so subsequent pages skip them to save bandwidth).

auctionStatus + endTime ride along on every page so the client can detect staleness without a separate auction-state poll.

Item-card shape (including the new controlMode field from HAN-1907) is identical to the first-page response.

Manager view (HAN-2131): pass manager=1 to include items for your own test and draft (setup-status) auctions, which the public catalog otherwise hides. Authorization is enforced server-side from the Bearer token — see the manager parameter — so non-managers (or anonymous callers) always get the public result; the flag alone grants nothing.

Donation Activity (HAN-3087). Each item card may carry activity (string | null): the item’s value in the organization’s flagged Activity custom-field group (HAN-453). The key is present only when the auction’s organization is entitled to Donation Items (allowDonationItems) and owns a flagged Activity group; it is absent otherwise (never null-for-absent). When present it is null for an item with no live Activity value. Additive scalar; identity-free (same body for anonymous and authenticated callers).

Authorizations

bearer

Parameters

Path Parameters

auctionId

required

string

Query Parameters

limit

integer

Example

offset

integer

Example

manager

boolean

Manager view. Set manager=1 to include items for your own test and draft (setup-status) auctions, which the public catalog hides. Authorization-gated server-side: honored only when the Bearer token belongs to a Handbid admin or a manager of the auction’s organization — any other caller (or none) receives the normal public result. The flag alone grants nothing.

Example

true

search

string

>= 1 characters <= 80 characters

NEW (HAN-2399). Optional keyword. Case/accent-insensitive substring over the item’s name, itemCode, and description; apostrophe-variant tolerant (straight ’ matches curly U+2019 and vice versa). % and _ are matched literally. Filters both the items list and totalCount, and composes with categoryId/limit/offset. 1-80 characters (else 400 validation_error). Omitting it preserves current behavior.

Example

trophy

Responses

200

Successful response

application/json

Bare body (no envelope). Only the HAN-3087 activity card scalar is described here; the rest of the item-card shape is documented in yii2-handbid docs/api/v3/auctions.md (“Shared item-card extras”).

object

auctionStatus

string

endTime

string

nullable

totalCount

integer

items

Array<object>

object

integer

name

string

itemType

string

nullable

activity

HAN-3087. The item’s Donation Activity (value of the org’s flagged Activity List field), trimmed. Present only when the org is allowDonationItems-entitled AND has a flagged Activity group; absent otherwise. null = no live Activity value.

string

nullable

key

additional properties

any

Example

{
  "auctionStatus": "open",
  "endTime": "2026-10-01 20:00:00",
  "totalCount": 2,
  "items": [
    {
      "id": 1963995,
      "name": "Golf Mulligans — 4 pack",
      "itemType": "activityDonation",
      "isDirectPurchaseItem": true,
      "sellOnPages": true,
      "controlMode": "purchase",
      "activity": "Golf Mulligans"
    },
    {
      "id": 1963996,
      "name": "Farmers Market table",
      "itemType": "activityDonation",
      "isDirectPurchaseItem": true,
      "sellOnPages": true,
      "controlMode": "purchase",
      "activity": null
    }
  ],
  "categories": []
}