Buying Integration Guide

Everything you need to go from zero to live on Tradepost, focused on the Conditional Bidding path — standing orders that auto-buy matching inventory 24/7.

Step 1: Get Access

Contact Tradepost to become an approved Liquidity Provider. Once approved, you'll receive:

A Terminal account at terminal.tradepost.co
Access to the GraphQL API at https://platform-api.tradepost.co/graphql

See Quick Links for all endpoints and contact info.

Step 2: Set Up Authentication

Generate an API key in Terminal under Settings > API Keys.

Include it in every request as the X-API-Key header:

Example Request
curl -X POST https://platform-api.tradepost.co/graphql \
  -H "Content-Type: application/json" \
  -H "X-API-Key: tp_live_your_api_key_here" \
  -d '{ "query": "mutation { ... }" }'

Security

Store keys in environment variables, never in code. Rotate keys periodically.

See Authentication for error codes and details.

Step 3: Add a Payment Method

In Terminal, go to Payment Methods and add a credit or debit card.

You're only charged after items are transferred to you — never before. See Platform Fees for fee rates (starting at 8% of bid amount).

See Payments for the full payment flow.

Step 4: Configure Your Webhook Endpoint

Set up an HTTPS endpoint on your server to receive TPX messages. Configure it in Terminal under Settings > Webhooks.

Every webhook follows this structure:

Webhook Message Structure
{
  "msg_type": "BID_REQUEST",
  "msg_id": "123e4567-e89b-12d3-a456-426614174000",
  "sent_at": 1736614800,
  "source_id": "tradepost_auction_service",
  "destination_id": "partner_yourname",
  "payload": { ... }
}

Your endpoint should return 200 OK for every message received.

See Webhooks for all message types and payload examples.

Step 5: Create Conditional Bids

This is the core of your integration. Conditional bids are standing orders that automatically bid on auctions matching your criteria — no need to respond to individual bid requests.

Create a Conditional Bid
mutation CreateConditionalBid($input: CreateConditionalBidInput!) {
  createConditionalBid(input: $input) {
    conditionalBid {
      id
      status
      isActive
      bidAmountCents
      currentFilledQuantity
      maxFilledQuantity
    }
    error { message code }
  }
}

Example Variables
{
  "input": {
    "assetType": "TICKET",
    "bidAmountCents": 15000,
    "externalReferenceId": "partner-cb-001",
    "maxFilledQuantity": 20,
    "checkoutExchanges": ["TRADEPOST"],
    "conditions": [
      {
        "mappingData": {
          "externalIdentifiers": {
            "SEATGEEK": "6234567"
          }
        },
        "filterData": {
          "sections": ["Floor A", "Floor B"],
          "rows": ["1", "2", "3"],
          "isParking": false
        }
      }
    ]
  }
}

Key fields:

Field	What it does
`assetType`	What you're buying (e.g. `TICKET`)
`bidAmountCents`	Your bid in cents (e.g. `15000` = $150)
`conditions`	Array of matching criteria — each with `mappingData` (which asset) and `filterData` (which sections/rows)
`externalReferenceId`	Your own ID for tracking this bid
`maxFilledQuantity`	Cap on total items to acquire
`checkoutExchanges`	Which platforms to match on (e.g. `TRADEPOST`, `SEATGEEK`)

See Conditional Bidding for all fields, condition structure, and bulk operations. See Checkout Exchanges for supported platforms.

Step 6: Manage Your Bids

Update bids to change pricing, pause/resume, or adjust criteria. Cancel bids you no longer need.

Update a Bid

Identify by conditionalBidId or externalReferenceId. You can update any combination of fields.

Update a Conditional Bid
mutation UpdateConditionalBid($input: UpdateConditionalBidInput!) {
  updateConditionalBid(input: $input) {
    conditionalBid {
      id
      bidAmountCents
      isActive
      checkoutExchanges
    }
    error { message code }
  }
}

Example: Change price and pause
{
  "input": {
    "externalReferenceId": "partner-cb-001",
    "bidAmountCents": 17500,
    "isActive": false
  }
}

Updatable fields: bidAmountCents, conditions, maxFilledQuantity, minQuantityPerCheckout, isActive, checkoutExchanges, expiresAt

Cancel a Bid

Cancel a Conditional Bid
mutation CancelConditionalBid($input: CancelConditionalBidInput!) {
  cancelConditionalBid(input: $input) {
    conditionalBid {
      id
      status
    }
    error { message code }
  }
}

Example Variables
{
  "input": {
    "externalReferenceId": "partner-cb-001"
  }
}

Bulk operations are also available — create, update, and cancel many bids in a single request.

See Conditional Bidding for bulk mutations and the full query/filter API.

Step 7: Handle Webhooks

TPX communicates with your system through webhook messages. Your endpoint will receive events for auction results, offer status changes, transfers, payments, and more.

Each message includes a msg_type field telling you what happened and a payload with the relevant data. Your endpoint should return 200 OK for every message.

See Webhook Messages for all message types, full payload examples, and handling requirements.

Step 8: Confirm Transfers

After winning, sellers transfer items to your configured email. Tradepost can auto-confirm transfers by monitoring your inbox, or you can confirm manually:

Confirm a Transfer
mutation ProcessPartnerTransfer($input: ProcessPartnerTransferInput!) {
  processPartnerTransfer(input: $input) {
    message { msgType payload { conversationId status } }
    error { message code }
  }
}

Example Variables
{
  "input": {
    "conversationId": "conv_abc123",
    "status": "CONFIRMED"
  }
}

Statuses: CONFIRMED (items received), REJECTED (fraudulent/invalid), NOT_RECEIVED (never arrived).

See Transfers & Settlements for details. See GraphQL API for the full mutation reference.

Step 9: You're Live

That's it. Your conditional bids are running 24/7, automatically matching and purchasing inventory. From here:

Monitor incoming webhooks for auction results and payment events
Manage bids — update, pause, or cancel via the Conditional Bidding API
Track orders and activity in Terminal or via the API
Reconcile payments using PAYMENT_SETTLED webhooks

See Query Orders and Query Activity for API-based monitoring.

Questions? Reach out to engineering@tradepost.co for technical support.

Step 1: Get Access​

Step 2: Set Up Authentication​

Step 3: Add a Payment Method​

Step 4: Configure Your Webhook Endpoint​

Step 5: Create Conditional Bids​

Step 6: Manage Your Bids​

Update a Bid​

Cancel a Bid​

Step 7: Handle Webhooks​

Step 8: Confirm Transfers​

Step 9: You're Live​