logo

Create your first auction

Management API

Here's a quick guide on how to create an auction using Management API and how to bid on an item using Client API. This guide will use the GraphQL UIs in the browser.
If you are following along, please ensure that you have either a valid cookie in the browser or the API key and account ID headers set. See 🔓Auth

Create a Sale

A sale is a grouping of 1 or more items.
Sale input properties:
  • title: Short title for the sale.
  • description: Some further details for the sale could be added here.
  • currency: Only “USD” is supported.
  • bidIncrementTable: The bid increments define the increments by which bids can increase. The bid increment table is optional, but setting it at the sale level means that it will apply to items within the sale.
  • closingTimeCountdown: Setting this optional value at the sale level will apply it to all items within the sale.
graphql
mutation CreateSale{ createSale(accountId: "ACCOUNT_ID", input: { title: "Test Sale", description: "Description for the sale", currency:"USD", bidIncrementTable: { rules: [ { lowRange: 0, highRange: 100000, step: 10000 }, { lowRange: 100000, highRange: 500000, step: 25000 }, ] } closingMethod: OVERLAPPING, closingTimeCountdown: 60000 }) { id status } }
Mutation to create a sale
graphql
{ "data": { "createSale": { "id": "GENERATED_SALE_ID", "status": "UNPUBLISHED" } } }
Response after running createSale mutation

Add Item to the sale

Adds an item for auction to the previously created sale
SaleItem input properties:
  • saleId: Previously generated saleId that item should belong to.
  • title: Title for the item.
  • description: Description for the item.
  • reserve: Set as 200000000 cents or $2,000,000.
  • openDate: The date and time when the auction will start to accept bids.
  • closingDate: The date and time when the auction will be moved to status ‘CLOSING’.
graphql
mutation CreateItemForSale{ createItemForSale(accountId: "ACCOUNT_ID", input: { saleId: "GENERATED_SALE_ID", title: "David Gilmour's 1969 Stratocaster", description: "David Gilmour purchased the guitar, a 1969 model with a maple cap fingerboard and large headstock, in 1970 from Manny's Music in New York City to replace a similar guitar his parents bought him for his 21st birthday, which had been lost while touring with Pink Floyd in the United States in 1968. The Black Strat was originally a sunburst colour, but had been repainted black at Manny's. Since then, it has undergone numerous modifications.", startingBid: 1000 reserve: 200000000 allowedBidTypes: [MAX] openDate: "2024-02-01T15:00:00Z", closingDate:"2024-02-01T16:00:00Z" }){ id dates { openDate closingStart closingEnd } status } }
Mutation to create a SaleItem
graphql
{ "data": { "createItemForSale": { "id": "GENERATED_ITEM_ID", "dates": { "openDate": "2024-02-01T15:00:00Z", "closingStart": "2024-02-01T16:00:00Z", "closingEnd": "2024-02-01T16:01:00Z" }, } } }
Response after running createItemForSale mutation

Publish Sale

After a sale is created and items have been added it is initially in status UNPUBLISHED.
If the sale should go live it needs to be published. After a sale has been published Basta will manage the lifecycle of the sale and handle opening and closing of the sale and its items.
graphql
mutation PublishSale{ publishSale(accountId: "ACCOUNT_ID", input: { saleId: "GENERATED_SALE_ID" }){ id status } }
Mutation to Publish a Sale
graphql
{ "data": { "publishSale": { "id": "GENERATED_SALE_ID", "status": "PUBLISHED" } } }
Response after running publishSale mutation

Get Sale

graphql
query GetSale{ sale(accountId: "ACCOUNT_ID", id: "GENERATED_SALE_ID"){ id status items { edges { node { id dates { closingStart closingEnd } } } } } }
Query to get a sale created for an account
graphql
{ "data": { "sale": { "id": "GENERATED_SALE_ID", "status": "PUBLISHED", "items": { "edges": [ { "node": { "id": "GENERATED_ITEM_ID", "dates": { "openDate": "2024-02-01T15:00:00Z", "closingStart": "2024-02-01T16:00:00Z", "closingEnd": "2024-02-01T16:01:00Z" } } } ] } } } }
Response after running sale query

CreateBidderToken

The owner of a sale must create a bidder token for each bidder, typically after bidder verification. A bid can only be executed if an authorization header with the corresponding bidder token is present.
BidderToken input parameters:
  • userID: The userID of the bidder.
  • ttl: Time to live for the bidder token in minutes.
graphql
mutation CreateBidderToken($accountID: String!) { createBidderToken(accountId: $accountID, input: { metadata: { userId: "user-1", ttl:60 } }){ token expiration } }
graphql
{ "data": { "createBidderToken": { "token": "GENERATED_BIDDER_TOKEN", "expiration": "2023-04-19T17:20:10Z" } } }

Client API

BidOnItem

Here's a code sample to bid on an item:
graphql
{ "Authorization": "Bearer GENERATED_BIDDER_TOKEN" }
To execute a bid an Authorization header must be present !
graphql
mutation MaxBid{ bidOnItem(saleId: "GENERATED_SALE_ID", itemId: "GENERATED_ITEM_ID", amount: 10000, type: MAX) { __typename ...on BidPlacedSuccess { amount bidStatus date bidType } ...on BidPlacedError { errorCode error } } }
Mutation to place a MaxBid on an item
graphql
{ "data": { "bidOnItem": { "__typename": "MaxBidPlacedSuccess" } } }
Response from BidOnItem mutation

Powered by Notaku