Mark a sale shipped

​

Marks one of your sales shipped and registers its tracking number. The order moves to shipped, and the buyer is notified.

The order must be awaiting dispatch (pending_shipment) or have an open cancellation request (cancellation_requested) — you can still ship within the cancellation-request window. Any other status returns 409 INVALID_STATUS.

The response carries a tracking link under shipping. The carrier is detected automatically from the tracking number and appears on the sale once detection completes. A tracking number that is rejected as invalid returns 422 TRACKING_REGISTRATION_FAILED.

Pass metadata to stamp your own key/value pairs in the same call, merged the same way PATCH /v1/sales/{orderNumber}/metadata merges them. The two either both apply or neither does: a tracking number rejected as invalid leaves the sale's metadata unchanged, and metadata that would take the sale past its key limit returns 422 METADATA_LIMIT_EXCEEDED without shipping the order.

CardNexus Shield shipping insurance cannot be opted into through the API — sales shipped here are uninsured. Use the web or mobile app to insure a shipment.

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
  • trackingNumber
    Type: string
    min length:  
    5
    max length:  
    50    Pattern: ^[a-zA-Z0-9_-]+$
    required

    The parcel's tracking number — 5 to 50 characters: letters, digits, -, _. The carrier is detected automatically from the number.

  • metadata
    Type: object

    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
  • application/json
Request Example for post/sales/{orderNumber}/mark-shipped
curl 'https://public-api.cardnexus.com/v1/sales/{orderNumber}/mark-shipped' \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "trackingNumber": "",
  "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
}

Sale marked shipped.