Order Summaries, Ensure Refunds Async

Root XML tag

<ensureRefundsAsyncInput>

JSON example

{
  "creditMemoId": "50gR000000000JB00G",
  "invoicesToPay": [
  {
  .."invoiceId": "3ttR000000000JNIAY"
  }
]
}

Properties

Name	Type	Description	Required or Optional	Available Version
creditMemoId	String	ID of the credit memo that represents a refund amount.	Either creditMemoId or excessFunds​Amount is required	48.0
excessFunds​Amount	Double	Amount of excess funds to refund.	Either excessFunds​Amount or creditMemoId is required	49.0
invoicesToPay	Invoice To Pay Input[]	List of invoices for any fees that reduce the refund, such as return fees.	Optional	56.0
isAllowPartial	Boolean	This value controls the behavior when the amounts included in the sequences list don’t cover the entire refund amount. If this value is false, then the default refund logic is applied to ensure the remaining refund amount. If this value is true, then the unrefunded balance remains on the credit memo. If you don’t specify a sequences list, this value is ignored and the default refund logic is applied. The default value is false.	Optional	56.0
isReservedBalanceAmountConsidered	Boolean	If true, the refundable amount is used to open the payment balance for the reservedBalanceAmount in the Order Payment Summaries. The remaining refundable amount considers the sequence of order payment summaries, if provided. If false, any reserved balance amount for exchanges is refunded.	Optional	59.0
sequences	Sequence Order Payment Summary Input[]	Ordered list of refund amounts and OrderPaymentSummaries to apply them to. An OrderPaymentSummary must either belong to the order summary or be a reference to the order summary in the OrderPaymentSummaryReference entity. The process traverses this list in order and stops when it's refunded the full amount.	Optional	56.0

• When the HTTP status code indicates success, the response body is an Ensure Refunds Async Output. The response body can still indicate processing errors.
• When the HTTP status code is in the 400 (client error) or 500 (server error) range, the response body is an Error with Output. The output property is an Ensure Refunds Async Output, and the value of the enhancedErrorType property can be ignored.

This method applies the refund to the OrderPaymentSummaries associated with the specified OrderSummary following this logic.

1. Verify that the CreditMemo balance and excess funds amount don't exceed the total AvailableToRefund amount of all the OrderPaymentSummaries associated with the OrderSummary.
2. If sequences is specified, follow these steps.
   1. Traverse the sequences list in order and apply the specified refund amounts to the specified OrderPaymentSummaries.
   2. If the specified CreditMemo and excess funds are fully refunded, or if isAllowPartial is true, then the action stops here.
3. If a CreditMemo is specified, follow these steps.
   1. If an OrderPaymentSummary has an AvailableToRefund amount matching the CreditMemo’s remaining balance, apply the refund to that payment.
   2. If no exact match was found but one or more OrderPaymentSummary has a large enough AvailableToRefund amount to cover the balance, use the OrderPaymentSummary with the smallest AvailableToRefund amount.
   3. If no single OrderPaymentSummary has a large enough AvailableToRefund amount, use multiple OrderPaymentSummaries in descending order of AvailableToRefund amount. This ensures the fewest OrderPaymentSummaries are used.
4. If only one OrderPaymentSummary is specified but has multiple payments, follow these steps.
   1. If a payment has an amount matching the CreditMemo’s remaining balance, apply the refund to that payment.
   2. If no exact match was found but one or more payment has a large enough amount to cover the balance, use the payment with the smallest amount.
   3. If no single payment has a large enough amount, use multiple payments in descending order of amount. This ensures the fewest payments are used.
5. If an excess funds amount is specified, follow these steps.
   1. Examine those OrderPaymentSummaries. If one has an AvailableToRefund amount matching the excess funds amount, apply the refund to that OrderPaymentSummary.
   2. If no exact match was found but one or more OrderPaymentSummary has a large enough AvailableToRefund amount to cover the balance, use the OrderPaymentSummary with the smallest AvailableToRefund amount.
   3. If no single OrderPaymentSummary has a large enough AvailableToRefund amount, use multiple OrderPaymentSummaries in descending order of AvailableToRefund amount. This ensures the fewest OrderPaymentSummaries are used.