# Record a refund of a payment

```http
PUT https://secure.yoprint.com/v2/api/store/{team_slug}/v2/sales_order/{hash_id}/payment/{id}/refund
```

- API version: v2
- Operation ID: `v2_public_sales_order_manual_payment_refund`
- Section: Invoices and payments › [Payments](https://developer.yoprint.com/reference/payments.md)
- Web page: https://developer.yoprint.com/reference/payments/v2-sales-order-manual-payment-refund/
- Authentication: `Authorization: Bearer YOUR_API_KEY`

Records that you gave back some or all of a payment outside YoPrint. No money moves. For a card payment, use Refund a card payment through the gateway instead: this operation only records a refund and does not return money. `{id}` is the payment's `id`.

Send a whole number of thousandths: `12500` is 12.50. See [Money and quantities](/concepts/money-and-quantities/). The refund uses the payment's method. The answer is the refund: `subtype` `REFUND`, `direction` `DECREASE`, a **negative** `amount` (25.00 is `-25000`), `refundable_amount` 0, and the payment's `id` in `related_transaction`. `{hash_id}` is the order's `id` (for example `V4keXwwxMQyXw7`); the `ord_` unique key is not accepted here.

## Permission

Any member of the team. The order must be published.

## Business rules

- The refund can't be more than the payment's amount minus its refunds and minus the customer credit issued from it that the customer has already spent: "Refund Amount greater than what payment can be refunded". Shopify orders skip this check.
- Only published orders: "Payment Action Not Allowed - due to order internal state".
- `{id}` must be a payment: a refund or a credit move gives HTTP 500, and credit linked to a Customer Portal payment gives 422 `customer_payment_parent_refund_required` ("Refund this credit through its original customer payment."). The sign of `amount` is ignored and 0 is accepted. An `amount` that is not a whole number is refused with 422 `validation_failed`: `error.fields.amount` says "The amount must be a whole number of thousandths of the currency unit, such as 12500 for 12.50.".
- A payment synced from an integration (Shopify) is refused: "Cannot refund external object from API."

## Side effects

- Updates the order's balance, invoices and customer totals, and sends the `payment.refund_issued` webhook.
- The refunded money comes first from the payment's money not allocated to invoices, then from customer credit issued from this payment that is still unspent (which lowers the customer's credit, and adds an `ORDER_CREDIT_RECOVERY` record to the order), then from its invoices, newest first.
- On a Customer Portal payment, its card surcharge on the invoice is reduced to match.

## Path parameters

- `team_slug` (string, required): Your team slug, shown as Team ID next to your API key in Profile. Example `your-team`.
- `hash_id` (string, required): The sales order's or quote's `id` (a hash id). The `ord_` unique key and the order number do not work here. Example `V4keXwwxMQyXw7`.
- `id` (string, required): The payment's `id` (a hash id). Example `hAwWd7vPrqjuHD`.

## Request body

Content type `application/json`, required.

Fields:

- `amount` (integer, required): The refund as a whole number of thousandths of the currency: `12500` is 12.50. A number with decimals is refused with 422. The sign is ignored and the answer shows the refund as negative.
- `created_at` (string (date), optional)
- `date` (string (date), optional): When it was refunded. Send `date` or `created_at`.
- `reference_description` (string, optional)
- `reference_id` (string, optional)

### Example request

```bash
curl -X PUT 'https://secure.yoprint.com/v2/api/store/your-team/v2/sales_order/V4keXwwxMQyXw7/payment/hAwWd7vPrqjuHD/refund' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: application/json' \
  -H 'X-Yoprint-Decimal-Format: exact-v1' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 25000,
    "date": "2026-11-05",
    "reference_description": "Returned two shirts"
  }'
```

## Response

`200` Successful response.

Fields:

- `data` (object, required): A payment, refund or credit move. Customer Portal rows (`action` `CUSTOMER_CHECKOUT`, and credit applied from a Customer Portal payment) also carry `customer_payment_checkout_id`, `funding_transaction_id`, `customer_payment_application_id`, `customer_payment_source_kind`, `is_external_cash_movement` and `currency_iso`.
  - `amount` (integer | number | string | null, required): Signed: negative for `DECREASE` (a 25.00 refund is `-25000`). Thousandths, an older encoding: `12500` is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (`1234.5` is 1.2345), or as a string (`"1234.5"`) when you send `X-Yoprint-Decimal-Format: exact-v1`. See [Money and quantities](/concepts/money-and-quantities/).
  - `id` (string, required)
  - `action` (string | null, optional): `ORDER_PAYMENT`, `ORDER_REFUND`, `ORDER_CREDIT_DEPOSIT` (paid from customer credit), `ORDER_CREDIT_WITHDRAW` (moved to customer credit), `ORDER_CREDIT_RECOVERY`, `ORDER_CREDIT_RESTORED`, `CUSTOMER_CHECKOUT` (paid in the customer portal, and its refunds), `CUSTOMER_CHECKOUT_CHARGEBACK` (a lost dispute), or the gateway: `STRIPE`, `SQUARE`, `SQUARE_V2`, `PAYPAL`, `AUTHORIZE_NET`, `CHARGE_IT_PRO`. A `REFUND_REVERSAL` carries its refund's gateway.
  - `credit_source` (object | null, optional): Where a customer credit record came from. Always present; null on an order's records.
  - `credit_source_payment_id` (string | null, optional): `ORDER_CREDIT_RECOVERY` and `ORDER_CREDIT_RESTORED` only: the payment the credit was issued from.
  - `customer_id` (string | null, optional): Always null on an order's records.
  - `customer_payment_funding_id` (string | null, optional): Customer Portal payment rows and credit applied from one only: the customer payment it belongs to.
  - `customer_payment_sources` (array of objects, optional): Customer Portal rows only: the customer payments the money came from, each with `customer_payment_funding_id`, `funding_transaction_id`, `amount` (a decimal string) and `currency_iso`.
  - `date` (string (date-time) | null, optional): When it was recorded (the payment date you sent). ISO 8601 with offset, or null.
  - `delete_blocked_reason` (object | null, optional): Recorded payments (`ORDER_PAYMENT`) and card payments only: why Delete a payment or refund refuses it, or null when it can be deleted. `code` is `credit_issued_from_payment` (with `amount`, a decimal string) or `provider_payment_not_removable`; `message` is the refusal's text.
    - `amount` (string, optional)
    - `code` (string, optional)
    - `message` (string, optional)
  - `direction` (string, optional): `INCREASE` (payments, payments from customer credit, `REFUND_REVERSAL`, `ORDER_CREDIT_RECOVERY`) or `DECREASE` (refunds and lost disputes, moves to customer credit, card voids, `ORDER_CREDIT_RESTORED`).
  - `funding_payment_gateway` (string | null, optional): Customer Portal rows only: the provider (`STRIPE`, `PAYPAL`, `SQUARE_V2`, `AUTHORIZE_NET`, `CHARGE_IT_PRO`) or null.
  - `has_open_hold` (boolean, optional): List and Get only, on `STRIPE`, `PAYPAL` and `SQUARE_V2` card payments and Customer Portal payments: true while a dispute (or, for a Customer Portal payment, a review) is open.
  - `is_deletable` (boolean, optional): false for card payments, Customer Portal payments, credit moves, card refunds, payments part of which moved to customer credit (and their refunds), refunds recorded against card payments, and the records YoPrint adds itself.
  - `is_editable` (boolean, optional): true only for recorded payments (`ORDER_PAYMENT`).
  - `negative_credit_amount` (integer | number | string | null, optional): Card refunds only: credit issued from the payment that the customer had already spent and the refund took back anyway, leaving their credit negative (usually 0). Thousandths, an older encoding: `12500` is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (`1234.5` is 1.2345), or as a string (`"1234.5"`) when you send `X-Yoprint-Decimal-Format: exact-v1`. See [Money and quantities](/concepts/money-and-quantities/).
  - `order_id` (string | null, optional)
  - `payment_freeze_reason` (string | null, optional): List and Get only, on `STRIPE`, `PAYPAL` and `SQUARE_V2` card payments and direct Customer Portal payments: `chargeback_open` or `payment_under_review` while refunds and credit moves are refused, otherwise null.
  - `payment_gateway` (string | null, optional): The gateway (`STRIPE`, `SQUARE_V2` and so on) for card payments and refunds; for a Customer Portal payment its provider (null when unknown), and `CUSTOMER_CHECKOUT` or `CUSTOMER_CHECKOUT_CHARGEBACK` on its refunds and lost disputes; null otherwise.
  - `payment_gateway_source` (string | null, optional): Card payments and refunds only: Square v2's source type (for example `CARD`), otherwise null.
  - `payment_method_id` (string | null, optional): Refunds take their payment's; null for card payments and credit moves.
  - `payment_notices` (array of objects, optional): List and Get only, on the same payments as `has_open_hold`: one notice per open dispute.
    - Each item:
      - `amount` (object | null, optional): The disputed amount as a decimal pair with `dp` 3, or null when the payment covered several orders.
      - `code` (string, optional): `dispute_open` or `dispute_under_review`; on Customer Portal payments also `payment_needs_attention`.
      - `currency_iso` (string, optional)
      - `customer_payment_dispute_id` (string, optional)
      - `customer_payment_funding_id` (string | null, optional)
      - `deadline_at` (string | null, optional): When the response to the provider is due (ISO 8601), or null.
      - `next_action` (string, optional): For example `respond_to_provider` or `awaiting_provider`.
      - `provider` (string, optional)
      - `provider_status` (string, optional)
      - `stage` (string | null, optional)
  - `recovery_kind` (string | null, optional): `ORDER_CREDIT_RECOVERY` and `ORDER_CREDIT_RESTORED` only: null on an order's records.
  - `reference_description` (string | null, optional)
  - `reference_id` (string | null, optional)
  - `refundable_amount` (integer | number | string | null, optional): Payments only: the amount minus its refunds. Money moved to customer credit is not taken off here, though a refund can't include it. 0 for refunds, credit moves, payments from customer credit, and `CHARGE_IT_PRO` and `SQUARE` card payments. Thousandths, an older encoding: `12500` is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (`1234.5` is 1.2345), or as a string (`"1234.5"`) when you send `X-Yoprint-Decimal-Format: exact-v1`. See [Money and quantities](/concepts/money-and-quantities/).
  - `related_transaction` (string | null, optional): For a refund, the `id` of the payment it refunds; for `REFUND_REVERSAL`, the payment; for `ORDER_CREDIT_RECOVERY` and `ORDER_CREDIT_RESTORED`, the refund; null otherwise.
  - `remove_unavailable` (object | null, optional): Recorded payments only: `{ "reason": "credit_issued", "amount": <thousandths> }` when credit was issued from the payment, otherwise null.
  - `restores_transaction_id` (string | null, optional): `ORDER_CREDIT_RESTORED` only: the `ORDER_CREDIT_RECOVERY` record it gives back.
  - `reversal_transaction_id` (string | null, optional): Card refunds and `ORDER_CREDIT_RESTORED` only: the `REFUND_REVERSAL` record when the refund failed, or null.
  - `reverses_transaction_id` (string | null, optional): `REFUND_REVERSAL` only: the failed refund.
  - `subtype` (string, optional): `PAYMENT`, `REFUND` (also a lost dispute), `TRANSFER` (a customer credit move), `ORDER_PAYMENT_VOIDED_NEG_ADJ` (a voided card payment), `REFUND_REVERSAL` (a failed card refund given back to its payment), `ORDER_CREDIT_RECOVERY` (credit a refund took back) or `ORDER_CREDIT_RESTORED` (that credit given back when the refund failed).
  - `token` (string | null, optional): The gateway's charge token; null for recorded payments.
  - `type` (string, optional): `MANUAL` (recorded in YoPrint) or `SYSTEM` (card and Customer Portal payments and refunds, Shopify payments, adjustments).
  - `user_id` (string | null, optional): The team member who recorded it.
  - `voided` (boolean, optional)
- `status` (integer, required)
- `success` (boolean, required)

Example response:

```json
{
  "data": {
    "action": "ORDER_REFUND",
    "amount": -25000,
    "credit_source": null,
    "customer_id": null,
    "date": "2026-11-05T00:00:00+00:00",
    "direction": "DECREASE",
    "id": "t3FdSWWe9TLyAR",
    "is_deletable": true,
    "is_editable": false,
    "order_id": "V4keXwwxMQyXw7",
    "payment_gateway": null,
    "payment_method_id": "Kst6z3ULXLBrmN",
    "reference_description": "Returned two shirts",
    "reference_id": null,
    "refundable_amount": 0,
    "related_transaction": "hAwWd7vPrqjuHD",
    "subtype": "REFUND",
    "token": null,
    "type": "MANUAL",
    "user_id": "PydH0WtBhSeiNU",
    "voided": false
  },
  "status": 200,
  "success": true
}
```

## Errors

- `401` The API key is missing or wrong (`unauthenticated`).
- `403` You are not allowed to do this. `api_access_not_in_plan`: your team's plan doesn't include API access (Pro and above, with an active subscription or trial), so every request answers this until the team upgrades. When your role lacks the permission the operation needs, the body is only `{"message": "Insufficient Permission"}`. Other refusals use the error envelope, with `unauthorized` or `user_is_not_authorized`.
- `404` Not found. `page_not_found`: the team slug is unknown, you are not a member of the team, or an id in the path is not one of this team's. `code: null`, with a message that starts "No query results for": there is no record with that id.
- `422` The request was refused and changed nothing. `validation_failed` lists what to fix in `error.fields`; other codes name a business rule, explained in `error.message`. A few checks answer with only `{"message": "..."}`. An operation that calls another service (a payment provider, a carrier, an accounting app) can answer `connect_timeout` ("Please retry again") when that service does not answer in time: the change may or may not have happened there, so read the record back before you retry.
  - When: Too large an amount, an `amount` with decimals, no date, a draft order, a Shopify order deleted in Shopify, or credit linked to a Customer Portal payment (`customer_payment_parent_refund_required`). Fix: Refund at most the payment's amount minus its refunds and the credit already spent.
- `500` A business rule refused the request (see the operation's errors), or something failed inside YoPrint. Refusals use the error envelope with a code such as `action_not_allowed`; an unexpected failure answers `{"message": "Server Error"}`. Repeating a refusal gets the same answer; after an unexpected failure, read the record back before you retry a change.
  - When: `{id}` is a refund or a credit move, not a payment (`{"message": "Server Error"}`). Fix: Use the payment's `id`.

## Related

- [Refund a card payment through the gateway](https://developer.yoprint.com/reference/payments/v2-sales-order-payment-gateway-refund.md): `PUT /v2/api/store/{team_slug}/v2/sales_order/{hash_id}/payment_gateway_refund/{id}`
- [List the payments of a sales order](https://developer.yoprint.com/reference/payments/v2-sales-order-payment-index.md): `GET /v2/api/store/{team_slug}/v2/sales_order/{hash_id}/payment`