Description
Create items within an already defined auction. This API call adds items to the auction - there may or may not be items in the auction already.
The API is very flexible and only the item type is needed to create a new item (all data can of course be reviewed and changed within the bidlogix admin system). Having said that the API allows any or all of the fields to be set in the API call, although errors will be generated if values of the wrong type are sent (e.g. sending a string instead of a numeric value).
Apart from this the error handling is very lenient and default values will be provided where no value is sent in the API.
URL
where
https://your_bidlogix_domain/auction-mgt/bdxapi/items/{auctionId}?clientId=your_bidlogix_client_id |
{auctionId} : the id of the auction you wish to create items within.Method
Http Method: POST
Security
See Bidlogix API document.
Query String Parameters
See Bidlogix API document.
Post Data
The minimum data that needs to be sent to bidlogix to create an item are the item type and a class identifier for internal bidlogix use.
Also type='WebcastItem' is only valid if the auction type is Webcast.
Name | Type | Value Range | Required | Default |
|---|---|---|---|---|
| type | String | Listing, Lot, WebcastItem, BulkBuyItem | Y | - |
| @class | String | com.bidlogix.scaffold.models.auctionapi.ItemApiModel | Y | - |
Errors in sent values will be corrected automatically. Validation tools and life cycle workflows within the bidlogix system are designed to check bidding data before items are made live. The API is mainly intended for asset database content - titles and images can be easily uploaded into auctions within the bidlogix platform.
Lot numbers will default to the index of the item within the list of items, and the title will default to 'Item for lot number x'.
Name | Type | Value range | Required | Default |
|---|---|---|---|---|
| The following set of fields apply to all item types (Listing, Lot, BulkBuy, Webcast) | ||||
| lotNumber | String | If not supplied the lot number is generated as the index of the item in the list. Lot numbers cannot contain duplicate values. | N | item index |
| title | String | The title of the auction - required is using strict validation | Y | Item for lot number x |
| summary | String | A short summary of the item or alternate information such as estimate of the sale price. | N | none |
| description | String | A full description displayed on the item details page. | N | none |
images | List<UrlAttachmentApiModel> | see Common Data document | N | none |
| documents | List<UrlAttachmentApiModel> | see Common Data document | N | none |
| videos | List<UrlAttachmentApiModel> | see Common Data document. Set the Youtube video id as the URL of the model object to attach Youtube videos to the item. | N | none |
| location | AddressModel | see Common Data document | N | from auction |
buyersPremium | Long | 0 - 100 | N | from auction |
contactSellerEnabled | Boolean | Enables the contact vendor feature per item. | N | false |
| currency | CurrencyModel | see Common Data document | N | from auction |
| vendorId | Long | Valid bidlogix vendor id | Y | first defined |
| categoryId | Long | Valid bidlogix category id | Y | first defined |
Fields related to charges and invoicing of the item... | ||||
| charges | Big Decimal | N | 0.00 | |
buyersPremium | Big Decimal | N | from auction | |
chargesTaxRate | Big Decimal | N | from auction | |
hammerTaxRate | Big Decimal | N | from auction | |
bpTaxRate | Big Decimal | N | from auction | |
Listing specific fields - listings do not support bidding. They optionally support buy now, make offer and transfer options. | ||||
| purchaseOption | String | Listing: 'NONE', 'MAKE_OFFER', 'BUY_NOW', 'TRANSFER', 'TENDER', 'TENDER_PCT' | NONE | |
minimumAcceptableOffer | Long | Applies only if purchaseOption=MAKE_OFFER or BUY_NOW. If purchaseOption=MAKE_OFFER then offers including and below this amount will be automatically rejected. If purchaseOption=BUY_NOW then this field represents the buy now purchase price. | Y for BUY_NOW | NONE |
| displayPrice | Long | An optional value to display on listings with a private treaty, or items for TRANSFER. | NONE | |
| unitOfMeasurement | String | Required for listings with the purchase options of TENDER or TENDER_PCT. For TENDER, the value should be the unit of measurement of the quantity provided e.g. 'Tonne'. For TENDER_PCT, the value is a label describing the nature of the % value being offered e.g. 'Discount on LME spot price'. | Y for TENDER, TENDER_PCT | |
| numberOfUnits | Big Decimal | For TENDER and TENDER_PCT listings, the number or approximate number of units available. | Y for TENDER, TENDER_PCT | |
Lot specific fields - lots support bidding. They also optionally support buy now and make offer options. | ||||
| purchaseOption | String | Lot: 'NONE', 'MAKE_OFFER', 'BUY_NOW' | NONE | |
minimumAcceptableOffer | Long | Applies only if purchaseOption=MAKE_OFFER or BUY_NOW. If purchaseOption=MAKE_OFFER then offers below this amount will be automatically rejected. If purchaseOption=BUY_NOW then this field represents the buy now price. | NONE | |
openingBid | Long | The amount to show as the starting bid. | 0 | |
| bidIncrement | Long | The increment - this may be overridden if the auctioneer is using increment tables! | 10 | |
| reservePrice | Long | A price the item must fetch before being sold | 0 | |
| numberOfUnits | Long | The number of units available. Bidding is per item i.e. all units. | 1 | |
BulkBuy specific fields - bulk buy (multi items) do not support bidding. They are intended to be used with the 'make offer' function but with items composed of multiple units. Users can then make offers different multiples of these units. | ||||
numberOfUnits | Long | The total number of units of the item available. | ||
Webcast Item specific fields - used exclusively in live Webcast auctions. They are similar to lots in that they support bidding but they do not support the purchase option functions; make offer, buy now and transfer. Unlike lots these items support bidding type; per item or per unit and can be grouped and sold together with various options for the bidding. | ||||
biddingType | Long | per item or per lot. 2 - per item 3 - per Lot | per lot | |
openingBid | Long | The amount to show as the starting bid. | 0 | |
| bidIncrement | Long | The increment - this may be overridden if the auctioneer is using increment tables! | 10 | |
| reservePrice | Long | A price the item must fetch before being sold | 0 | |
| numberOfUnits | Long | The number of units available. Bidding is per item i.e. all units. | 1 | |
Examples
Please find attached a working json post call.
Request 1: No Images
|
Response:
{ "@class":".BackboneCollectionModel", "collection":[ { "@class":".auctionapi.ItemApiModel", "id":225, "type":"Listing", "auctionIndex":2, "title":"Title for Item 1", "summary":null, "description":null, "lotNumber":"1", "statusId":2, "endTime":1479340800000, "endTimeReadable":"2016-11-17T00:00:00.000Z", "locale":null, "hammerTaxRate":20, "bpTaxRate":20, "chargesTaxRate":20, "buyersPremium":15, "vendor":{ "@class":".VendorModel", "id":10, "auctioneer":null, "name":"Apex Auctions Ltd", "companyContact":null, "contacts":[ ], "contactable":false, "activated":false, "summary":null, "description":null, "timeZone":null, "administrators":[ ] }, "category":{ "@class":".CategoryModel", "id":1, "name":"Turning", "code":null, "selected":false, "treeName":"Industrial Machinery", "treeId":1, "parentName":null, "parentId":null, "children":null } }, { "@class":".auctionapi.ItemApiModel", "id":226, "type":"Listing", "auctionIndex":3, "title":"Title for Item 2", "summary":null, "description":null, "lotNumber":"2", "statusId":2, "endTime":1479340800000, "endTimeReadable":"2016-11-17T00:00:00.000Z", "locale":null, "hammerTaxRate":20, "bpTaxRate":20, "chargesTaxRate":20, "buyersPremium":15, "vendor":{ "@class":".VendorModel", "id":10, "auctioneer":null, "name":"Apex Auctions Ltd", "companyContact":null, "contacts":[ ], "contactable":false, "activated":false, "summary":null, "description":null, "timeZone":null, "administrators":[ ] }, "category":{ "@class":".CategoryModel", "id":1, "name":"Turning", "code":null, "selected":false, "treeName":"Industrial Machinery", "treeId":1, "parentName":null, "parentId":null, "children":null } } ]}
|
Request 2: With Images
|
Response
|
Errors
Errors are handled where possible by returning an ErrorModel with the field 'failed' set to true. The error model will contain a detailed message indicating the first errored field. The errors are generally related to incorrect types being sent in the fields above. For example the following fails because a 'string' value is sent in the 'charges' field which should contain a big decimal value.
Status Code: 400 (Bad Request)
|
Yields the response...
|
Notes
- Duplicate lot numbers were previously allowed via the API but were considered validation errors within bidlogix management. As of November 2019, this is no longer the case and attempting to create items with lot numbers that already exist in the system for this auction will return a 400 error response (with the duplicates listed in the body of the error response).
- Items are created in state 'DRAFT'. See table below for current bidlogix item states.
|