Conditional Bidding

Overview

Create standing orders that automatically bid on auctions matching your criteria. No need to respond to individual bid requests — define your strategy once and bids are applied 24/7.

Checkout Exchanges

See Checkout Exchanges for supported platforms and the getSupportedCheckoutExchanges query.

Creating Conditional Bids

Mutation

mutation CreateConditionalBid($input: CreateConditionalBidInput!) {
  createConditionalBid(input: $input) {
    conditionalBid {
      id
      externalReferenceId
      recipientAddressId
      paymentTokenId
      paymentRail
      assetType
      bidAmountCents
      allInPriceCents
      status
      isActive
      currentFilledQuantity
      maxFilledQuantity
      keyIds
      checkoutExchanges
      expiresAt
      createdAt
    }
    error {
      message
      code
    }
  }
}

Input Fields

Field	Type	Required	Description
assetType	AssetTypeEnum	Yes	Type of asset — see Asset Types for supported values
bidAmountCents	Int	Conditional	Per-unit bid amount in cents. Required if allInPriceCents is not provided
allInPriceCents	Int	Conditional	Total price including platform + processing fees. The system derives bidAmountCents automatically. Required if bidAmountCents is not provided
conditions	JSON	Yes	Matching criteria (see Condition Structure)
maxFilledQuantity	Int	No	Max total quantity to acquire (default: unlimited)
minQuantityPerCheckout	Int	No	Min quantity per match (default: any)
externalReferenceId	String	No	Your reference ID for tracking
recipientAddressId	ID	No	Saved address for shipping purchases from this bid (see Address Management)
paymentTokenId	ID	No	Saved payment method to charge when this bid wins (overrides account default)
paymentRail	PaymentRail	No	How to charge the payment token: CARD, ACH, WIRE (require paymentTokenId), or TRADEPOST_BALANCE, CRYPTO (wallet-based, no token needed)
checkoutExchanges	[String!]	No	Platforms where bid can execute (default: ["TRADEPOST"])
expiresAt	DateTime	No	When the bid expires

Pricing: bidAmountCents vs allInPriceCents

Provide exactly one:

• bidAmountCents — the per-unit bid amount you want to offer the seller. Fees are added on top at checkout.
• allInPriceCents — the total amount you're willing to pay per unit, including platform fees and payment processing fees. The system automatically derives bidAmountCents by subtracting fees.

When using allInPriceCents, the derived bidAmountCents depends on your account's fee configuration and payment method. If your fee configuration changes, bids created with allInPriceCents are automatically recalculated.

Full Example (Ticket)

{
  "query": "mutation CreateConditionalBid($input: CreateConditionalBidInput!) { createConditionalBid(input: $input) { conditionalBid { id externalReferenceId status isActive } error { message code } } }",
  "variables": {
    "input": {
      "assetType": "TICKET",
      "bidAmountCents": 15000,
      "externalReferenceId": "partner-cb-002",
      "maxFilledQuantity": 20,
      "checkoutExchanges": ["TRADEPOST"],
      "expiresAt": "2025-12-31T23:59:59Z",
      "conditions": [
        {
          "mappingData": {
            "externalIdentifiers": {
              "SEATGEEK": "6234567",
              "TICKETMASTER": "vvG1YZ4bJalaRJ"
            }
          },
          "filterData": {
            "sections": ["Floor A", "Floor B", "Floor C"],
            "rows": ["1", "2", "3", "4", "5"],
            "isParking": false
          }
        }
      ]
    }
  }
}

Full Example (Sealed TCG)

{
  "query": "mutation CreateConditionalBid($input: CreateConditionalBidInput!) { createConditionalBid(input: $input) { conditionalBid { id externalReferenceId status isActive } error { message code } } }",
  "variables": {
    "input": {
      "assetType": "SEALED_TCG",
      "bidAmountCents": 8500,
      "externalReferenceId": "partner-tcg-001",
      "maxFilledQuantity": 50,
      "checkoutExchanges": ["TRADEPOST"],
      "conditions": [
        {
          "mappingData": {
            "externalIdentifiers": {
              "TCGPLAYER": "593355"
            }
          },
          "filterData": {
            "conditions": ["UNOPENED"]
          }
        }
      ]
    }
  }
}

Condition Structure

Each condition has two parts: mappingData (what asset to target) and filterData (criteria for matching). Both vary by asset type.

mappingData

Identify the target asset using exactly one (mutually exclusive):

externalIdentifiers — platform IDs:

{
  "mappingData": {
    "externalIdentifiers": {
      "SEATGEEK": "6234567"
    }
  }
}

{
  "mappingData": {
    "externalIdentifiers": {
      "TCGPLAYER": "593355"
    }
  }
}

internalIdentifiers — Tradepost asset config ID:

{
  "mappingData": {
    "internalIdentifiers": {
      "assetConfigId": "550e8400-e29b-41d4-a716-446655440000"
    }
  }
}

filterData (Tickets)

Field	Type	Description
sections	[String]	Acceptable section names. Omit to accept any section. Case-insensitive, spacing matters ("102A" ≠ "102 A")
rows	[String]	Acceptable row identifiers. Omit to accept any row
isParking	Boolean	Match parking tickets (default: false)

Section/row names vary across platforms. Include variations to maximize matches (e.g., ["102", "Section 102", "SEC 102"]).

filterData (Sealed TCG)

Field	Type	Description
conditions	[String]	Acceptable product conditions: UNOPENED, OPENED, DAMAGED. Omit to accept any condition

ConditionalBid Type

Returned by all create, update, cancel, delete, and query operations.

Field	Type	Description
id	ID!	Unique identifier
accountId	ID!	Account that owns this bid
externalReferenceId	String	Your reference ID
recipientAddressId	ID	Saved address for shipping purchases from this bid (see Address Management)
paymentTokenId	ID	Saved payment method to charge when this bid wins (overrides account default)
paymentRail	PaymentRail	How to charge: CARD, ACH, WIRE (require token), or TRADEPOST_BALANCE, CRYPTO (wallet, no token)
assetType	AssetTypeEnum!	Asset type — see Asset Types for supported values
bidAmountCents	Int!	Per-unit bid amount in cents (derived automatically when allInPriceCents is used)
allInPriceCents	Int	Total price including platform + processing fees (null if bid was created with bidAmountCents directly)
conditions	JSON!	Matching criteria (see Condition Structure)
maxFilledQuantity	Int	Max quantity to acquire
currentFilledQuantity	Int!	Items already acquired
minQuantityPerCheckout	Int	Min quantity per match
status	ConditionalBidStatus!	Current status
isActive	Boolean!	Whether bid is actively matching
keyIds	[ID!]	Resolved key IDs (populated after creation from filterData)
checkoutExchanges	[String!]!	Platforms where purchases execute
expiresAt	DateTime	Expiration (null = never)
createdAt	DateTime!	Created timestamp
updatedAt	DateTime!	Last modified timestamp
pausedAt	DateTime	When the bid was paused (null if never paused or resumed)
deletedAt	DateTime	When the bid was soft-deleted (null if not deleted)

Querying Bids

List Bids

query GetMyConditionalBids($input: GetConditionalBidsInput!) {
  getConditionalBids(input: $input) {
    conditionalBids {
      id
      externalReferenceId
      recipientAddressId
      paymentTokenId
      paymentRail
      assetType
      bidAmountCents
      allInPriceCents
      status
      isActive
      currentFilledQuantity
      maxFilledQuantity
      checkoutExchanges
      conditions
      createdAt
      updatedAt
    }
    pagination {
      totalCount
      hasNextPage
    }
    error {
      message
      code
    }
  }
}

Get Single Bid

query GetConditionalBid($input: GetConditionalBidInput!) {
  getConditionalBid(input: $input) {
    conditionalBid {
      id
      externalReferenceId
      recipientAddressId
      paymentTokenId
      paymentRail
      assetType
      bidAmountCents
      allInPriceCents
      status
      isActive
      checkoutExchanges
      conditions
    }
    error {
      message
      code
    }
  }
}

Lookup by either conditionalBidId or externalReferenceId:

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

Filter Options

Filter	Type	Description
assetType	AssetTypeEnum	Filter by single asset type
assetTypes	[AssetTypeEnum!]	Filter by multiple asset types
status	ConditionalBidStatus	Filter by single status (deprecated — use statuses)
statuses	[ConditionalBidStatus!]	Filter by statuses
isActive	Boolean	Active/inactive bids only
ids	[ID!]	Filter by conditional bid IDs
externalReferenceIds	[String!]	Filter by your reference IDs
externalIdentifiers	JSON	Filter by external identifiers in conditions (single value or list per exchange)
recipientAddressId	ID	Bids assigned to a specific saved address
paymentTokenId	ID	Bids assigned to a specific payment token
paymentRail	PaymentRail	Filter by payment rail (CARD, ACH, WIRE, TRADEPOST_BALANCE, CRYPTO)
checkoutExchanges	[String!]	Bids that include ANY of these exchanges
minBidAmountCents	Int	Amount greater than or equal to this value
maxBidAmountCents	Int	Amount less than or equal to this value
createdAfter	DateTime	Created after timestamp
createdBefore	DateTime	Created before timestamp
expiresAfter	DateTime	Expires after timestamp
expiresBefore	DateTime	Expires before timestamp
hasRemainingCapacity	Boolean	Only bids that can still be filled
includeExpired	Boolean	Include expired bids (default: false)
includeDeleted	Boolean	Include soft-deleted bids (default: false)
pagination	SimplePaginationInput	Limit and offset

Sorting

Field	Type	Default	Description
sortBy	ConditionalBidSortBy	CREATED_AT	CREATED_AT, UPDATED_AT, BID_AMOUNT_CENTS, MAX_FILLED_QUANTITY, CURRENT_FILLED_QUANTITY, EXPIRES_AT
sortDirection	SortDirection	DESC	ASC or DESC

Filter by External Identifiers

Single identifier:

{
  "input": {
    "externalIdentifiers": {
      "TICKETMASTER": "vvG1YZ4bJalaRJ"
    }
  }
}

{
  "input": {
    "externalIdentifiers": {
      "TCGPLAYER": "593355"
    }
  }
}

Multiple identifiers:

{
  "input": {
    "externalIdentifiers": {
      "TICKETMASTER": ["event-123", "event-456"]
    }
  }
}

Updating Bids

mutation UpdateConditionalBid($input: UpdateConditionalBidInput!) {
  updateConditionalBid(input: $input) {
    conditionalBid {
      id
      recipientAddressId
      paymentTokenId
      paymentRail
      bidAmountCents
      allInPriceCents
      isActive
      checkoutExchanges
    }
    error {
      message
      code
    }
  }
}

Identify by conditionalBidId or externalReferenceId. Updatable fields: bidAmountCents, allInPriceCents, conditions, maxFilledQuantity, minQuantityPerCheckout, recipientAddressId, paymentTokenId, paymentRail, isActive, checkoutExchanges, expiresAt.

{
  "input": {
    "externalReferenceId": "partner-cb-001",
    "bidAmountCents": 17500,
    "isActive": true
  }
}

Cancelling Bids

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

Identify by conditionalBidId or externalReferenceId.

Deleting Bids

Soft-deletes a conditional bid. The bid is marked as DELETED and excluded from all queries by default. A scheduled cleanup job permanently removes soft-deleted bids after a retention period.

mutation DeleteConditionalBid($input: DeleteConditionalBidInput!) {
  deleteConditionalBid(input: $input) {
    conditionalBid {
      id
      status
      deletedAt
    }
    error {
      message
      code
    }
  }
}

Identify by conditionalBidId or externalReferenceId.

Key behaviors:

• Idempotent — deleting an already-deleted bid returns success without error
• Irreversible — deleted bids cannot be updated, cancelled, or un-deleted
• Invisible — deleted bids are excluded from list queries unless includeDeleted: true is set
• Visible by ID — you can still look up a deleted bid by conditionalBidId or externalReferenceId to confirm it's gone
• External reference preserved — the externalReferenceId is NOT freed after deletion; you cannot reuse it for a new bid
• Webhook — a CONDITIONAL_BID_STATUS_CHANGE webhook is sent with new_status: "DELETED"

Bulk Operations

Bulk Create

Each bid in the array accepts the same fields as CreateConditionalBidInput (including recipientAddressId, paymentTokenId, and paymentRail).

mutation BulkCreateBids($input: BulkCreateConditionalBidsInput!) {
  bulkCreateConditionalBids(input: $input) {
    results {
      conditionalBid {
        id
        externalReferenceId
        checkoutExchanges
      }
      error {
        message
        code
      }
    }
    successCount
    errorCount
    totalCount
  }
}

Bulk Update

Each bid in the array accepts the same fields as UpdateConditionalBidInput (including recipientAddressId, paymentTokenId, and paymentRail).

mutation BulkUpdateBids($input: BulkUpdateConditionalBidsInput!) {
  bulkUpdateConditionalBids(input: $input) {
    results {
      conditionalBid {
        id
        bidAmountCents
        allInPriceCents
        isActive
        checkoutExchanges
      }
      error {
        message
        code
      }
      externalReferenceId
    }
    successCount
    errorCount
    totalCount
  }
}

{
  "input": {
    "conditionalBids": [
      {
        "externalReferenceId": "partner-cb-001",
        "bidAmountCents": 20000
      },
      {
        "conditionalBidId": "550e8400-e29b-41d4-a716-446655440000",
        "isActive": false
      }
    ]
  }
}

Bulk Cancel

mutation BulkCancelBids($input: BulkCancelConditionalBidsInput!) {
  bulkCancelConditionalBids(input: $input) {
    results {
      conditionalBid {
        id
        status
      }
      error {
        message
        code
      }
      externalReferenceId
    }
    successCount
    errorCount
    totalCount
  }
}

Supports two modes (can be combined):

By specific bids:

{
  "input": {
    "conditionalBids": [
      { "externalReferenceId": "partner-cb-001" },
      { "conditionalBidId": "550e8400-e29b-41d4-a716-446655440000" }
    ]
  }
}

By external identifiers (cancels ALL matching bids):

{
  "input": {
    "externalIdentifiers": {
      "TICKETMASTER": ["event-123", "event-456", "event-789"]
    }
  }
}

{
  "input": {
    "externalIdentifiers": {
      "TCGPLAYER": ["593355", "285229"]
    }
  }
}

Field	Type	Description
conditionalBids	[CancelConditionalBidInput!]	Cancel specific bids by ID or externalReferenceId
externalIdentifiers	JSON	Cancel ALL bids matching these identifiers. Supports single value or list per exchange

At least one of conditionalBids or externalIdentifiers must be provided.

Bulk Delete

Soft-deletes multiple bids. Supports the same two modes as bulk cancel.

mutation BulkDeleteBids($input: BulkDeleteConditionalBidsInput!) {
  bulkDeleteConditionalBids(input: $input) {
    results {
      conditionalBid {
        id
        status
        deletedAt
      }
      error {
        message
        code
      }
    }
    successCount
    errorCount
    totalCount
  }
}

By specific bids:

{
  "input": {
    "conditionalBids": [
      { "externalReferenceId": "partner-cb-001" },
      { "conditionalBidId": "550e8400-e29b-41d4-a716-446655440000" }
    ]
  }
}

By external identifiers (deletes ALL matching bids):

{
  "input": {
    "externalIdentifiers": {
      "TICKETMASTER": ["event-123", "event-456"]
    }
  }
}

Field	Type	Description
conditionalBids	[DeleteConditionalBidInput!]	Delete specific bids by ID or externalReferenceId
externalIdentifiers	JSON	Delete ALL bids matching these identifiers. Supports single value or list per exchange

At least one of conditionalBids or externalIdentifiers must be provided.

Pause All

mutation PauseAllBids($input: PauseAllConditionalBidsInput!) {
  pauseAllConditionalBids(input: $input) {
    pausedCount
    error {
      message
      code
    }
  }
}

Requires confirm: true.

Status Values

Status	Description
NOT_FILLED	Active, no matches yet
PARTIALLY_FILLED	Some quantity filled
FILLED	Max quantity reached
CANCELLED	Manually cancelled
EXPIRED	Past expiration date
ON_HOLD	Under risk review
DELETED	Soft-deleted, excluded from queries by default

Webhook Notifications

CONDITIONAL_BID_APPLIED

Sent when a conditional bid is applied to an auction:

{
  "msg_type": "CONDITIONAL_BID_APPLIED",
  "msg_id": "770e8400-e29b-41d4-a716-446655440002",
  "sent_at": 1736616000,
  "source_id": "tradepost_auction_service",
  "destination_id": "partner_acme",
  "payload": {
    "conversation_id": "conv_123",
    "external_reference_id": "partner-cb-001",
    "ico_id": "ico_456",
    "ico_item_id": "icoi_789",
    "reference_type": "INSTANT_CASH_OFFER",
    "reference_id": "ico_456",
    "bid_amount_cents": 15000,
    "applied_at": 1736616000,
    "asset_type": "TICKET | SEALED_TCG",
    "external_ids": { ... },
    "asset_details": { ... },
    "config_details": { ... },
    "item_details": { ... }
  }
}

CONDITIONAL_BID_STATUS_CHANGE

Sent when a conditional bid status changes:

{
  "msg_type": "CONDITIONAL_BID_STATUS_CHANGE",
  "msg_id": "770e8400-e29b-41d4-a716-446655440003",
  "sent_at": 1736616000,
  "source_id": "tradepost_auction_service",
  "destination_id": "partner_acme",
  "payload": {
    "conditional_bid_id": "550e8400-e29b-41d4-a716-446655440000",
    "external_reference_id": "partner-cb-001",
    "old_status": "NOT_FILLED",
    "new_status": "ON_HOLD",
    "reason": "Aggregate risk $7,500.00 exceeds threshold",
    "external_identifiers": {
      "TICKETMASTER": "vvG1YZ4bJalaRJ"
    },
    "status_changed_at": 1736616000
  }
}

Common Status Transitions:

• NOT_FILLED → ON_HOLD (risk review triggered)
• ON_HOLD → NOT_FILLED (mapping verified, bid resumed)
• ON_HOLD → CANCELLED (mapping rejected)
• NOT_FILLED/PARTIALLY_FILLED → EXPIRED (bid reached expires_at deadline)
• Any status → DELETED (bid soft-deleted via deleteConditionalBid)
• DELETED is a terminal state — deleted bids cannot be updated, cancelled, or un-deleted

CONDITIONAL_BID_EXPIRING_SOON

Advisory notification sent when a conditional bid is approaching its expiration deadline. The bid remains active — this is an advance warning.

{
  "msg_type": "CONDITIONAL_BID_EXPIRING_SOON",
  "msg_id": "880e8400-e29b-41d4-a716-446655440010",
  "sent_at": 1736616000,
  "source_id": "tradepost_auction_service",
  "destination_id": "partner_acme",
  "payload": {
    "conditional_bid_id": "550e8400-e29b-41d4-a716-446655440000",
    "external_reference_id": "partner-cb-001",
    "current_status": "NOT_FILLED",
    "expires_at": 1736619600,
    "seconds_remaining": 3600
  }
}

Sent once per expiration deadline (default: 1 hour before). If you extend expires_at, a new notification is sent as the updated deadline approaches. Use this to renew the bid or adjust your strategy.

Error Codes

Code	Description
NOT_FOUND	Bid not found — check your reference ID
ACCESS_DENIED	Not authorized to access this bid
DUPLICATE_REFERENCE	External reference ID already exists — must be unique
VALIDATION_ERROR	Invalid input data
MAPPING_CONFLICT	External identifiers map to different assets
PAYMENT_TOKEN_NOT_FOUND	Payment token not found or doesn't belong to your account
INVALID_PAYMENT_RAIL	Payment rail is incompatible with the token type (e.g., CARD rail on a bank account token) or violates constraints (e.g., token-based rail without a token, wallet rail with a token)
BUYER_CONFIGURATION_NOT_FOUND	No buyer configuration found — required when using allInPriceCents
REJECTED_ASSET_MAPPING	Asset mapping was previously rejected — verify event IDs or contact support
BID_DELETED	Cannot update or cancel a deleted bid — the bid has been soft-deleted

Support

• Email: support@tradepost.co
• Include: Asset type, example conditions, error messages

---

← Webhooks | GraphQL API →

© 2026 Tradepost Markets Inc. All rights reserved.