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.

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: "VHJhbnNhY3Rpb25JdGVtOjljY2NkYTYyLTllMjktNGE0OC05NzIyLWRlYzAwOTRmZmY5Yg=="
    actionType: REFUND
    amount: "10"
  ) {
    transaction {
      events {
        id
        message
        pspReference
        amount {
          amount
        }
        type
      }
    }
  }
}

Expand ▼

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.

Grant refunds

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.

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⁽¹⁾.
• 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⁽²⁾.
• 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⁽³⁾.

Step Nr	total	totalBalance	authorizeStatus	chargeStatus	tr.chargedAmount	orderGrantedRefund.amount
1	100	0	FULL	FULL	100	0
2	100	10	FULL	OVERCHARGED	100	10
3	100	0	FULL	FULL	90	10

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

mutation {
  orderGrantRefundCreate(
    id: "T3JkZXI6NWZlOTE5NzItYjg3OC00Y2QyLTkyN2UtZTQwZDJjZDRjMmEz"
    input: {
      transactionId: "VHJhbnNhY3Rpb25JdGVtOmUzOTVjNzdmLWFmNjQtNDRmZC05NmRiLThkZmNkMDYwNmZmOA=="
      lines: [
        {
          id: "T3JkZXJMaW5lOjdlNzg5NzY0LTUyZWMtNDU3Mi05NWNkLTM5ZjQ0OTJmZDk4ZA=="
          quantity: 5
          reason: "Line reason"
        }
        {
          id: "T3JkZXJMaW5lOjdlNzg5NzY0LTUyZWMtNDU3Mi05NWNkLTM5ZjQ0OTJmZDk4Z1=="
          quantity: 5
        }
      ]
      grantRefundForShipping: true
      amount: 10
      reason: "Returned by customer"
    }
  ) {
    grantedRefund {
      id
    }
    order {
      id
    }
    errors {
      field
      code
      message
      lines {
        lineId
        field
        message
        code
      }
    }
  }
}

Expand ▼

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.
• 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: "T3JkZXJHcmFudGVkUmVmdW5kOjE="
    input: {
      addLines: [
        {
          id: "T3JkZXJMaW5lOjgzYmZmZWI3LTVkNjEtNDMzZS1iOGFkLTFhMTE1NWI2ZTgwNg=="
          quantity: 3
        }
      ]
      removeLines: []
      transactionId: "VHJhbnNhY3Rpb25JdGVtOmUzOTVjNzdmLWFmNjQtNDRmZC05NmRiLThkZmNkMDYwNmZmOA=="
      amount: 10
      grantRefundForShipping: false
      reason: "New reason"
    }
  ) {
    grantedRefund {
      id
    }
    errors {
      addLines {
        field
        message
        code
        lineId
      }
      field
      code
    }
  }
}

Expand ▼

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.
• 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: "T3JkZXJHcmFudGVkUmVmdW5kOjE="
  ) {
    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.