Trigger an offline refund via API

I would like to know if anyone knows if there’s an option to trigger an offline refund via the API
The idea is I wanna use a 3rd party system to refund (instantly: Apace Refunds) and mark the transaction as refunded, but it should not trigger the VTEX refund (Shopify and BigCommerce have this option)

Thanks so much for nay help

1 Like

I’m not sure, but I can find out. Could you further describe the business case in which this would apply?

  • When would that happen in the real world? Could you give me an example?

  • Would the refund be paid in the same payment method used for the order? Or is this closer to a “cashback” in a separate system?

  • When you say “mark the transaction as refunded”, what is the expected outcome? Is it for Customer Service to know that offline refund happened for an order?

Reading through the Apace Refunds website, I understand that the goal here is not necessarily to mark the transaction as refunded, but to make it visible in the order details that this refund happened.

Is this a reasonable interpretation?

@georgebrindeiro Yes exactly!
So for 2 reasons, we would like the order to be marked as refunded

  1. For the merchant to be able to track what was already refunded and what not
  2. For the reports (in VTEX) to include the refunded orders (e.g. today was a total of $1000 in orders and 1 order was refunded offline (cash or via 3rd party: Apace) in the amount of $100 the reports would show $900 in total revenue for today, and again Shopify and BigCommerce have this option, I could only think that your amazing system should have some kind of this solution)

Thanks so much for your amazing help

I’m still looking for more information internally on how to best achieve these two goals, but here’s my response so far:

  1. I would recommend using the Create Note endpoint in VTEX Do API to add a note in the Annotations section of the Order Details page, like so:

    Screen Shot 2023-02-03 at 13.44.54

    Which would be done through a request like this:

curl --location --request POST 'https://{{accountName}}{{orderId}}' \
--header 'X-VTEX-API-AppKey: {{X-VTEX-API-AppKey}}' \
--header 'X-VTEX-API-AppToken: {{X-VTEX-API-AppToken}}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \

--data-raw '{
    "target": {
        "id": {{orderId}},
        "type": "order",
        "url": "https://{{accountName}}{{orderId}}/"
    "domain": "oms",
    "description": "$100 refunded via Apace Refunds"
  1. For refunds to show up in the orders, I’m pretty sure they need to go through our Payments Gateway. We do allow cash and promissory notes as Payment Methods, but I’m not sure we allow refunds to payment methods not used in the order itself. Still need to confirm that bit.

Could you point me towards the documentation for how to do it in the other ecommerce platforms you mentioned, so I can show it to our team?

@georgebrindeiro thanks so much for your amazing support
See below Shopify and BigCommerce reference for offline refund


In the refund object, we need to put a transaction object, and in the transaction object they have the option to add source: 'external'

Unfortunately I just confirmed that it is not possible to trigger an offline refund via API that affects the orders/transactions reports.

The alternative approach I would take to allow merchants to view refund reports would be to create a refunds Data Entity in Master Data where each Document is a refund made to an order. You would have the orderId, the value, datetime and other relevant information.

I would then create an Admin app that would then present the data in a way that would allow merchants to filter, search and check out the refund details.

You can find several app examples to draw inspiration from at VTEX Apps · GitHub

Hope this helps!

This topic was automatically closed 24 hours after the last reply. New replies are no longer allowed.