Sale

A sale — an order where you are the seller — with the buyer, the address to ship to, your seller fee, and your payout.

buyer
Type: object · OrderParty
required

The other party on an order — the buyer on a sale, the seller on a purchase — with their public profile and reputation.
- avatarUrl
  Type: string nullable
  required
  
  Their avatar URL. null when they haven't uploaded one.
- country
  Type: string nullable
  required
  
  Their country as a two-letter ISO 3166-1 alpha-2 code (e.g. FR, US). null when unknown.
- id
  Type: string
  required
  
  Stable opaque identifier for the other party. Do not parse.
- rating
  Type: object · OrderPartyRating
  required
  
  A party's average review score and the number of reviews behind it.
- reliability
  Type: object · OrderPartyReliabilitynullable
  required
  
  A seller's recent order-handling stats. null for a buyer, or when there aren't enough recent orders to report.
- type
  Type: string enumnullable
  required
  
  pro if they sell as a registered company, individual if they sell as a private person. null when they aren't a seller.
  
  values
  pro
  
  You sell as a registered company.
  
  individual
  
  You sell as a private person.
- username
  Type: string
  required
  
  Their public handle.
completedAt
Type: string · DateStringFormat: date-timenullable
required

When the order closed. null if still open.
currency
Type: string enum
required

The currency every amount in this response is expressed in. Sales are in your selling currency; purchases are in the currency you paid.
values
- USD
  
  US Dollar.
- EUR
  
  Euro.
- GBP
  
  British Pound.
- CAD
  
  Canadian Dollar.
- CHF
  
  Swiss Franc.
deliveredAt
Type: string · DateStringFormat: date-timenullable
required

When the parcel was delivered. null if not yet.
items
Type: array object[]
required

The items in the order, each tied to the inventory line it sold from.
A single line of a sale: the product sold, its condition or grade, quantity, price, and the identifiers to find it in your stock.
- condition
  Type: string · CardConditionenumnullable
  required
  
  The card's condition: NM, LP, MP, HP, or DMG. null when the item is graded or sealed.
  
  values
  NM
  
  Near Mint.
  
  LP
  
  Lightly Played.
  
  MP
  
  Moderately Played.
  
  HP
  
  Heavily Played.
  
  DMG
  
  Damaged.
- customId
  Type: string · CustomId
  min length:
  1
  max length:
  255nullable
  required
  
  Your own identifier for the inventory line this item was sold from, captured at the time of sale. null when the line had none.
- finish
  Type: string
  required
  
  The card's finish, e.g. Standard, Foil, Reverse Holo.
- graded
  Type: object · Gradednullable
  required
  
  Grading details when the item is graded. null for raw cards and sealed products.
- imageUrl
  Type: string nullable
  required
  
  The product image captured at the time of sale. null when there is none.
- inventoryId
  Type: string
  required
  
  The inventory line this item was sold from. Look it up with GET /v1/inventory/{inventoryId}.
- language
  Type: string
  required
  
  The card's language as a two-letter code, e.g. en, fr.
- lineTotal
  Type: object · Money
  required
  
  A monetary amount as a decimal in the currency's major unit paired with its currency code — { amount: 14.99, currency: "USD" } means $14.99.
- productId
  Type: integer · CatalogId
  min:
  -9007199254740991
  max:
  9007199254740991nullable
  required
  
  The catalogue product that was sold. Returned by GET /v1/products. null when the product is no longer in the catalogue.
- productName
  Type: string
  required
  
  The product name captured at the time of sale.
- quantity
  Type: integer
  min:
  -9007199254740991
  max:
  9007199254740991
  required
  
  How many units of this item were sold.
- unitPrice
  Type: object · Money
  required
  
  A monetary amount as a decimal in the currency's major unit paired with its currency code — { amount: 14.99, currency: "USD" } means $14.99.
metadata
Type: object · OrderMetadata
required

Your own key/value pairs on this sale. Empty when you haven't set any. Keys start with a letter and may contain letters, digits, _, . and -, up to 64 characters; values are strings of up to 500 characters. A sale holds at most 50 keys. The buyer never sees them.
- propertyName
  Type: string
  keys:
  string
  max length:
  500
orderNumber
Type: string
required

Human-readable order reference, shared across the sale and the purchase, e.g. OR-ASNBC-1.
payout
Type: object · SalePayout
required

Your payout for a sale and its transfer timeline.
- amount
  Type: object · Moneynullable
  required
  
  What you receive for this order, after the seller fee and any CardNexus Shield shipping-insurance premium. null until it is calculated.
- eligibleAt
  Type: string · DateStringFormat: date-timenullable
  required
  
  When the payout becomes eligible for transfer. null when not yet set.
- paidOutAt
  Type: string · DateStringFormat: date-timenullable
  required
  
  When the payout was transferred to you. null until paid out.
placedAt
Type: string Format: date-time
required

When the order was placed.
sellerFee
Type: object · SellerFee
required

The seller fee CardNexus charged on a sale.
- amount
  Type: object · Money
  required
  
  A monetary amount as a decimal in the currency's major unit paired with its currency code — { amount: 14.99, currency: "USD" } means $14.99.
- percentage
  Type: number
  required
  
  Your seller-fee rate, as a percentage (e.g. 5 for 5%).
shippedAt
Type: string · DateStringFormat: date-timenullable
required

When the order was marked shipped. null if not yet.
shippingAddress
Type: object · OrderShippingAddress
required

A postal address an order ships to.
- city
  Type: string
  required
  
  City.
- countryCode
  Type: string
  required
  
  Destination country as a two-letter ISO 3166-1 alpha-2 code.
- line1
  Type: string
  required
  
  Street address, first line.
- line2
  Type: string nullable
  required
  
  Street address, second line. null when unused.
- phone
  Type: string nullable
  required
  
  Contact phone. null when not provided.
- postalCode
  Type: string
  required
  
  Postal or ZIP code.
- recipientName
  Type: string
  required
  
  Name the parcel is addressed to.
- state
  Type: string nullable
  required
  
  State or province. null when unused.
shippingAmount
Type: object · Money
required

A monetary amount as a decimal in the currency's major unit paired with its currency code — { amount: 14.99, currency: "USD" } means $14.99.
- amount
  Type: number
  required
  
  Decimal amount in the currency's major unit (e.g. 5.23 for €5.23). 2 decimal places for EUR/USD/GBP/CHF/CAD/AUD.
- currency
  Type: string enum
  required
  values
  USD
  
  US Dollar.
  
  EUR
  
  Euro.
  
  GBP
  
  British Pound.
  
  CAD
  
  Canadian Dollar.
  
  CHF
  
  Swiss Franc.
status
Type: string · OrderStatusenum
required

Where the order is in its lifecycle. pending_shipment is awaiting dispatch; shipped and delivered track the parcel; completed is closed and paid out; cancelled_* and resolved_* are the terminal cancellation and dispute outcomes.
values
- pending_shipment
  
  Awaiting dispatch.
- cancellation_requested
  
  The buyer asked to cancel; awaiting a response.
- cancelled_buyer
  
  Cancelled — the buyer's cancellation was accepted.
- cancelled_seller
  
  Cancelled by the seller.
- cancelled_auto
  
  Cancelled automatically by CardNexus.
subtotal
Type: object · Money
required

A monetary amount as a decimal in the currency's major unit paired with its currency code — { amount: 14.99, currency: "USD" } means $14.99.
- amount
  Type: number
  required
  
  Decimal amount in the currency's major unit (e.g. 5.23 for €5.23). 2 decimal places for EUR/USD/GBP/CHF/CAD/AUD.
- currency
  Type: string enum
  required
  values
  USD
  
  US Dollar.
  
  EUR
  
  Euro.
  
  GBP
  
  British Pound.
  
  CAD
  
  Canadian Dollar.
  
  CHF
  
  Swiss Franc.
updatedAt
Type: string Format: date-time
required

When the order last changed.

Examples

{
  "orderNumber": "OR-ASNBC-1",
  "status": "shipped",
  "placedAt": "2026-06-13T15:02:00.000Z",
  "updatedAt": "2026-06-14T09:12:00.000Z",
  "shippedAt": "2026-06-14T09:12:00.000Z",
  "deliveredAt": null,
  "completedAt": null,
  "currency": "EUR",
  "items": [
    {
      "productId": 50212,
      "productName": "Dark Magician (SDMY-EN001)",
      "imageUrl": "https://images.cardnexus.com/yugioh/SDMY-EN001.png",
      "condition": "NM",
      "language": "en",
      "finish": "Standard",
      "graded": null,
      "quantity": 2,
      "unitPrice": {
        "amount": 4.5,
        "currency": "EUR"
      },
      "lineTotal": {
        "amount": 9,
        "currency": "EUR"
      },
      "inventoryId": "665f3a2b1c8d4e9f7a6b5c4d",
      "customId": "YRG|5555-5DS1-2EX-006-f-2-2008-08-01"
    }
  ],
  "subtotal": {
    "amount": 9,
    "currency": "EUR"
  },
  "shippingAmount": {
    "amount": 3.5,
    "currency": "EUR"
  },
  "sellerFee": {
    "percentage": 5,
    "amount": {
      "amount": 0.45,
      "currency": "EUR"
    }
  },
  "payout": {
    "amount": {
      "amount": 12.05,
      "currency": "EUR"
    },
    "eligibleAt": "2026-06-21T09:12:00.000Z",
    "paidOutAt": null
  },
  "buyer": {
    "id": "665f3a2b1c8d4e9f7a6b5c4d",
    "username": "north_arena_tcg",
    "avatarUrl": "https://images.cardnexus.com/avatars/north_arena_tcg.png",
    "country": "GB",
    "type": "individual",
    "rating": {
      "average": 4.9,
      "count": 51
    },
    "reliability": null
  },
  "shippingAddress": {
    "recipientName": "Marie Dubois",
    "line1": "14 Rue des Lilas",
    "line2": null,
    "city": "Lyon",
    "state": null,
    "postalCode": "69003",
    "countryCode": "FR",
    "phone": null
  },
  "metadata": {
    "fulfillment_stage": "packed",
    "internal_order_ref": "SO-10432"
  }
}