Return/refund item via api

Is it possible to refund an item, e.g. all items or some items as part of an order via the api. It seems you can do this via the dashboard, but the refunds api doesn’t seem to have an option for this?

If I do a full refund via the api, it creates a new return order with one returnLineItem containing "itemType": "CUSTOM_AMOUNT", rather than the original line items.

This is needed as some line items have different VAT amounts so we need to access which items have been returned.

:wave: I’m Square Dev AI, here to help answer your question!
Based on the information you’ve provided, the following documentation will help answer your question:

Additional Documentation

Refund Payments
Refunds API Overview
Pay or Refund Invoices

If this documentation helped you find a solution, please check the box indicating that this reply solves the problem.
Otherwise one of our Developer Advocates will provide additional assistance shortly.

Yes, it is possible to refund specific items in an order using the Square APIs. However, the Refunds API currently does not support itemized refunds. You can refund a specific line item in an order using the Square Point of Sale or other Square products, but not programmatically via the API.

For itemized refunds, the Orders API provides the return details in the ‘returns’ field of the Order object. This includes information such as the item type, catalog information of the refunded line item like catalog_object_id and variation_name.

For custom refunds, the ‘returns’ field has the item_type set to CUSTOM_AMOUNT and no other catalog item information.

When a refund is processed, Square also creates an Order object that provides the refund details. Both the itemized refund and custom refund create a return order (an Order object). The information in the ‘returns’ field varies for itemized and custom refunds.

However, if you need to refund a specific amount rather than a specific item, both the Square products and the Refunds API support custom refunds. In this case, a custom refund refers to refunding a specific order amount.

This answer was reviewed by @Bryan-Square.

This reply isn’t super clear. It sounds like it isn’t possible via the API and only via the dashboard, but I just wanted to make sure as this first sentence say it is possible. It looks like the only thing you can do via the API is a custom amount, and not return the items from the order?

1 Like

Sorry, about that. Itemized refunds aren’t currently available with API refunds. They’re only available in app and on the Dashboard. :slightly_smiling_face:

Hi Bryan, thanks for confirming! It would be useful if this was an option in the future, or even if you do a 100% refund, it defaults to returning all items.


We’re constantly working to improve our features based on feedback like this, so I’ll be sure to share your request to the API product team. :slightly_smiling_face: