API reference / Finance API / Get Refunds

Get Refunds

Required headers: X-App-Key X-App-Secret X-Shop-Id

Returns one row per day of refunds for the shop in the X-Shop-Id header, using the same P&L refund-cost breakdown as the Kixmon dashboard. Each row carries the day’s total refund cost and its details breakdown. Refund amounts are returned as negative numbers. startDate and endDate are required and filter by statement date.

For how the headers work, refer to Authentication.

Version v1API Testing Tool

GEThttps://api.kixmon.io/api/v1/refunds

Request

Properties	Type	Description
`X-App-Key`Required	string	App key created when REST APIs are enabled in Settings. Example: `km_your_app_key`.
`X-App-Secret`Required	string	App secret created when REST APIs are enabled in Settings. Store it on your server only — never send it from a browser or mobile app.
`X-Shop-Id`Required	string	The shop to query. Get this id from Get Shops.

Query

Properties	Type	Description
`startDate`Required	integer	Earliest statement date, Unix seconds. Maximum range is 366 days. Example: `1756598400`.
`endDate`Required	integer	Latest statement date, Unix seconds. Maximum range is 366 days. Example: `1756684799`.
`sort`Optional	string	`ASC` or `DESC`. Defaults to `DESC` when omitted. Sorted by date.
`page`Optional	integer	Page number. Defaults to 1.
`limit`Optional	integer	Results per page. Defaults to 10, maximum 100.

Dates are Unix timestamps in seconds. The range between startDate and endDate can be at most 366 days.

Example

curl 'https://api.kixmon.io/api/v1/refunds?startDate=1756598400&endDate=1756684799&page=1&limit=10' \
  -H "X-App-Key: $KIXMON_APP_KEY" \
  -H "X-App-Secret: $KIXMON_APP_SECRET" \
  -H "X-Shop-Id: $KIXMON_SHOP_ID"

const res = await fetch("https://api.kixmon.io/api/v1/refunds?startDate=1756598400&endDate=1756684799&page=1&limit=10", {
  headers: {
    "X-App-Key": process.env.KIXMON_APP_KEY,
    "X-App-Secret": process.env.KIXMON_APP_SECRET,
    "X-Shop-Id": process.env.KIXMON_SHOP_ID,
  },
});
const data = await res.json();

import os, requests

resp = requests.get(
    "https://api.kixmon.io/api/v1/refunds",
    headers={
        "X-App-Key": os.environ["KIXMON_APP_KEY"],
        "X-App-Secret": os.environ["KIXMON_APP_SECRET"],
        "X-Shop-Id": os.environ["KIXMON_SHOP_ID"],
    },
    params={"startDate": 1756598400, "endDate": 1756684799, "page": 1, "limit": 10},
    timeout=30,
)
resp.raise_for_status()
data = resp.json()

Response

Parameters

Properties	Type	Description
`success`	boolean	`true` when the request succeeds
`data`	object	Response payload
`items`	array	Refund days on this page
`date`	integer	Refund date, Unix seconds
`value`	number	Total refund cost for that day
`details`	object	Refund cost breakdown, same as P&L
`grossSalesRefund`	number	Gross sales refunded
`sellerDiscountRefund`	number	Seller discount refunded
`refundAdministrationFee`	number	Refund administration fee
`returnShippingFee`	number	Return shipping fee
`returnShippingLabelFee`	number	Return shipping label fee
`returnShippingFeePaidBuyer`	number	Return shipping fee paid by the buyer
`returnShippingFeeReimbursement`	number	Return shipping fee reimbursement
`pagination`	object	Pagination details
`page`	integer	Current page number
`limit`	integer	Results per page
`total`	integer	Total matching results
`totalPages`	integer	Total number of pages

Example

{
  "success": true,
  "data": {
    "items": [
      {
        "date": 1756598400,
        "value": -18.4,
        "details": {
          "grossSalesRefund": -16.2,
          "sellerDiscountRefund": 0,
          "refundAdministrationFee": -0.5,
          "returnShippingFee": -1.7,
          "returnShippingLabelFee": 0,
          "returnShippingFeePaidBuyer": 0,
          "returnShippingFeeReimbursement": 0
        }
      }
    ],
    "pagination": { "page": 1, "limit": 10, "total": 1, "totalPages": 1 }
  }
}

Error Code

HTTP status	Code	Description
`400`	`INVALID_REQUEST`	A header or query parameter is invalid.
`401`	`MISSING_CREDENTIALS`	`X-App-Key` or `X-App-Secret` is missing.
`401`	`INVALID_CREDENTIALS`	App key or app secret is wrong.
`403`	`FEATURE_UNAVAILABLE`	REST APIs are not on the current plan.
`404`	`SHOP_NOT_FOUND`	Shop not found or not available for this app key.
`429`	`RATE_LIMITED`	More than 60 requests were sent in one minute for this app key, or the IP limit was reached. Wait, then retry.
`500`	`INTERNAL_ERROR`	An unexpected error occurred. Retry later.

Get Refunds

Request

Header

Query

Example

Response

Parameters

Example

Error Code

Resources

Features

Get in Touch