Refunds
Refunds of orders: calculate first, then refund items and delivery; the money goes back by the payment methods, the goods go back to stock.
Refunds
Objects
Refund
idintegerrequiredID of the record, unique among records of its kind in the store.
order_idintegerrequiredID of the order.
pos_shift_idinteger or nullrequiredID of the register shift (/v1/pos-shifts) that made the refund; null — not refunded at a register.
kindstringrequiredreturn — goods are returned; adjustment — the amount is corrected without goods; overpayment — an overpayment is returned; tip — a tip is returned.
- Values:
returnadjustmentoverpaymenttip
statusstringrequiredpending — waiting for the provider or a manual payout; completed; failed; reversed — cancelled after it was completed.
- Values:
pendingcompletedfailedreversed
app_idinteger or nullrequiredThe app that made the refund (/v1/orders/{order}/refunds or an order cancellation), its id from /v1/me; null for a refund by the register, the staff, the customer or automation.
confirmablebooleanrequiredThe refund waits for confirmation that the money was paid back outside the system (POST /v1/refunds/{refund}/confirm).
currencystringrequiredCurrency of the amounts, an ISO 4217 code: the currency of the store.
amountintegerrequiredAmount of the refund: items and delivery.
shipping_amountintegerrequiredPart of amount that refunds the delivery.
tax_linesarray of object or nullrequiredTax of what was refunded by the classification of the products: the composition of the credit note of the refund, with the returned items except gift cards and the delivery; for a refund of an amount without items, the taxable part by the default tax class of the store. null when the store has no tax classes or nothing taxable was refunded (a gift card).
Fields · 6
regimestringrequiredWhich tax: vat — value added tax (IVA); income — income tax; turnover — gross receipts tax (Ingresos Brutos); municipal — a municipal levy; internal — excise; social — social security; other. Tax of a sale is vat: the tax class of a product classifies value added tax.
- Values:
vatincometurnovermunicipalinternalsocialother
kindstringrequiredtaxed — at the rate; exempt — exempt by law; untaxed — outside the scope of the tax. exempt and untaxed lines have rate_bps 0 and amount 0: the amount is in base.
- Values:
taxedexemptuntaxed
rate_bpsintegerrequiredRate in basis points: 2100 is 21 %.
baseintegerrequiredBase of the tax, without the tax. Prices include tax: base + amount is what the customer paid for this part.
amountintegerrequiredAmount of the tax. The tax of a sale is calculated per rate for the whole order, the base rounded to the nearest unit and the tax as the rest; items and delivery get shares of it, so their lines add up to the line of the order.
jurisdictionstring or nullrequiredProvince or municipality for taxes that need one (turnover, municipal); otherwise null.
exchanged_to_order_idinteger or nullrequiredThe order handed out in exchange; null for an ordinary refund.
itemsarray of objectrequiredReturned items.
Fields · 4
order_item_idintegerrequiredID of the item of the order (items in /v1/orders).
quantitystringrequiredQuantity, a decimal string in unit: pieces, or the whole measure of an item sold by weight or volume.
unitstring or nullrequiredUnit of quantity: pcs, g or ml; null when the variant no longer knows the unit of its measure.
- Values:
pcsgmlnull
amountintegerrequiredAmount refunded for the item.
transactionsarray of objectrequiredWhere the money went: transactions by the payments of the order.
Fields · 7
idintegerrequiredID of the transaction.
payment_idinteger or nullrequiredPayment of the order the money goes back by; null when there is no such payment, such as a refund to the balance.
methodstringrequiredPayment method of the transaction, the same values as method of a payment.
- Values:
cashmercadopagocryptobybittrc20balancemodopaywaymercadopago_qrmercadopago_pointmercadopago_transfergift_cardsubscriptiondepositexternalmanualoffseton_accountexchange_creditbonpuntoservice_package
targetstringrequiredWhere the money goes: card — back to the card through the provider; cash — in cash; balance — to the balance of the customer; gift_card — to a gift card; account — against the debt of the customer; manual — paid back by hand outside the system; exchange — to the order of an exchange; subscription — to a subscription; deposit — to a deposit.
- Values:
cardcashbalancegift_cardaccountmanualexchangesubscriptiondepositservice_package
amountintegerrequiredAmount of the transaction.
statusstringrequiredpending, completed, failed or reversed, as status of the refund.
- Values:
pendingcompletedfailedreversed
provider_refund_idstring or nullrequiredID of the refund at the payment provider, for reconciliation with its statement; null when there is no provider.
created_atstring (date-time)requiredWhen the record was created.
updated_atstring (date-time)requiredWhen the record last changed.
RefundCalculation
order_idintegerrequiredID of the order.
currencystringrequiredCurrency of the amounts, an ISO 4217 code: the currency of the store.
amountintegerrequiredAmount that will be refunded for the chosen items and delivery.
shipping_amountintegerrequiredPart of amount that refunds the delivery.
itemsarray of objectrequiredItems that will be returned.
Fields · 4
order_item_idintegerrequiredID of the item of the order (items in /v1/orders).
quantitystringrequiredQuantity, a decimal string in unit: pieces, or the whole measure of an item sold by weight or volume.
unitstring or nullrequiredUnit of quantity: pcs, g or ml; null when the variant no longer knows the unit of its measure.
- Values:
pcsgmlnull
amountintegerrequiredAmount refunded for the item.
transactionsarray of objectrequiredWhere the money will go: shares by the payments of the order, exactly as the refund will make them.
Fields · 4
payment_idinteger or nullrequiredPayment of the order the money goes back by; null when there is no such payment, such as a refund to the balance.
methodstring or nullrequiredPayment method of the share; null for a share without a payment.
- Values:
cashmercadopagocryptobybittrc20balancemodopaywaymercadopago_qrmercadopago_pointmercadopago_transfergift_cardsubscriptiondepositexternalmanualoffseton_accountexchange_creditbonpuntoservice_packagenull
targetstringrequiredWhere the money goes: card — back to the card through the provider; cash — in cash; balance — to the balance of the customer; gift_card — to a gift card; account — against the debt of the customer; manual — paid back by hand outside the system; exchange — to the order of an exchange; subscription — to a subscription; deposit — to a deposit.
- Values:
cardcashbalancegift_cardaccountmanualexchangesubscriptiondepositservice_package
amountintegerrequiredAmount of the transaction.
balance_availablebooleanrequiredA share of an irreversible method (a transfer, crypto, a manual method) can go to the balance of the customer instead — irreversible_to: balance in the refund: such a share is in the calculation, the customer has an account and the store uses balances.
refundableobjectrequiredWhat can still be refunded on the order: items with quantity left and the rest of the delivery. A cancelled refund does not use it up.
Fields · 2
itemsarray of objectrequiredItems with quantity left to refund.
Fields · 3
order_item_idintegerrequiredID of the item of the order (items in /v1/orders).
quantitystringrequiredQuantity left to refund, a decimal string in unit.
unitstring or nullrequiredUnit of quantity: pcs, g or ml; null when the variant no longer knows the unit of its measure.
- Values:
pcsgmlnull
shipping_amountintegerrequiredDelivery amount left to refund.
Endpoints
List order refunds changed since a given time: items and payment transactions
get/refunds
Scope: refunds:read
Parameters
Query
limitintegerPage size: up to 250 records; 50 by default.
- Minimum:
- 1
- Maximum:
- 250
cursorstringOpaque cursor: next_cursor of the previous page, or sync_cursor of the last page saved by the previous sync. The list goes in commit order, so the sync cursor later returns only what changed after it.
- Max length:
- 4096
updated_sincestring (date-time)Only records changed after this moment, ISO 8601 with a time zone. A filter for the first sync; continue with the cursor.
- Pattern:
^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,6})?(Z|[+-]\d{2}:\d{2})$
include_deletedbooleantrue — also return deleted records: archived ones with deleted_at set, and records erased from the database as tombstones {id, deleted_at} in the continuation by the sync cursor. Turn it on for a sync.
order_idintegerOnly records of this order.
- Minimum:
- 1
pos_shift_idintegerOnly records taken by this register shift.
- Minimum:
- 1
Responses
200Success
application/json
Records of the page.
deletedarray of objectrequiredRecords erased from the database since the cursor, as tombstones: only with include_deleted=true in the continuation by the sync cursor.
Fields · 2
idintegerrequiredID of the erased record.
deleted_atstring (date-time)requiredWhen the record was erased.
next_cursorstring or nullrequiredCursor of the next page; null on the last page.
has_morebooleanrequiredtrue when there is a next page.
sync_cursorstring or nullrequiredOn the last page — the cursor to continue from later: it returns only what changed after this page. null on other pages.
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
410The sync cursor is older than the deletion retention period or was issued before the database was restored
application/problem+json
Returns Problem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl "https://api.saleya.app/v1/refunds" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"data": [
{
"id": 0,
"order_id": 0,
"pos_shift_id": 0,
"kind": "return",
"status": "pending",
"app_id": 0,
"confirmable": true,
"currency": "string",
"amount": 0,
"shipping_amount": 0,
"tax_lines": [
{
"regime": "vat",
"kind": "taxed",
"rate_bps": 0,
"base": 0,
"amount": 0,
"jurisdiction": "string"
}
],
"exchanged_to_order_id": 0,
"items": [
{
"order_item_id": 0,
"quantity": "string",
"unit": "pcs",
"amount": 0
}
],
"transactions": [
{
"id": 0,
"payment_id": 0,
"method": "cash",
"target": "card",
"amount": 0,
"status": "pending",
"provider_refund_id": "string"
}
],
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}
],
"deleted": [
{
"id": 0,
"deleted_at": "2026-01-15T12:00:00Z"
}
],
"next_cursor": "string",
"has_more": true,
"sync_cursor": "string"
}Get an order refund
get/refunds/{refund}
Scope: refunds:read
Parameters
Path
refundintegerrequiredID of the refund.
Responses
200Success
application/json
Returns Refund
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
404The object does not exist or is not available to the app
application/problem+json
Returns Problem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl "https://api.saleya.app/v1/refunds/{refund}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"id": 0,
"order_id": 0,
"pos_shift_id": 0,
"kind": "return",
"status": "pending",
"app_id": 0,
"confirmable": true,
"currency": "string",
"amount": 0,
"shipping_amount": 0,
"tax_lines": [
{
"regime": "vat",
"kind": "taxed",
"rate_bps": 0,
"base": 0,
"amount": 0,
"jurisdiction": "string"
}
],
"exchanged_to_order_id": 0,
"items": [
{
"order_item_id": 0,
"quantity": "string",
"unit": "pcs",
"amount": 0
}
],
"transactions": [
{
"id": 0,
"payment_id": 0,
"method": "cash",
"target": "card",
"amount": 0,
"status": "pending",
"provider_refund_id": "string"
}
],
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}Calculate an order refund and what is left to refund, without writing anything
post/orders/{order}/refunds/calculate
Scope: refunds:write
Parameters
Path
orderintegerrequiredID of the order.
Header
Idempotency-KeystringUnique key of the attempt, for example a UUID. A retry with the same key and body gets the saved response instead of a second write. Keys live 24 hours.
- Min length:
- 1
- Max length:
- 255
- Example:
8e03978e-40d5-43e8-bc93-6894a57f9324
Request body application/json
itemsarray of objectrequiredReturned items.
- Max items:
- 200
- No repeats
Fields · 2
order_item_idintegerrequiredID of the item of the order (items in /v1/orders).
- Minimum:
- 1
quantitystringrequiredQuantity, a decimal string in unit: pieces, or the whole measure of an item sold by weight or volume.
- Max length:
- 32
shipping_amountintegerPart of amount that refunds the delivery.
- Minimum:
- 0
- Maximum:
- 100000000000000
irreversible_tostringWhere the share of an irreversible method (a transfer, crypto, a manual method) goes: manual — the store pays it back by hand and confirms it (POST /v1/refunds/{refund}/confirm); balance — to the balance of the customer (balance_available of the calculation).
- Values:
manualbalance
Responses
200Success
Headers
Idempotent-Replayedstringtrue when this is the saved response of an earlier request with the same Idempotency-Key.
- Values:
true
application/json
Returns RefundCalculation
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
404The object does not exist or is not available to the app
application/problem+json
Returns Problem
409A request with the same idempotency key is in progress, the data changed after it was read, the external ID belongs to another record, the plan or webhook endpoint limit is reached, or the change needs consent to its consequences
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns ConflictProblem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
- 409
idempotency_key_in_useA request with this key is in progress - 409
refund_refusedThe order cannot be refunded - 422
idempotency_key_reusedIdempotency key is already used - 422
invalid_idempotency_keyIdempotency key is invalid
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl -X POST "https://api.saleya.app/v1/orders/{order}/refunds/calculate" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H "Content-Type: application/json" \
-d @body.json{
"items": [
{
"order_item_id": 1,
"quantity": "string"
}
],
"shipping_amount": 0,
"irreversible_to": "manual"
}{
"order_id": 0,
"currency": "string",
"amount": 0,
"shipping_amount": 0,
"items": [
{
"order_item_id": 0,
"quantity": "string",
"unit": "pcs",
"amount": 0
}
],
"transactions": [
{
"payment_id": 0,
"method": "cash",
"target": "card",
"amount": 0
}
],
"balance_available": true,
"refundable": {
"items": [
{
"order_item_id": 0,
"quantity": "string",
"unit": "pcs"
}
],
"shipping_amount": 0
}
}Refund order items and delivery: money goes back by the payment methods, goods go back to stock
post/orders/{order}/refunds
Scope: refunds:write
Parameters
Path
orderintegerrequiredID of the order.
Header
Idempotency-KeystringUnique key of the attempt, for example a UUID. A retry with the same key and body gets the saved response instead of a second write. Keys live 24 hours.
- Min length:
- 1
- Max length:
- 255
- Example:
8e03978e-40d5-43e8-bc93-6894a57f9324
Request body application/json
itemsarray of objectrequiredReturned items.
- Max items:
- 200
- No repeats
Fields · 2
order_item_idintegerrequiredID of the item of the order (items in /v1/orders).
- Minimum:
- 1
quantitystringrequiredQuantity, a decimal string in unit: pieces, or the whole measure of an item sold by weight or volume.
- Max length:
- 32
shipping_amountintegerPart of amount that refunds the delivery.
- Minimum:
- 0
- Maximum:
- 100000000000000
irreversible_tostringWhere the share of an irreversible method (a transfer, crypto, a manual method) goes: manual — the store pays it back by hand and confirms it (POST /v1/refunds/{refund}/confirm); balance — to the balance of the customer (balance_available of the calculation).
- Values:
manualbalance
expected_amountintegerrequiredThe amount from the calculation (/v1/orders/{order}/refunds/calculate) you confirm. A spread discount, earlier refunds or a change of the order can change it after reading; a refund for another amount is not made.
- Minimum:
- 0
- Maximum:
- 100000000000000
Responses
201Created
Headers
Idempotent-Replayedstringtrue when this is the saved response of an earlier request with the same Idempotency-Key.
- Values:
true
application/json
Returns Refund
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
404The object does not exist or is not available to the app
application/problem+json
Returns Problem
409A request with the same idempotency key is in progress, the data changed after it was read, the external ID belongs to another record, the plan or webhook endpoint limit is reached, or the change needs consent to its consequences
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns ConflictProblem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
- 409
idempotency_key_in_useA request with this key is in progress - 409
refund_refusedThe order cannot be refunded - 422
idempotency_key_reusedIdempotency key is already used - 422
invalid_idempotency_keyIdempotency key is invalid
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl -X POST "https://api.saleya.app/v1/orders/{order}/refunds" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H "Content-Type: application/json" \
-d @body.json{
"items": [
{
"order_item_id": 1,
"quantity": "string"
}
],
"shipping_amount": 0,
"irreversible_to": "manual",
"expected_amount": 0
}{
"id": 0,
"order_id": 0,
"pos_shift_id": 0,
"kind": "return",
"status": "pending",
"app_id": 0,
"confirmable": true,
"currency": "string",
"amount": 0,
"shipping_amount": 0,
"tax_lines": [
{
"regime": "vat",
"kind": "taxed",
"rate_bps": 0,
"base": 0,
"amount": 0,
"jurisdiction": "string"
}
],
"exchanged_to_order_id": 0,
"items": [
{
"order_item_id": 0,
"quantity": "string",
"unit": "pcs",
"amount": 0
}
],
"transactions": [
{
"id": 0,
"payment_id": 0,
"method": "cash",
"target": "card",
"amount": 0,
"status": "pending",
"provider_refund_id": "string"
}
],
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}Confirm that the refund money was paid back outside the system
post/refunds/{refund}/confirm
Scope: refunds:write
Parameters
Path
refundintegerrequiredID of the refund.
Header
Idempotency-KeystringUnique key of the attempt, for example a UUID. A retry with the same key and body gets the saved response instead of a second write. Keys live 24 hours.
- Min length:
- 1
- Max length:
- 255
- Example:
8e03978e-40d5-43e8-bc93-6894a57f9324
Responses
200Success
Headers
Idempotent-Replayedstringtrue when this is the saved response of an earlier request with the same Idempotency-Key.
- Values:
true
application/json
Returns Refund
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
404The object does not exist or is not available to the app
application/problem+json
Returns Problem
409A request with the same idempotency key is in progress, the data changed after it was read, the external ID belongs to another record, the plan or webhook endpoint limit is reached, or the change needs consent to its consequences
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns ConflictProblem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
- 409
idempotency_key_in_useA request with this key is in progress - 409
refund_not_confirmableThe refund does not await a payout confirmation - 422
idempotency_key_reusedIdempotency key is already used - 422
invalid_idempotency_keyIdempotency key is invalid
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl -X POST "https://api.saleya.app/v1/refunds/{refund}/confirm" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"id": 0,
"order_id": 0,
"pos_shift_id": 0,
"kind": "return",
"status": "pending",
"app_id": 0,
"confirmable": true,
"currency": "string",
"amount": 0,
"shipping_amount": 0,
"tax_lines": [
{
"regime": "vat",
"kind": "taxed",
"rate_bps": 0,
"base": 0,
"amount": 0,
"jurisdiction": "string"
}
],
"exchanged_to_order_id": 0,
"items": [
{
"order_item_id": 0,
"quantity": "string",
"unit": "pcs",
"amount": 0
}
],
"transactions": [
{
"id": 0,
"payment_id": 0,
"method": "cash",
"target": "card",
"amount": 0,
"status": "pending",
"provider_refund_id": "string"
}
],
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}