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.

POST /v1/refund

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
Shopify Stores Need Nothing

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

Secret Key Required

/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 orderId that differs from the purchase. The refund must use the same orderId you sent to /v1/transaction.
  • A new refundId on every retry. Reuse the same one: a repeated refundId within 30 days is ignored, a new one is counted again.
  • Calling it from the browser. /v1/refund accepts only the Secret Key; a Public Key request is answered 401.
  • 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 refundId is counted once, however often it arrives.
Revenue and Ad Platforms Stay Unchanged

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.