Work with refunds and credit memos using Magento API

This article is a short guide to choosing the correct Magento Refund API that would best match your needs.

Related documentation: Magento REST API documentation (Swagger).

salesRefundInvoice service

With this service, you may initiate and process a refund based on an Invoice ID, created using an online payment method. 

If you try to apply the service to an invoice created using an offline payment method, the system will throw a validation error.

The service allows you to:

• create a credit memo (complete or partial) for an invoice 
• add details about the refunded items to the order
• change status and state of an order according to performed actions
• notify a customer about the performed refund operation
• designate whether the returned items are returned to stock

Related documentation on DevDocs: The RefundInvoice service.

salesRefundOrder service

This service performs the same operations as the RefundInvoice service, but based on an Order ID. Use this service if the invoice was created using an offline payment method.

Related documentation on DevDocs: The RefundOrder service.

salesCreditmemoManagement service

The service also allows to initiate and process a refund but requires more information in a request — as compared with the RefundInvoice and RefundOrder services.

The Refund services are newer, more complex, and universal, and may be viewed as an improvement to the CreditmemoManagement service — providing more convenience working with refunds. Still, the CreditmemoManagement service is valid and functional.

salesCreditmemoRepository service

This service is only for persistence operations with refunds: it may add or update a refund, but does not process it in the Magento system.

The POST /V1/creditmemo method of this service allows to place a new credit memo or update an existing one, but will not process any refund operations with it. Sending a request with this method will not change the status of a credit memo and will not affect the refund amount; consequently, a new credit memo will not have any status and the refund will amount to zero.

Choose a correct method with the salesCreditmemo services

1. Create a new credit memo and process it: use the salesCreditmemoManagementV1 service (POST /V1/creditmemo/refund method)
2. Create and update credit memos without processing them: use the salesCreditmemoRepositoryV1 service (POST /V1/creditmemo method).

Note: for the correct refund shipment, these parameters are required:

• shipping_amount
• base_shipping_amount