Refund Event
Report a refund or a cancellation of an order you already sent as a transaction. Refunds reduce profit and POAS (Profit on Ad Spend). They never change revenue, ROAS or anything AxiTrace sends to an ad platform.
When to Use This Event
- A customer returned some products and you refunded them
- You refunded part of an order as a goodwill gesture (an amount, no products)
- An order was cancelled after it had been paid
The AxiTrace Shopify app receives refunds and cancellations from Shopify on its own. Call this endpoint only from a custom store or your own backend.
Server-Side Only
/v1/refund accepts only your Secret Key (HTTP Basic auth, the key as the user
name and an empty password). A request with the Public Key is answered 401.
The JavaScript SDK cannot send refunds: your Public Key is visible in every page of your
store, and a refund changes your profit figures.
Example
curl -X POST https://stat.axitrace.com/v1/refund \
-u "sk_live_YOUR_SECRET_KEY:" \
-H "Content-Type: application/json" \
-d '{
"orderId": "ORD-2024-001234",
"refundId": "RF-2024-000077",
"refundedAt": "2026-10-02T10:00:00Z",
"amount": 99.99,
"currency": "USD",
"lines": [
{ "sku": "PROD-001", "quantity": 1, "amount": 99.99 }
]
}'
Response (also for a refund id you already sent, which is ignored):
{
"success": true,
"refundId": "RF-2024-000077",
"orderId": "ORD-2024-001234"
}
Fields
| Field | Required | Notes |
|---|---|---|
orderId |
Required | The orderId you sent with the purchase to /v1/transaction |
refundId |
Required | Your id of this refund, at most 191 characters. A refund id sent again within 30 days is ignored, so retries are safe. |
refundedAt |
Optional | RFC 3339 time of the refund; defaults to the time of the request |
amount |
Optional | Total refunded, gross of tax, in the order currency; must be >= 0 |
currency |
Optional | ISO 4217 code of the order currency, e.g. PLN. Required when amount or any lines[].amount is set. |
isCancellation |
Optional | true when the whole order was cancelled; every product of the order is reversed and lines and amount are not needed |
lines[] |
Optional | The refunded products. Each needs sku or externalId (the same values the purchase carried), quantity >= 0 and optionally amount (gross, >= 0). |
A refund needs at least one of amount, lines or
isCancellation: true; anything else is answered 400 with the field
that is missing.
Common Mistakes
- Sending an
orderIdthat differs from the purchase. The refund must use the sameorderIdyou sent to/v1/transaction. - A new
refundIdon every retry. Reuse the same one: a repeatedrefundIdwithin 30 days is ignored, a new one is counted again. - Calling it from the browser.
/v1/refundaccepts only the Secret Key; a Public Key request is answered401. - Sending refunds while profit tracking is off. They are accepted and discarded, and turning profit tracking on later does not bring them back.
See how refunds fit into profit and POAS reporting: profit tracking in AxiTrace.
How a Refund Changes Profit
- Refunded products reverse their share of the order's net revenue and their cost of goods, in proportion to the refunded quantity.
- An amount without products reverses that amount net of tax; the cost of goods stays, because the products were not returned.
- A cancellation reverses the net revenue and cost of goods of every product of the order.
- Shipping cost, payment fee and handling cost are never reversed: you paid them anyway.
- The order keeps its purchase date. A refund in October of a September order lowers September's profit.
- The same
refundIdis counted once, however often it arrives.
A refund is stored for profit reporting only. Revenue, ROAS, Orders & journeys and every conversion already sent to Google Ads, Meta, TikTok or any other platform stay as they are. Refunds are recorded only while profit tracking is on. A refund received while it is off is accepted and discarded, so turning profit tracking on later does not include refunds from before.