Send an opening offer

​

Creates one offer for 1–1,000 distinct listings from one seller. Each item supplies only its listing ID and quantity. Supply either total in the listing currency or discountPercentage for the complete item subtotal. Per-item prices are not accepted.

The whole request is validated before creation. Your cart is unchanged, and stock is reserved only on acceptance. An existing live offer with this seller returns 409 with its offerId; cancel an open offer explicitly before replacing it.

The original subtotal must be at least 20 in the listing currency. Discounts may not exceed 40%; totals below 60% of the original subtotal or above the original subtotal return 422. The server allocates prices with the same rounding rules as the website; currentProposal.total is the resulting subtotal. You may make five creation requests per hour across your API credentials. Retries count toward this limit.

Returns the offer summary. Send an optional Idempotency-Key to repeat the same response for 24 hours. Requires offers:write.

Body

required
application/json
  • items
    Type: array of object 1…1000
    required

    The listings and quantities you are offering to buy.

    Properties: 2
  • discountPercentage
    Type: number
    min:  
    0
    max:  
    100

    The percentage discount from the original item subtotal: 20 means 20% off. Discounts above 40% return 422. Exactly one of total or discountPercentage is required.

  • total
    Type: object

    Your proposed subtotal for all selected units, excluding shipping, in the listing currency. Exactly one of total or discountPercentage is required.

    Properties: 2

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/offers
curl https://public-api.cardnexus.com/v1/offers \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "items": [
    {
      "listingId": "665f3a2b1c8d4e9f7a6b5c52",
      "quantity": 2
    }
  ],
  "total": {
    "amount": 25,
    "currency": "EUR"
  }
}'

{
  "id": "665f3a2b1c8d4e9f7a6b5c59",
  "status": "pending",
  "viewerRole": "buyer",
  "buyer": {
    "id": "665f3a2b1c8d4e9f7a6b5c4d",
    "username": "alphabay_cards"
  },
  "seller": {
    "id": "665f3a2b1c8d4e9f7a6b5c4e",
    "username": "north_arena_tcg"
  },
  "itemCount": 1,
  "totalQuantity": 2,
  "originalTotal": {
    "amount": 30,
    "currency": "EUR"
  },
  "currentProposal": {
    "id": "665f3a2b1c8d4e9f7a6b5c60",
    "authorRole": "buyer",
    "total": {
      "amount": 25,
      "currency": "EUR"
    },
    "createdAt": "2026-09-10T14:32:00.000Z"
  },
  "awaitingResponseFrom": "seller",
  "buyerProposalCount": 1,
  "voidReason": null,
  "createdAt": "2026-09-10T14:32:00.000Z",
  "updatedAt": "2026-09-10T14:32:00.000Z",
  "expiresAt": null,
  "actions": [
    {
      "id": "cancel",
      "method": "POST",
      "path": "/v1/offers/665f3a2b1c8d4e9f7a6b5c59/cancel"
    }
  ]
}

Offer returned.