Auction Items

An auction item represents a single listing in an auction. Each item has a status of scheduled, active, or completed.

Price attributes such as startPrice, minimumBid, currentIncrement, and highBidAmount are returned as a price object containing value (minor units), major, display, and currency fields.

The bidIncrementStrategy describes the increment type — fixed_amount, percentage, or tier — along with a value object containing the increment details.

The automaticBidding and softClose objects expose a single enabled boolean indicating whether each feature is active for the item.

The reserveMet boolean indicates whether the current high bid meets the auction's reserve, without exposing the reserve price itself. The processed attribute indicates whether the listing has been finalized, including assigning a winner — listings are typically processed within a minute after the end time.

Per-viewer fields (whether the authenticated customer has bid, is the high bidder, or is watching the item) are opt-in. Request fields by name with the viewerFields query parameter (e.g. viewerFields=hasBid,isWatching).

List Auction Items

get

Returns a paginated list of auction items that are scheduled, active, or completed. Canceled and archived items are excluded.

Authorizations

AuthorizationstringRequired

You can retrieve your token by visiting Settings > API and clicking Generate API token.

Query parameters

filter[status]string · enumOptionalPossible values:

filter[viewerHasBid]string · enumOptional

Limit results to auction items the authenticated customer has bid on.

Possible values:

filter[eventId]stringOptional

viewerFieldsstring · nullableOptional

perPageinteger · min: 1 · max: 100Optional

Results per page (1–100).

fields[auction-items]stringOptional

Available values are startPrice, bidIncrementStrategy, automaticBidding, softClose, totalBids, highBidAmount, minimumBid, currentIncrement, startsAt, endsAt, position, status, enableReserve, reserveMet, processed, createdAt, updatedAt, canceledAt. You can include multiple values by separating them with a comma.

fields[variants]stringOptional

Available values are externalId, displayName, title, price, photoUrl. You can include multiple values by separating them with a comma.

fields[products]stringOptional

Available values are externalId, title, vendor, type, photoUrl, handle. You can include multiple values by separating them with a comma.

fields[bids]stringOptional

Available values are amount, placedAt. You can include multiple values by separating them with a comma.

fields[max-bids]stringOptional

Available values are amount, createdAt. You can include multiple values by separating them with a comma.

fields[auction-winners]stringOptional

Available values are amount, notifiedAt, paymentDueAt. You can include multiple values by separating them with a comma.

includestringOptional

Comma-separated list of related resources to include in the response. Available values: variant, product, highBid, highBid.customer, viewerMaxBid, viewerWin.

sortstringOptional

Sort by field. Prefix with - for descending order. Available values: startsAt, -startsAt, endsAt, -endsAt, totalBids, -totalBids.

Responses

200

Paginated set of AuctionItemResource

application/vnd.api+json

401

The provided user does not have access to this resource.

application/vnd.api+json

422

Validation error

application/vnd.api+json

get/auction-items

GET /storefront/v1/auction-items HTTP/1.1
Host: api.auctionplusapp.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": [
    {
      "id": "text",
      "type": "text",
      "attributes": {
        "startPrice": {
          "value": 1,
          "major": "text",
          "display": "text",
          "currency": "text"
        },
        "bidIncrementStrategy": {
          "strategy": "text",
          "value": {
            "amount": {
              "value": 1,
              "major": "text",
              "display": "text",
              "currency": "text"
            }
          }
        },
        "automaticBidding": {
          "enabled": true
        },
        "softClose": {
          "enabled": true
        },
        "totalBids": 1,
        "highBidAmount": {
          "value": 1,
          "major": "text",
          "display": "text",
          "currency": "text"
        },
        "minimumBid": {
          "value": 1,
          "major": "text",
          "display": "text",
          "currency": "text"
        },
        "currentIncrement": {
          "value": 1,
          "major": "text",
          "display": "text",
          "currency": "text"
        },
        "startsAt": "2026-01-01T00:00:00.000Z",
        "endsAt": "2026-01-01T00:00:00.000Z",
        "position": null,
        "status": "scheduled",
        "enableReserve": true,
        "reserveMet": true,
        "processed": true,
        "createdAt": null,
        "updatedAt": null,
        "canceledAt": null
      },
      "meta": {
        "viewer": {
          "hasBid": true,
          "isWatching": true,
          "isHighBidder": true
        }
      },
      "relationships": {
        "variant": {
          "data": {
            "type": "variants",
            "id": "text"
          }
        },
        "product": {
          "data": {
            "type": "products",
            "id": "text"
          }
        },
        "highBid": {
          "data": {
            "type": "bids",
            "id": "text"
          }
        },
        "viewerMaxBid": {
          "data": {
            "type": "max-bids",
            "id": "text"
          }
        },
        "viewerWin": {
          "data": {
            "type": "auction-winners",
            "id": "text"
          }
        }
      }
    }
  ],
  "meta": {
    "currentPage": 1,
    "from": null,
    "lastPage": 1,
    "perPage": 1,
    "to": null,
    "total": 1
  }
}

Search Auction Items

get

Returns a paginated list of auction items that match the search query.

Authorizations

AuthorizationstringRequired

You can retrieve your token by visiting Settings > API and clicking Generate API token.

Query parameters

filter[status]string · enumOptionalPossible values:

filter[viewerHasBid]string · enumOptional

Limit results to auction items the authenticated customer has bid on.

Possible values:

filter[eventId]stringOptional

viewerFieldsstring · nullableOptional

perPageinteger · min: 1 · max: 100Optional

Results per page (1–100).

querystring · min: 1 · max: 100Required

The text to match against auction item titles.

fields[auction-items]stringOptional

Available values are startPrice, bidIncrementStrategy, automaticBidding, softClose, totalBids, highBidAmount, minimumBid, currentIncrement, startsAt, endsAt, position, status, enableReserve, reserveMet, processed, createdAt, updatedAt, canceledAt. You can include multiple values by separating them with a comma.

fields[variants]stringOptional

Available values are externalId, displayName, title, price, photoUrl. You can include multiple values by separating them with a comma.

fields[products]stringOptional

Available values are externalId, title, vendor, type, photoUrl, handle. You can include multiple values by separating them with a comma.

fields[bids]stringOptional

Available values are amount, placedAt. You can include multiple values by separating them with a comma.

fields[max-bids]stringOptional

Available values are amount, createdAt. You can include multiple values by separating them with a comma.

fields[auction-winners]stringOptional

Available values are amount, notifiedAt, paymentDueAt. You can include multiple values by separating them with a comma.

includestringOptional

Comma-separated list of related resources to include in the response. Available values: variant, product, highBid, highBid.customer, viewerMaxBid, viewerWin.

sortstringOptional

Sort by field. Prefix with - for descending order. Available values: startsAt, -startsAt, endsAt, -endsAt, totalBids, -totalBids.

Responses

200

Paginated set of AuctionItemResource

application/vnd.api+json

401

Unauthenticated

application/vnd.api+json

422

Validation error

application/vnd.api+json

get/auction-items/search

GET /storefront/v1/auction-items/search?query=text HTTP/1.1
Host: api.auctionplusapp.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": [
    {
      "id": "text",
      "type": "text",
      "attributes": {
        "startPrice": {
          "value": 1,
          "major": "text",
          "display": "text",
          "currency": "text"
        },
        "bidIncrementStrategy": {
          "strategy": "text",
          "value": {
            "amount": {
              "value": 1,
              "major": "text",
              "display": "text",
              "currency": "text"
            }
          }
        },
        "automaticBidding": {
          "enabled": true
        },
        "softClose": {
          "enabled": true
        },
        "totalBids": 1,
        "highBidAmount": {
          "value": 1,
          "major": "text",
          "display": "text",
          "currency": "text"
        },
        "minimumBid": {
          "value": 1,
          "major": "text",
          "display": "text",
          "currency": "text"
        },
        "currentIncrement": {
          "value": 1,
          "major": "text",
          "display": "text",
          "currency": "text"
        },
        "startsAt": "2026-01-01T00:00:00.000Z",
        "endsAt": "2026-01-01T00:00:00.000Z",
        "position": null,
        "status": "scheduled",
        "enableReserve": true,
        "reserveMet": true,
        "processed": true,
        "createdAt": null,
        "updatedAt": null,
        "canceledAt": null
      },
      "meta": {
        "viewer": {
          "hasBid": true,
          "isWatching": true,
          "isHighBidder": true
        }
      },
      "relationships": {
        "variant": {
          "data": {
            "type": "variants",
            "id": "text"
          }
        },
        "product": {
          "data": {
            "type": "products",
            "id": "text"
          }
        },
        "highBid": {
          "data": {
            "type": "bids",
            "id": "text"
          }
        },
        "viewerMaxBid": {
          "data": {
            "type": "max-bids",
            "id": "text"
          }
        },
        "viewerWin": {
          "data": {
            "type": "auction-winners",
            "id": "text"
          }
        }
      }
    }
  ],
  "meta": {
    "currentPage": 1,
    "from": null,
    "lastPage": 1,
    "perPage": 1,
    "to": null,
    "total": 1
  }
}

Retrieve an Auction Item

get

Retrieves the details for a single auction item.

Authorizations

AuthorizationstringRequired

You can retrieve your token by visiting Settings > API and clicking Generate API token.

Path parameters

idstringRequired

The auction item UID.

Example: 1c6af60by54hzdmgxy5ab4ypw0

Query parameters

viewerFieldsstring · nullableOptional

fields[auction-items]stringOptional

Available values are startPrice, bidIncrementStrategy, automaticBidding, softClose, totalBids, highBidAmount, minimumBid, currentIncrement, startsAt, endsAt, position, status, enableReserve, reserveMet, processed, createdAt, updatedAt, canceledAt. You can include multiple values by separating them with a comma.

fields[variants]stringOptional

Available values are externalId, displayName, title, price, photoUrl. You can include multiple values by separating them with a comma.

fields[products]stringOptional

Available values are externalId, title, vendor, type, photoUrl, handle. You can include multiple values by separating them with a comma.

fields[bids]stringOptional

Available values are amount, placedAt. You can include multiple values by separating them with a comma.

fields[max-bids]stringOptional

Available values are amount, createdAt. You can include multiple values by separating them with a comma.

fields[auction-winners]stringOptional

Available values are amount, notifiedAt, paymentDueAt. You can include multiple values by separating them with a comma.

includestringOptional

Comma-separated list of related resources to include in the response. Available values: variant, product, highBid, highBid.customer, viewerMaxBid, viewerWin.

Responses

200

AuctionItemResource

application/vnd.api+json

401

Unauthenticated

application/vnd.api+json

422

Validation error

application/vnd.api+json

get/auction-items/{id}

GET /storefront/v1/auction-items/{id} HTTP/1.1
Host: api.auctionplusapp.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": {
    "id": "text",
    "type": "text",
    "attributes": {
      "startPrice": {
        "value": 1,
        "major": "text",
        "display": "text",
        "currency": "text"
      },
      "bidIncrementStrategy": {
        "strategy": "text",
        "value": {
          "amount": {
            "value": 1,
            "major": "text",
            "display": "text",
            "currency": "text"
          }
        }
      },
      "automaticBidding": {
        "enabled": true
      },
      "softClose": {
        "enabled": true
      },
      "totalBids": 1,
      "highBidAmount": {
        "value": 1,
        "major": "text",
        "display": "text",
        "currency": "text"
      },
      "minimumBid": {
        "value": 1,
        "major": "text",
        "display": "text",
        "currency": "text"
      },
      "currentIncrement": {
        "value": 1,
        "major": "text",
        "display": "text",
        "currency": "text"
      },
      "startsAt": "2026-01-01T00:00:00.000Z",
      "endsAt": "2026-01-01T00:00:00.000Z",
      "position": null,
      "status": "scheduled",
      "enableReserve": true,
      "reserveMet": true,
      "processed": true,
      "createdAt": null,
      "updatedAt": null,
      "canceledAt": null
    },
    "meta": {
      "viewer": {
        "hasBid": true,
        "isWatching": true,
        "isHighBidder": true
      }
    },
    "relationships": {
      "variant": {
        "data": {
          "type": "variants",
          "id": "text"
        }
      },
      "product": {
        "data": {
          "type": "products",
          "id": "text"
        }
      },
      "highBid": {
        "data": {
          "type": "bids",
          "id": "text"
        }
      },
      "viewerMaxBid": {
        "data": {
          "type": "max-bids",
          "id": "text"
        }
      },
      "viewerWin": {
        "data": {
          "type": "auction-winners",
          "id": "text"
        }
      }
    }
  }
}

Place a Bid

post

Places a bid on an active auction item on behalf of the authenticated storefront customer.

You must provide either maxAmount for a maximum bid (automatic bidding), amount for a straight bid, or both.

• Straight bid (amount): Places a single bid at the specified amount.

• Proxy bid (maxAmount): Sets the maximum amount the system will automatically bid up to on behalf of the customer. The system places the minimum winning bid and automatically increments as competing bids are received, up to the maximum.

• Both (amount + maxAmount): Places a straight bid at the specified amount and sets a proxy maximum for automatic bidding.

The response returns the updated auction item with a meta.status field indicating whether the customer is the high_bidder or was automatically outbid by proxy bidding.

Authorizations

AuthorizationstringRequired

You can retrieve your token by visiting Settings > API and clicking Generate API token.

Path parameters

idstringRequired

The auction item UID.

Example: 1c6af60by54hzdmgxy5ab4ypw0

Query parameters

fields[auction-items]stringOptional

Available values are startPrice, bidIncrementStrategy, automaticBidding, softClose, totalBids, highBidAmount, minimumBid, currentIncrement, startsAt, endsAt, position, status, enableReserve, reserveMet, processed, createdAt, updatedAt, canceledAt. You can include multiple values by separating them with a comma.

fields[bids]stringOptional

Available values are amount, placedAt. You can include multiple values by separating them with a comma.

fields[max-bids]stringOptional

Available values are amount, createdAt. You can include multiple values by separating them with a comma.

fields[auction-winners]stringOptional

Available values are amount, notifiedAt, paymentDueAt. You can include multiple values by separating them with a comma.

includestringOptional

Comma-separated list of related resources to include in the response. Available values: highBid, highBid.customer, viewerMaxBid, viewerWin.

Body

viewerFieldsstring · nullableOptional

amountnumber · nullableOptional

The bid amount in major currency units (e.g. 10.50).

maxAmountnumber · nullableOptional

The maximum (proxy) bid in major currency units (e.g. 10.50).

Responses

200

AuctionItemResource

application/vnd.api+json

401

The provided user does not have access to this resource.

application/vnd.api+json

403

The provided user does not have access to this resource.

application/vnd.api+json

422

The bid could not be placed. Inspect errors[0].code for the specific reason:

• access_denied — the customer is not permitted to bid (e.g. not approved for bidder registration).
• auction_ended — the auction has already ended.
• amount_below_start_price — the straight bid amount is below the auction's start price.
• amount_below_showing_bid — the straight bid amount is at or below the current high bid plus the required increment. meta.minimum_bid shows the minimum acceptable value.
• max_amount_below_start_price — the max bid maxAmount is below the auction's start price. meta.minimum_bid shows the start price.
• max_amount_below_showing_bid — the max bid maxAmount is at or below the current high bid plus the required increment. meta.minimum_bid shows the minimum acceptable value.
• max_amount_below_current_bid — the customer is already the high bidder and the new maxAmount is lower than their existing showing bid. meta.minimum_bid shows the existing bid amount.

application/vnd.api+json

post/auction-items/{id}/place-bid

POST /storefront/v1/auction-items/{id}/place-bid HTTP/1.1
Host: api.auctionplusapp.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 52

{
  "viewerFields": null,
  "amount": null,
  "maxAmount": null
}

{
  "data": {
    "id": "text",
    "type": "text",
    "attributes": {
      "startPrice": {
        "value": 1,
        "major": "text",
        "display": "text",
        "currency": "text"
      },
      "bidIncrementStrategy": {
        "strategy": "text",
        "value": {
          "amount": {
            "value": 1,
            "major": "text",
            "display": "text",
            "currency": "text"
          }
        }
      },
      "automaticBidding": {
        "enabled": true
      },
      "softClose": {
        "enabled": true
      },
      "totalBids": 1,
      "highBidAmount": {
        "value": 1,
        "major": "text",
        "display": "text",
        "currency": "text"
      },
      "minimumBid": {
        "value": 1,
        "major": "text",
        "display": "text",
        "currency": "text"
      },
      "currentIncrement": {
        "value": 1,
        "major": "text",
        "display": "text",
        "currency": "text"
      },
      "startsAt": "2026-01-01T00:00:00.000Z",
      "endsAt": "2026-01-01T00:00:00.000Z",
      "position": null,
      "status": "scheduled",
      "enableReserve": true,
      "reserveMet": true,
      "processed": true,
      "createdAt": null,
      "updatedAt": null,
      "canceledAt": null
    },
    "meta": {
      "viewer": {
        "hasBid": true,
        "isWatching": true,
        "isHighBidder": true
      }
    },
    "relationships": {
      "highBid": {
        "data": {
          "type": "bids",
          "id": "text"
        }
      },
      "viewerMaxBid": {
        "data": {
          "type": "max-bids",
          "id": "text"
        }
      },
      "viewerWin": {
        "data": {
          "type": "auction-winners",
          "id": "text"
        }
      }
    }
  },
  "meta": {
    "status": "outbid"
  }
}