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.

closingMethod: Only ‘OVERLAPPING’ is currently supported

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.

startingBid: Initialized as 1000 cents or $10.

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