Learn about migrating your application from the V1 Refunds API to the V2 Refunds API.
The following information helps you migrate from the Connect V1 Refunds API to the correct Square API counterparts. For general guidance about the differences between Connect V1 and Square APIs, see General Guidance.
Code relying on the following V1 Refunds API endpoints must be updated to avoid breaking when the V1 Refunds API reaches retirement:
- V1
CreateRefund - V1
ListRefunds
- Deprecation: 2021-05-13
- Retirement: TBD
If you need help migrating to the Square API or need more time to complete your migration, contact Developer Support, join our Discord community, or reach out to your Square account manager.
The CreateRefund endpoint is replaced by the Square RefundPayment endpoint. The following sections provide mapping information about the request fields, path parameters, and response fields.
| V1 CreateRefund request field | Square RefundPayment request field |
|---|---|
payment_id | payment_id |
type | N/A |
reason | reason |
refunded_money | amount_money |
refunded_money.amount | amount_money.amount |
refunded_money.currency_code | amount_money.currency |
refunded_idempotency_key | idempotency_key |
Note the following:
- N/A indicates that the field isn't used in the Square endpoint.
The V1 CreateRefund endpoint returns refund information as a set of fields in the response body, whereas the Square RefundPayment creates two objects: PaymentRefund and Order. The PaymentRefund object provides the ID of the created Order object. The following table shows the field mappings.
| V1 CreateRefund response field | Map to Square PaymentRefund Object field | Map to Square Order Object field |
|---|---|---|
type | N/A | |
reason | reason | |
refunded_money | amount_money | |
refunded_money.processing_money | processing_fee | |
created_at | created_at | |
processed_at | N/A | |
payment_id | payment_id | |
merchant_id | location_id | |
refunded_tax_money | return_amounts.tax_money | |
refunded_additive_tax_money | No direct field mapping. Instead, manually aggregate across the objects in returns.return_taxes. | |
refunded_additive_tax | returns.return_taxes | |
refunded_inclusive_tax_money | No direct field mapping. Instead, manually aggregate across the objects in returns.return_taxes. | |
refunded_inclusive_tax | returns.return_taxes | |
refunded_tip_money | return_amounts.tip_money | |
refunded_discount_money | return_amounts.discount_money | |
refunded_surcharge_money | return_amounts.service_charge_money | |
refunded_surcharges | returns.return_service_charges |
Note that a merchant can have one or more locations. Therefore, in this context, a location_id can serve the same purpose as the merchant_id.
The v1 ListRefunds endpoint is replaced by the Square ListPaymentRefunds endpoint. The following sections provide mapping information about the request fields (path parameters and query parameters) and the response fields.
| V1 ListRefunds path parameters | Square ListPaymentRefunds path parameters |
|---|---|
location_id | Not available as a path parameter, but you can specify it as a location_id query parameter. |
| V1 ListRefunds query parameters | Square ListPaymentRefunds query parameters |
|---|---|
order | sort_order |
begin_time | begin_time |
end_time | end_time |
limit | limit |
batch_token | cursor |
The V1 ListRefunds endpoint returns payment information as an array of V1Refund objects in the response body, whereas the Square ListRefunds endpoint returns an array of Square PaymentRefund objects. This PaymentRefund object provides an order_id, if available, which you can use to retrieve the Order object.
| V1 ListRefunds response field | Mapping to Square PaymentRefund or Order object field |
|---|---|
items | refunds |
items.created_at | PaymentRefund.created_at |
items.is_exchange | You can derive if the refund is related to an exchange by verifying the sum of the line_items.total_money with the sum of returns.return_amounts in the Order object. |
items.merchant_id | PaymentRefund.location_id |
items.processed_at | N/A. This field isn't available. |
items.reason | PaymentRefund.reason |
items.refunded_additive_tax | No direct field mapping. Instead, you aggregate manually across the objects in Order.returns.return_taxes where return_taxes.type is ADDITIVE. |
items.refunded_additive_tax_money | No direct field mapping. Instead, you aggregate manually across the objects in Order.returns.return_taxes where return_taxes.type is ADDITIVE. |
items.refunded_discount_money | Order.returns.return_amounts.tax_money |
items.refunded_inclusive_tax | No direct field mapping. Instead, you aggregate manually across the objects in Order.returns.return_taxes where return_taxes.type is INCLUSIVE. |
items.refunded_inclusive_tax_money | No direct field mapping. Instead, you aggregate manually across the objects in Order.returns.return_taxes where return_taxes.type is INCLUSIVE. |
items.refunded_money | PaymentRefund.amount_money |
items.refunded_processing_fee_money | PaymentRefund.processing_fee.amount_money |
items.refunded_surcharge_money | Order.returns.return_amounts.service_charge_money |
items.refunded_surcharges | Order.returns.return_service_charges |
items.refunded_tax_money | Order.returns.return_amounts.tax_money |
items.refunded_tip_money | Order.returns.return_amounts.tip_money |
items.type | You can determine whether the refund is full or partial based on the refund amount (PaymentRefund.amount_money) relative to the original order (Order.total_money). |