Refund PayPal Payment
POST/api/paypal/captures/:captureId/refund
Refunds all or part of a PayPal payment through PayPal and records the refund on the sales order (a closed refund credit dated when PayPal made the refund). A full refund sets the order's payment status to refunded; a partial one to partially_refunded.
Authentication: Requires Bearer token and the Sales Orders > Refund permission.
Body:
amount(number, required, min 0.01) — no more than the payment's remaining refundable amount; whole amounts only for zero-decimal currencies (JPY, HUF, TWD).note(string, optional, max 255) — shown to the customer by PayPal.
Returns 404 when the payment is unknown, 409 when Connect with PayPal is unavailable for the account, and 422 when the amount is invalid or the PayPal account is disconnected or PayPal declines the refund. When PayPal is still processing the refund, data.status is PENDING and the refund is recorded once PayPal completes it.
This endpoint currently requires session authentication; Personal Access Token scope support is in progress.
Request
Responses
- 200
- 401
- 403
- 404
- 422
- 429
OK
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Not Found
Response Headers
Unprocessable Content
Response Headers
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.