Refund part of a sale

​

Refunds part of one of your sales to the buyer. The refund is issued immediately and cannot be undone. The buyer is notified of the refund.

The refund is taken from the order payment CardNexus holds, so it lowers your payout for this sale. Nothing is debited from your account.

If the buyer used a CardNexus coupon on the order, the refund is split in the same proportion as their payment: part goes back to their payment method and the rest comes off their coupon. The buyer is told how much of each.

amount is in your selling currency — the sale's currency. You can refund a sale more than once, but all refunds on a sale together must stay below the sale's total (items plus the shipping you charged). An amount above what you can still refund returns 409 AMOUNT_TOO_HIGH, with the most you can still refund in maxAllowed. To refund the buyer in full, cancel the sale with POST /v1/sales/{orderNumber}/cancel while it is awaiting dispatch (pending_shipment).

The order must be pending_shipment, cancellation_requested, shipped, or delivered. Any other status returns 409 INVALID_STATUS.

While another refund or payout on the sale is being processed, the request returns 409 REFUND_IN_PROGRESS. Read the sale with GET /v1/sales/{orderNumber} before you retry: refunded is the total refunded so far.

Returns the updated sale, in the same shape as GET /v1/sales/{orderNumber}. Its refunded includes this refund.

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
  • amount
    Type: number
    greater than:  
    0
    required

    How much to refund, as a decimal in your selling currency — the sale's currency (e.g. 2.50 for €2.50). At most 2 decimal places.

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}/refunds
curl 'https://public-api.cardnexus.com/v1/sales/{orderNumber}/refunds' \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "amount": 2.5
}'

{
  "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,
  "shippingService": "tracked",
  "untrackedCloseAt": 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"
  },
  "shippingManagedByCardNexus": false,
  "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
  },
  "refunded": {
    "amount": 0,
    "currency": "EUR"
  },
  "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",
    "type": "parcel",
    "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
}

Refund issued.