GraphQL Responses

Overview

Partners interact with TPX by sending GraphQL mutations to respond to webhook messages. This document details the available mutations, their input requirements, and expected responses.

GraphQL Endpoint

• URL: https://platform-api.tradepost.co/graphql
• Method: POST
• Content-Type: application/json
• Authentication: Required (see Authentication)

Field Naming Flexibility: While GraphQL conventionally uses camelCase and we return responses in camelCase, our API accepts both naming formats:

• Recommended: Send fields in camelCase (e.g., conversationId, bidAmountCents)
• Also Accepted: Send fields in snake_case (e.g., conversation_id, bid_amount_cents)

We automatically convert incoming fields to our internal format, giving you flexibility to use your preferred naming convention.

Available Mutations

1. createLiveBid (Deprecated)

Deprecated

This mutation is deprecated. Use Conditional Bidding instead.

Submit a bid in response to a BID_REQUEST webhook message during an active auction.

Mutation

mutation CreateLiveBid($input: CreateLiveBidInput!) {
  createLiveBid(input: $input) {
    message {
      msgType
      msgId
      sentAt
      sourceId
      destinationId
      payload {
        conversationId
        conditionalBidId
        bidId
        isWinner
      }
    }
    error {
      message
      code
    }
  }
}

Input Fields

Field	Type	Required	Description
conversationId	String	Yes	The conversation_id from the bid_request message
quantityToExecute	Int	Yes	Number of items you want to bid on (must match quantity from bid_request)
bidAmountCents	Int	Yes	Your offer in cents (price per unit)
expiresAt	DateTime	Yes	When your bid expires (ISO 8601 format with timezone)
externalReferenceId	String	No	Your external reference ID for tracking this bid (will be returned in AUCTION_RESULT and INSTANT_CASH_OFFER_STATUS_CHANGE webhooks)
externalMsgId	String	No	Your internal message ID for tracking
keyId	String	No	Key ID for targeted bidding at a specific pricing level (from fair_values in BID_REQUEST)

Important: Live bids via createLiveBid are always for the full quantity shown in the BID_REQUEST. You cannot bid on partial quantities. The system may split the offer across multiple partners at auction closure to maximize revenue.

Example: Submit Bid

{
  "query": "mutation CreateLiveBid($input: CreateLiveBidInput!) { createLiveBid(input: $input) { message { msgType msgId sentAt payload { conversationId bidId isWinner } } error { message code } } }",
  "variables": {
    "input": {
      "conversationId": "70f60410-ffed-4f39-91ac-180395c995b7",
      "quantityToExecute": 2,
      "bidAmountCents": 11500,
      "expiresAt": "2025-12-16T12:35:00Z",
      "externalReferenceId": "internal-bid-ref-789",
      "externalMsgId": "partner-msg-12345"
    }
  }
}

Note: The externalReferenceId you provide here will be returned to you in the AUCTION_RESULT webhook (if you win or lose) and in the INSTANT_CASH_OFFER_STATUS_CHANGE webhook (when the seller accepts/declines/expires your winning bid). This allows you to correlate webhook notifications back to your internal systems.

2. processPartnerTransfer

Process item transfers after winning an auction - confirm receipt, reject fraudulent items, or report missing deliveries.

Mutation

mutation ProcessTransfer($input: ProcessPartnerTransferInput!) {
  processPartnerTransfer(input: $input) {
    transfer {
      id
      status
      completedAt
    }
    error {
      message
      code
    }
  }
}

Input Fields

Field	Type	Required	Description
transferId	UUID	Yes	Transfer ID from fulfillment_info in INSTANT_CASH_OFFER_STATUS_CHANGE webhook
action	PartnerTransferAction	Yes	Action to take: CONFIRMED, REJECTED, or NOT_RECEIVED
reason	TransferRejectionReason	Conditional	Required for REJECTED and NOT_RECEIVED actions

Actions

Action	When to Use	What Happens	Requires Reason
CONFIRMED	Items received successfully	Transfer completed, seller paid	No
REJECTED	Items fraudulent/counterfeit/invalid	Transfer rejected, seller notified	Yes
NOT_RECEIVED	Items never arrived	Transfer cancelled, investigation started	Yes

Rejection Reasons

Reason	When to Use
COUNTERFEIT	Items are fake/counterfeit
FRAUD	Fraudulent listing or bait-and-switch
DAMAGED	Items arrived damaged or defective
WRONG_ITEMS	Wrong items sent (not matching listing)
INCOMPLETE	Some items missing from shipment
NOT_RECEIVED	Transfer never received
LATE_DELIVERY	Items arrived too late
OTHER	Other issue not covered above

Examples

Confirm receipt:

{
  "query": "mutation ProcessTransfer($input: ProcessPartnerTransferInput!) { processPartnerTransfer(input: $input) { transfer { id status } error { message code } } }",
  "variables": {
    "input": {
      "transferId": "660e8400-e29b-41d4-a716-446655440001",
      "action": "CONFIRMED"
    }
  }
}

Reject counterfeit items:

{
  "query": "mutation ProcessTransfer($input: ProcessPartnerTransferInput!) { processPartnerTransfer(input: $input) { transfer { id status } error { message code } } }",
  "variables": {
    "input": {
      "transferId": "660e8400-e29b-41d4-a716-446655440001",
      "action": "REJECTED",
      "reason": "COUNTERFEIT"
    }
  }
}

Report not received:

{
  "query": "mutation ProcessTransfer($input: ProcessPartnerTransferInput!) { processPartnerTransfer(input: $input) { transfer { id status } error { message code } } }",
  "variables": {
    "input": {
      "transferId": "660e8400-e29b-41d4-a716-446655440001",
      "action": "NOT_RECEIVED",
      "reason": "NOT_RECEIVED"
    }
  }
}

Authorization: Only the partner who owns the order can process its transfers.

Idempotency: Safe to call multiple times - already-processed transfers return success without reprocessing.

Pagination

All query endpoints that return lists support offset-based pagination using SimplePaginationInput and return pagination metadata via PaginatedResponse.

SimplePaginationInput

Field	Type	Default	Description
limit	Int	20	Maximum number of items to return (minimum: 1)
offset	Int	0	Number of items to skip

Example:

query {
  getMyTpxOrders(input: {
    pagination: { limit: 10, offset: 20 }
  }) {
    orders { id status }
    pagination { totalCount hasNextPage }
  }
}

PaginatedResponse

Returned alongside list results with metadata for navigating pages.

Field	Type	Description
totalCount	Int	Total number of matching records across all pages
limit	Int	Number of items requested per page
offset	Int	Number of items skipped
hasNextPage	Boolean	Whether more items exist after the current page
hasPreviousPage	Boolean	Whether items exist before the current page

Iterating Through Pages

To paginate through results, increment offset by limit until hasNextPage is false:

Page 1: { limit: 20, offset: 0 }   → hasNextPage: true
Page 2: { limit: 20, offset: 20 }  → hasNextPage: true
Page 3: { limit: 20, offset: 40 }  → hasNextPage: false  ← last page

Response Structure

All mutations return a TpxMessagePayload with either a success message or an error.

Success Response

{
  "data": {
    "createLiveBid": {
      "message": {
        "msgType": "BID_RESPONSE",
        "msgId": "123e4567-e89b-12d3-a456-426614174000",
        "sentAt": 1736625000,
        "sourceId": "tradepost_auction_service",
        "destinationId": "partner_acme",
        "payload": {
          "conversationId": "conv_123",
          "conditionalBidId": null,
          "bidId": "bid-uuid-456",
          "isWinner": false
        }
      },
      "error": null
    }
  }
}

Error Response

{
  "data": {
    "createLiveBid": {
      "message": null,
      "error": {
        "message": "Auction has ended (ended at 1749321479, current time 1749325937)",
        "code": "AUCTION_EXPIRED"
      }
    }
  }
}

Error Codes

Common error codes you may encounter:

Code	Description
CONVERSATION_NOT_FOUND	The conversation_id is invalid or not found
AUCTION_NOT_ACTIVE	The auction is not currently accepting bids (deprecated)
AUCTION_EXPIRED	The auction has already ended (deprecated)
INVALID_BID_AMOUNT	Bid amount is invalid (e.g., negative or zero)
INVALID_BID_QUANTITY	Bid quantity is invalid
DUPLICATE_RESPONSE	A response has already been submitted for this conversation
ACCOUNT_NOT_AUTHORIZED	Your account is not authorized for this action

Support

For GraphQL integration assistance:

• Email: support@tradepost.co
• Include: Mutation name, request/response examples, error messages

---

← Asset Types | Offer Lifecycle →

© 2026 Tradepost Markets Inc. All rights reserved.