Technical guide: Refunds

When you need to return money to a customer for an already invoiced order, Skip Pay offers two ways to do it. Both result in a refund (a repayment transaction) being registered on the application, but they differ in how the order is affected and in what the customer sees. This guide explains both approaches and helps you decide which one to use.

The two ways to refund

1. Mark order items as returned

Use the Mark order items as returned operation when the customer actually returns some or all of the ordered items. You either send the returned items (identified by code, ean, name and type) or an amount-only partial refund.

This operation automatically creates a refund for the returned amount and adjusts the order accordingly:

• An amount-only partial refund ("items": [] + totalPrice) reduces the order's totalPrice but keeps the order in SENT/DELIVERED.
• A full return (omit items or send an empty body {}) reduces the order's totalPrice to zero and moves the order to RETURNED.

Advantage: the return is transparent to the customer in the Skip Pay environment — the customer sees the returned items and the adjusted order directly in their Skip Pay account.

💡 This approach is covered step by step in the Technical guide: Manage your orders.

2. Create a refund

Use the Create refund endpoint when you need to return an arbitrary amount without referencing specific order items and without changing the order — for example a goodwill refund, a price adjustment, or several partial refunds over time.

Create refund Request example

{
  "totalPrice": {
    "amount": 10000,
    "currency": "CZK"
  },
  "reason": "Goodwill refund",
  "variableSymbol": "1234567890"
}

The refunded amount is deducted from the order's remaining refundable amount, but the order items and the order state stay unchanged. You can repeat the call as many times as needed, up to the order's remaining refundable amount.

Advantage: repeated refunds without the need to change the order. The order keeps its original items and state, so you can issue multiple independent refunds without re-sending order data.

💡 All refunds — created by either approach — can be retrieved via the List refunds endpoint.

Which one to use?

Situation	Endpoint	Item state	Order state
Customer physically returns the goods to you	PUT .../order/return	RETURNED	RETURNED if all items are returned
Additional discount / compensation, customer keeps the goods	POST .../refunds	Unchanged	Unchanged
Goodwill refund / price correction after delivery	POST .../refunds	Unchanged	Unchanged
Partial return of goods + discount on the rest	Combination of both calls	order/return for the returned items + /refunds for the discount	Depends on item states
Partner has no item data (typically integration via an intermediary)	POST .../refunds	N/A	Unchanged

Good to know...

Both endpoints validate the refund against the order's remaining refundable amount (the original order total minus the sum of refunds already created), and the order must already be invoiced.

Need help?

If you have any questions or issues related to refunds, send us an email at integrace@skippay.cz