WORKING
TradeSessions
get
/v1/trade-sessionsList trade sessions for a seller (as either sellerA or sellerB). Trade sessions are always system-generated from an accepted offer, never created directly via this API.
Parameters
| sellerId | query | required |
Response (200)
get
/v1/trade-sessions/{id}Get a trade session
Parameters
| id | path | required |
Response (200)
| Field | Type | Required |
|---|---|---|
| id | string (uuid) | — |
| offerId | string,null (uuid) | — |
| sellerAId | string (uuid) | — |
| sellerBId | string (uuid) | — |
| status | DRAFT | PENDING | OFFERED | ACCEPTED | RESERVING | RESERVED | WAITING_CHECKOUT_A | WAITING_CHECKOUT_B | CHECKOUT_A_COMPLETE | CHECKOUT_B_COMPLETE | SCHEDULING_A | SCHEDULING_B | EXCHANGE_A_CONFIRMED | EXCHANGE_B_CONFIRMED | EXCHANGE_FAILED | LOCKED | FULFILLMENT | FULFILLED | COMPLETED | CANCELLED | EXPIRED | PAYMENT_FAILED | RESERVATION_FAILED | FULFILLMENT_FAILED | RETURNED | REFUNDED | — |
| fulfillmentMode | MERCHANT_CHECKOUT | PEER_TO_PEER | — |
| tradeValue | numbernull | — |
| currency | string | — |
| createdAt | string (date-time) | — |
| updatedAt | string (date-time) | — |
| expiresAt | string,null (date-time) | — |
| lockedAt | string,null (date-time) | — |
| completedAt | string,null (date-time) | — |
| listingsA | object[] | — |
| listingsB | object[] | — |
| reservations | object[] | — |
| payments | object[] | — |
post
/v1/trade-sessions/{id}/cancelCancel a trade session — only a party to the trade (sellerA or sellerB) may cancel, and only while the session is before LOCKED/FULFILLMENT/FULFILLED/COMPLETED/CANCELLED/ RETURNED/REFUNDED. Releases any RESERVED reservations as a side effect.
Parameters
| id | path | required |
| optional |
Request body
| Field | Type | Required |
|---|---|---|
| actingSellerId | string (uuid) | yes |
| reason | string | — |
Response (201)
| Field | Type | Required |
|---|---|---|
| id | string (uuid) | — |
| offerId | string,null (uuid) | — |
| sellerAId | string (uuid) | — |
| sellerBId | string (uuid) | — |
| status | DRAFT | PENDING | OFFERED | ACCEPTED | RESERVING | RESERVED | WAITING_CHECKOUT_A | WAITING_CHECKOUT_B | CHECKOUT_A_COMPLETE | CHECKOUT_B_COMPLETE | SCHEDULING_A | SCHEDULING_B | EXCHANGE_A_CONFIRMED | EXCHANGE_B_CONFIRMED | EXCHANGE_FAILED | LOCKED | FULFILLMENT | FULFILLED | COMPLETED | CANCELLED | EXPIRED | PAYMENT_FAILED | RESERVATION_FAILED | FULFILLMENT_FAILED | RETURNED | REFUNDED | — |
| fulfillmentMode | MERCHANT_CHECKOUT | PEER_TO_PEER | — |
| tradeValue | numbernull | — |
| currency | string | — |
| createdAt | string (date-time) | — |
| updatedAt | string (date-time) | — |
| expiresAt | string,null (date-time) | — |
| lockedAt | string,null (date-time) | — |
| completedAt | string,null (date-time) | — |
| listingsA | object[] | — |
| listingsB | object[] | — |
| reservations | object[] | — |
| payments | object[] | — |
post
/v1/trade-sessions/{id}/scheduling/confirmPeer-to-peer trade completion (Phase 26) — either party confirms the exchange happened on their side. Once both sides have confirmed, the session moves to COMPLETED.
Parameters
| id | path | required |
| optional |
Request body
| Field | Type | Required |
|---|---|---|
| actingSellerId | string (uuid) | yes |
| confirmedByMerchantUserId | string (uuid) | — |
Response (200)
| Field | Type | Required |
|---|---|---|
| id | string (uuid) | — |
| offerId | string,null (uuid) | — |
| sellerAId | string (uuid) | — |
| sellerBId | string (uuid) | — |
| status | DRAFT | PENDING | OFFERED | ACCEPTED | RESERVING | RESERVED | WAITING_CHECKOUT_A | WAITING_CHECKOUT_B | CHECKOUT_A_COMPLETE | CHECKOUT_B_COMPLETE | SCHEDULING_A | SCHEDULING_B | EXCHANGE_A_CONFIRMED | EXCHANGE_B_CONFIRMED | EXCHANGE_FAILED | LOCKED | FULFILLMENT | FULFILLED | COMPLETED | CANCELLED | EXPIRED | PAYMENT_FAILED | RESERVATION_FAILED | FULFILLMENT_FAILED | RETURNED | REFUNDED | — |
| fulfillmentMode | MERCHANT_CHECKOUT | PEER_TO_PEER | — |
| tradeValue | numbernull | — |
| currency | string | — |
| createdAt | string (date-time) | — |
| updatedAt | string (date-time) | — |
| expiresAt | string,null (date-time) | — |
| lockedAt | string,null (date-time) | — |
| completedAt | string,null (date-time) | — |
| listingsA | object[] | — |
| listingsB | object[] | — |
| reservations | object[] | — |
| payments | object[] | — |
post
/v1/trade-sessions/{id}/scheduling/failEither party reports the peer-to-peer exchange failed (no-show, item mismatch)
Parameters
| id | path | required |
| optional |
Request body
| Field | Type | Required |
|---|---|---|
| actingSellerId | string (uuid) | yes |
| reason | string | — |
Response (200)
| Field | Type | Required |
|---|---|---|
| id | string (uuid) | — |
| offerId | string,null (uuid) | — |
| sellerAId | string (uuid) | — |
| sellerBId | string (uuid) | — |
| status | DRAFT | PENDING | OFFERED | ACCEPTED | RESERVING | RESERVED | WAITING_CHECKOUT_A | WAITING_CHECKOUT_B | CHECKOUT_A_COMPLETE | CHECKOUT_B_COMPLETE | SCHEDULING_A | SCHEDULING_B | EXCHANGE_A_CONFIRMED | EXCHANGE_B_CONFIRMED | EXCHANGE_FAILED | LOCKED | FULFILLMENT | FULFILLED | COMPLETED | CANCELLED | EXPIRED | PAYMENT_FAILED | RESERVATION_FAILED | FULFILLMENT_FAILED | RETURNED | REFUNDED | — |
| fulfillmentMode | MERCHANT_CHECKOUT | PEER_TO_PEER | — |
| tradeValue | numbernull | — |
| currency | string | — |
| createdAt | string (date-time) | — |
| updatedAt | string (date-time) | — |
| expiresAt | string,null (date-time) | — |
| lockedAt | string,null (date-time) | — |
| completedAt | string,null (date-time) | — |
| listingsA | object[] | — |
| listingsB | object[] | — |
| reservations | object[] | — |
| payments | object[] | — |