Update a sale's metadata

​

Writes your own key/value pairs onto one of your sales. Use it to carry a reference from your own system, or a fulfillment state finer than the order statuses CardNexus tracks.

The write merges rather than replaces. Keys you send are set, keys you send as null are removed, and keys you leave out keep their value — so two systems can each own their keys on the same sale without overwriting each other. An empty string is a value, not a removal; sending {} changes nothing.

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 once the write is applied; a write that would go past that stores nothing and returns 422 METADATA_LIMIT_EXCEEDED.

Metadata can be written in any status, including on completed and cancelled sales. It is yours alone — the buyer never sees it, and it never appears on their purchase.

Filter on it with GET /v1/sales?metadata[key]=value, and read it back under metadata on every sales response.

Returns the updated sale, in the same shape as GET /v1/sales/{orderNumber}.

Send an Idempotency-Key header to make retries safe: the same key returns the same response for 24 hours.

Requires the sales:write scope.

Path Parameters
  • orderNumber
    Type: string
    min length:  
    1
    required

    The order reference, e.g. OR-ASNBC-1. Path parameter — not a query string.

Body
required
application/json
  • metadata
    Type: object
    required

    Metadata to write. Keys you send are set, keys you send as null are removed, and keys you leave out keep their current value. An empty string is a value, not a removal. Send {} to change nothing. 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 once the write is applied.

Responses
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for patch/sales/{orderNumber}/metadata
curl 'https://public-api.cardnexus.com/v1/sales/{orderNumber}/metadata' \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "metadata": {
    "fulfillment_stage": "packed",
    "picked_by": null
  }
}'

{
  "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"
  },
  "shipping": {
    "trackingNumber": "6A18432197431",
    "carrier": "Colissimo",
    "trackingUrl": "https://www.laposte.fr/outils/suivre-vos-envois?code=6A18432197431",
    "status": "in_transit",
    "shippedAt": "2026-06-14T09:12:00.000Z",
    "deliveredAt": null,
    "history": null
  },
  "cancellation": null
}

Metadata updated.