Learn about migrating your application from the V1 Refunds API to the V2 Refunds API.
Connect V1 Migration

Migrate from the Connect V1 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 Slack, 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 fieldSquare RefundPayment request field
payment_idpayment_id
typeN/A
reasonreason
refunded_moneyamount_money
refunded_money.amountamount_money.amount
refunded_money.currency_codeamount_money.currency
refunded_idempotency_keyidempotency_key

Note the following:

  • N/A indicates that the field is not 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 fieldMap to Square PaymentRefund Object fieldMap to Square Order Object field
typeN/A
reasonreason
refunded_moneyamount_money
refunded_money.processing_moneyprocessing_fee
created_atcreated_at
processed_atN/A
payment_idpayment_id
merchant_idlocation_id
`refunded_tax_moneyreturn_amounts.tax_money`
refunded_additive_tax_moneyNo direct field mapping. Instead, you aggregate manually across the objects in returns.return_taxes.
refunded_additive_taxreturns.return_taxes
refunded_inclusive_tax_moneyNo direct field mapping. Instead, you aggregate manually across the objects in returns.return_taxes.
refunded_inclusive_taxreturns.return_taxes
refunded_tip_moneyreturn_amounts.tip_money
refunded_discount_moneyreturn_amounts.discount_money
refunded_surcharge_moneyreturn_amounts.service_charge_money
refunded_surchargesreturns.return_service_charges

Note that a merchant can have one or more locations. Therefore, in this context a location_id can server 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 also the response fields.

V1 ListRefunds path parametersSquare ListPaymentRefunds path parameters
location_idNot available as a path parameter, but you can specify it as a location_id query parameter.

V1 ListRefunds query parametersSquare ListPaymentRefunds query parameters
ordersort_order
begin_timebegin_time
end_timeend_time
limitlimit
batch_tokencursor

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 fieldMapping to Square PaymentRefund or Order object field
itemsrefunds
items.created_atPaymentRefund.created_at
items.is_exchangeYou 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_idPaymentRefund.location_id
items.processed_atN/A. This field is not available.
items.reasonPaymentRefund.reason
items.refunded_additive_taxNo 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_moneyNo direct field mapping. Instead, you aggregate manually across the objects in Order.returns.return_taxes where return_taxes.type is ADDITIVE
items.refunded_discount_moneyOrder.returns.return_amounts.tax_money
items.refunded_inclusive_taxNo 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_moneyNo direct field mapping. Instead, you aggregate manually across the objects in Order.returns.return_taxes where return_taxes.type is INCLUSIVE
items.refunded_moneyPaymentRefund.amount_money
items.refunded_processing_fee_moneyPaymentRefund.processing_fee.amount_money
items.refunded_surcharge_moneyOrder.returns.return_amounts.service_charge_money
items.refunded_surchargesOrder.returns.return_service_charges
items.refunded_tax_moneyOrder.returns.return_amounts.tax_money
items.refunded_tip_moneyOrder.returns.return_amounts.tip_money
items.typeYou can determine if refund is full or partial based on refund amount (PaymentRefund.amount_money) relative to the original order (Order.total_money).

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.