Skip to main content

Refunds

There are two ways to process refunds:

  • Manual refund: This method involves directly refunding the payment through the payment app.
  • Refund based on OrderGrantedRefund: This method triggers the refund request based on the details stored in OrderGrantedRefund.
note

You may have seen we start referencing Page as a Model. While in the API we still use Page name for backwards compatibility, we will be renaming it to Model in the future.

Manual refund​

The manual refund can be triggered by calling transactionRequestAction. If the refund is successful, the transaction.chargedAmount will be reduced. The order's authorizeStatus, chargeStatus, and totalBalance will also be recalculated based on the new values of chargedAmount and refundedAmount. This method is useful when handling overcharged orders.

The below example shows how to trigger the manual refund:

mutation TransactionRequestAction($id: ID, $actionType: TransactionActionEnum!, $amount: PositiveDecimal) {
  transactionRequestAction(id: $id, actionType: $actionType, amount: $amount) {
    transaction {
      events {
        id
        message
        pspReference
        amount {
          amount
        }
        type
      }
    }
  }
}

The mutation accepts below arguments:

  • id - ID of the transaction which will be used to trigger the refund action.
  • actionType - The type of action to be performed on the requested TransactionItem. For a refund action, use REFUND.
  • amount - The amount of the action. The amount is rounded based on the given currency precision. If not provided Saleor will use TransactionItem.chargedAmount.
  • refundReason - Optional plain text reason for the refund. Will be populated to the TransactionEvent.message field.
  • refundReasonReference - The ID of a Page representing the reason for the refund. This is useful for tracking and reporting purposes, like aggregating refunds by specific type. See configuration to learn more.

Grant refunds​

A granted refund refers to the process where a customer receives their money back after a refund request has been approved. Once a refund is granted, the customer is reimbursed for the purchase.

When processing a refund based on OrderGrantedRefund, there are two steps involved. Firstly, an order must be granted a refund, which defines what should be refunded. This step requires the MANAGE_ORDERS permission. Secondly, a refund needs to be requested based on the created OrderGrantedRefund. This step requires the HANDLE_PAYMENTS permission.

A granted refund contains all the details related to the refund, such as the list of refunded lines, the amount, and the included shipping costs. This is useful when handling refunds based on the products returned by the customer.

The current status of the OrderGrantedRefund is represented by the status field. The possible statuses are:

  • NONE: No refund request has been triggered for the granted refund.
  • PENDING: The refund request has been triggered, but the payment app has not provided the final result.
  • SUCCESS: The refund has been successfully processed.
  • FAILURE: The last refund request failed.

The status is calculated based on the latest refund TransactionEvents assigned to the OrderGrantedRefund. The events can be accessed via the OrderGrantedRefund.transactionEvents field. The assigned TransactionItem can be accessed via the OrderGrantedRefund.transaction field.

The OrderGrantedRefund has an impact on the authorizeStatus, chargeStatus, and totalBalance, as it reduces the total value used to calculate the totalBalance.

note

The maximum amount of OrderGrantedRefund is the order.total.

For example:

  • if an order has a total of 100 USD and a single TransactionItem with a chargedAmount of 100 USD, the totalBalance would be 0, as chargedAmount - order.total results in 0(1).
  • Adding a granted refund with an amount of 10 USD would result in a totalBalance of 10, as chargedAmount - (order.total - grantedRefund.amount) gives 10. The chargeStatus will be OVERCHARGED(2).
  • If a refund request is made based on the defined granted refund and is successfully processed by the payment app, it will reduce the chargedAmount. The totalBalance will be 0, as chargedAmount (90USD) - (order.total - grantedRefund.amount) gives 0. The chargeStatus will be changed to FULL(3).
Step NrtotaltotalBalanceauthorizeStatuschargeStatustr.chargedAmountorderGrantedRefund.amount
11000FULLFULL1000
210010FULLOVERCHARGED10010
31000FULLFULL9010

The following example shows how to create the granted refund with the assigned TransactionItem for the order.

mutation OrderGrantRefundCreate($id: ID!, $input: OrderGrantRefundCreateInput!) {
  orderGrantRefundCreate(id: $id, input: $input) {
    grantedRefund {
      id
    }
    order {
      id
    }
    errors {
      field
      code
      message
      lines {
        lineId
        field
        message
        code
      }
    }
  }
}

The mutation accepts below arguments:

  • id - ID of the Order to which granted refund should be assigned.
  • input:
  • lines - List of lines related to the planned refund action:
  • id - ID of the OrderLine.
  • quantity - The quantity of the specific lines planned to refund.
  • reason - Reason of the refund related to the specific line.
  • reasonReference - ID of the Page representing the reason for the refund. See configuration to learn more.
  • grantRefundForShipping - Determines if the shipping costs will be also included in the refund.
  • amount - Amount of the granted refund. If not provided, the amount will be calculated automatically based on provided lines and grantRefundForShipping.
  • transactionId - ID of TransactionItem that will be used to process the refund. If amount is provided in the input, the transaction.chargedAmount needs to be equal to or greater than the provided amount. If amount is not provided in the input and calculated automatically by Saleor, the min(calculatedAmount, transaction.chargedAmount) will be used. This field was added in Saleor 3.20, and it will be a mandatory input field starting from Saleor 3.21.

The below example shows how to update the existing granted refund

mutation OrderGrantRefundUpdate($id: ID!, $input: OrderGrantRefundUpdateInput!) {
  orderGrantRefundUpdate(id: $id, input: $input) {
    grantedRefund {
      id
    }
    errors {
      addLines {
        field
        message
        code
        lineId
      }
      field
      code
    }
  }
}

The mutation accepts below arguments:

  • id - ID of the OrderGrantedRefund which should be updated
  • input:
  • addLines: Lines that should be added to OrderGrantedRefund
  • id - ID of the OrderLine.
  • quantity - The quantity of the specific lines planned to refund.
  • reason - Reason for the planned refund related to the specific line.
  • reasonReference - ID of the Page representing the reason for the refund. See configuration to learn more.
  • removeLines - List of OrderGrantedRefundLine's IDs that should be removed from OrderGrantedRefund.
  • grantRefundForShipping - Determines if the shipping costs will be also included in the refund.
  • amount - Amount of the granted refund. If not provided, the amount will be calculated automatically based on provided lines and grantRefundForShipping.
  • transactionId - ID of TransactionItem that will be used to process the refund. If amount is provided in the input, the transaction.chargedAmount needs to be equal to or greater than the provided amount. If amount is not provided in the input and calculated automatically by Saleor, the min(calculatedAmount, transaction.chargedAmount) will be used. This field was added in Saleor 3.20, and it will be a mandatory input field starting from Saleor 3.21.
info

When OrderGrantedRefund.status is SUCCESS or PENDING, only reason can be updated.

Below example shows how to trigger the refund based on OrderGrantedRefund:

mutation TransactionRequestRefundForGrantedRefund($grantedRefundId: ID!) {
  transactionRequestRefundForGrantedRefund(grantedRefundId: $grantedRefundId) {
    transaction {
      id
    }
    errors {
      field
      message
      code
    }
  }
}

To request a refund, you need to provide the grantedRefundId field. The mandatory refund details are stored as OrderGrantedRefund, so the refund request will be created based on this data. The OrderGrantedRefund.status field will be updated based on the result of the refund action. The TransactionEvents related to the requested action will be accessible via OrderGrantedRefund.transactionEvents field.

Total remaining grant calculations​

The amount specified in the OrderGrantedRefund determines the portion of the order.total that should be refunded to the customer. The order.totalRemainingGrant specifies the amount that still needs to be refunded to achieve a state where the total charged amount equals the order.total minus the granted refund amount.

The order.totalRemainingGrant amount is calculated based on the following formula:

totalRemainingGrant = totalGrantedRefund - alreadyGrantedRefund

where

  • alreadyGrantedRefund is the difference between already refunded and overcharged amounts

    alreadyGrantedRefund = max((totalRefunded - overchargedAmount), 0)

  • totalGrantedRefund is a sum of all amount from all OrderGrantedRefund. The maximum value is order.total, when the value is above, it's replaced with the order.total.

    totalGrantedRefund = max(sum(orderTotalGranted.amount), order.total)

  • totalRefunded is a sum of amount from all transactions with refunded or pending refunds amount

    totalRefunded = sum(amountRefunded + amountRefundPending)

  • overchargedAmount defines the amount that has been charged over the order.total value. It's calculated as a sum of all processed amounts (excluding cancel amounts) minus the order.total.

    processedAmount = sum(amountCharged + amountRefunded + amountAuthorized + amountChargePending + amountRefundPending + amountAuthorizePending)

    overchargedAmount = processedAmount - order.total

Below is an example order with multiple transactions and totalRemainingGrant at each stage:

  1. An order has a total of 100 USD and two TransactionItems: one with a chargedAmount of 100 USD and the second with chargedAmount of 60 USD. The totalBalance would be 60, as chargedAmount - order.total results in 60, and we do not have any granted refunds. The chargeStatus is OVERCHARGED.

  2. Adding a granted refund of 10 USD increases the totalBalance to 70, as it widens the difference between the total charged amount and the new expected order total. Here's the calculation:

    totalBalance = totalCharged - (order.total - totalGrantedRefunds) = 160 - (100 - 10) = 70

    The totalRemainingGrant becomes 10, as the totalRefundedAmount is 0.

  3. The second transaction is refunded for an amount of 50 USD. After this operation, the totalBalance is 20, and the order remains OVERCHARGED. The totalChargedAmount decreases, and the totalRefundedAmount increases. The totalRemainingGrant remains 10 because the overchargedAmount still exceeds the original order.total.

    overchargedAmount = totalChargedAmount + totalRefundedAmount - order.total = 110 + 50 - 100 = 60

    totalRefunded = max(totalGrantedRefund - (totalRefunded - overchargedAmount), 0) = max(10 - max(50 - 60, 0)) = 10 - 0 = 10

  4. In the next step the first transaction was refunded for 15 USD. This brings the total below the order.total value, reducing the totalRemainingGrant.

  5. Finally, the last refund of 5 USD is processed, resulting in a totalBalance of 0. The chargeStatus is FULL, and the totalRemainingGrant is 0.

Step NrtotaltotalBalanceauthorizeStatuschargeStatustotalChargedAmounttotalRefundedAmountorderGrantedRefund.amounttotalRemainingGrant.amount
110060FULLOVERCHARGED160000
210070FULLOVERCHARGED16001010
310020FULLOVERCHARGED110501010
41005FULLOVERCHARGED9565105
51000FULLFULL9070100

Note:

  • totalChargedAmount - is the sum of charged amounts from all transactions
  • totalRefundedAmount - is the sum of all refunded or pending refunds amount from all transactions
info

In case of calculating total remaining grant:

  • Pending amounts are treated as they were processed, so are included in all processed amounts. It also means that totalChargedAmount includes amountChargePending, and totalRefundedAmount includes amountRefundPending.
  • Authorized amounts, including amountAuthorized and amountAuthorizePending, are also considered processed. These amounts will contribute to the overall processed totals and impact the overchargedAmount.

Refund reasons configuration​

note

Available from 3.22

Staff users with MANAGE_SETTINGS permission can access additional refunds configuration available in Dashboard and via API.

Configuration is global and reflected on every channel.

Currently, RefundSettings type controls a single behavior: whether the reasonReference is required when the refund is created or updated.

Setting Refund Reason Type Requirement​

You can decide you want a strict policy to require a reason reference for every refund. Such reference will be a relation to a Page type. To enable that, you need first to create a Page Type dedicated for such refunds. You can do that in the Dashboard or by pageTypeCreate mutation.

Once you have a PageType ID, you can set it in the refundSettingsUpdate mutation.

mutation SetRefundTypeRequired($pageTypeId:ID!){
  refundSettingsUpdate(input:{
    refundReasonReferenceType:$pageTypeId
  }){
    errors{
      message
    }
  }
}

Now, every time a staff user tries to create a refund via transactionActionRequest or orderGrantRefundCreate/orderGrantRefundUpdate mutations (or via Dashboard), they will be required to provide a reason reference. The existing "reason" field will still be available, but it will be optional.

Note that permitted App will be able to omit this setting. For the staff user, the ValidationError will be raised if the reason reference is not provided. App can omit this field for more powerful workflows.

Apart from that, the refundReason provided in refund mutations must be a valid Page ID of the type set in the refundReasonReferenceType setting. If not, a ValidationError will be raised as well.

Disabling refund reason type requirement​

To opt-out from this strict policy, staff user can disable it in the Dashboard or by running the refundReasonReferenceClear mutation:

mutation DisableRefundTypeRequired {
  refundReasonReferenceClear {
    errors {
      message
    }
  }
}