--- schema_version: "1" id: 164044395d443746ed2a5b9a97874a4df541a219bc04b12146afa4396b975c1d title: OrderSummary Class collection: legacydeveloper version: current locale: en-us portal_url: https://docs.salesforce.com/legacydeveloper/current/en-us/apexref/apex_ConnectAPI_OrderSummary_static_methods.md canonical_url: https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_ConnectAPI_OrderSummary_static_methods.htm source_site: developer.salesforce.com content_type: documentation content_hash: ed83a03b54dc287b9f37b9312759ea00d0ec3e5976306fbc05716d4a99afa364 description: Work with orders in Order Management.These methods are for OrderSummary. All methods are static.Retrieve the expected results of adjusting the price of one or more OrderItemSummaries from an OrderSummary, without actually executing the adjustment. The response data contains the financial changes that would result from submitting the proposed adjustment.Adjust the price of one or more OrderItemSummaries from an OrderSummary, and create corresponding change orders.Create a credit memo to represent the refund for one or more change orders associated with an OrderSummary.Create Invoices to represent the charges for one or more change orders. Create Invoices for change orders that increase order amounts, such as for return fees. When you ensure the refund for a return, include the invoices for any associated return fees in the request.Ensure funds for an Invoice and apply them to it and optional define a sequence to capture payments in. If needed, capture authorized funds by sending a request to a payment provider. This method inserts a background operation into an asynchronous job queue and returns the ID of that operation so you can track its status. Payment gateway responses appear in the payment gateway log and do not affect the background operation status.Ensure refunds for a CreditMemo or excess funds by sending a request to a payment provider. This method inserts a background operation into an asynchronous job queue and returns the ID of that operation so you can track its status. Payment gateway responses appear in the payment gateway log and don’t affect the background operation status.Ensure and apply funds for one or more Invoices. If needed, capture authorized funds by sending a request to a payment provider. This method inserts a background operation into an asynchronous job queue and returns the ID of that operation so you can track its status. Payment gateway responses appear in the payment gateway log and do not affect the background operation status.Retrieve the expected change order values for canceling one or more OrderItemSummaries from an OrderSummary, without actually executing the cancel.Retrieve the expected change order financial values for changing order summary fields and related entities, without executing the action.Retrieve the expected change order values for a simple return of one or more OrderItemSummaries from an OrderSummary, without actually executing the return.Cancel one or more OrderItemSummaries from an OrderSummary, and create a corresponding change order.Submit changes to an existing order summary's non-financial fields, pre-fulfillment order item summaries, and related adjustments and taxes, including custom fields.Return one or more OrderItemSummaries from an OrderSummary, and create a corresponding change order. This return is a simple return that creates a change order but not a ReturnOrder. --- # OrderSummary Class Work with orders in Order Management. ## Namespace [ConnectApi](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_classes_connect_api.htm "The ConnectApi namespace (also called Connect in Apex) provides classes for accessing the same data available in Connect REST API. Use Connect in Apex to create custom experiences in Salesforce.") ## OrderSummary Methods These methods are for OrderSummary. All methods are static. - **[adjustPreview(orderSummaryId, adjustInput)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_ConnectAPI_OrderSummary_static_methods.htm#apex_ConnectAPI_OrderSummary_adjustPreview_1)** Retrieve the expected results of adjusting the price of one or more OrderItemSummaries from an OrderSummary, without actually executing the adjustment. The response data contains the financial changes that would result from submitting the proposed adjustment. - **[adjustSubmit(orderSummaryId, adjustInput)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_ConnectAPI_OrderSummary_static_methods.htm#apex_ConnectAPI_OrderSummary_adjustSubmit_1)** Adjust the price of one or more OrderItemSummaries from an OrderSummary, and create corresponding change orders. - **[createCreditMemo(orderSummaryId, creditMemoInput)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_ConnectAPI_OrderSummary_static_methods.htm#apex_ConnectAPI_OrderSummary_createCreditMemo_1)** Create a credit memo to represent the refund for one or more change orders associated with an OrderSummary. - **[createMultipleInvoices(invoicesInput)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_ConnectAPI_OrderSummary_static_methods.htm#apex_ConnectAPI_OrderSummary_createMultipleInvoices_1)** Create Invoices to represent the charges for one or more change orders. Create Invoices for change orders that increase order amounts, such as for return fees. When you ensure the refund for a return, include the invoices for any associated return fees in the request. - **[ensureFundsAsync(orderSummaryId, ensureFundsInput)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_ConnectAPI_OrderSummary_static_methods.htm#apex_ConnectAPI_OrderSummary_ensureFundsAsync_1)** Ensure funds for an Invoice and apply them to it and optional define a sequence to capture payments in. If needed, capture authorized funds by sending a request to a payment provider. This method inserts a background operation into an asynchronous job queue and returns the ID of that operation so you can track its status. Payment gateway responses appear in the payment gateway log and do not affect the background operation status. - **[ensureRefundsAsync(orderSummaryId, ensureRefundsInput)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_ConnectAPI_OrderSummary_static_methods.htm#apex_ConnectAPI_OrderSummary_ensureRefundsAsync_1)** Ensure refunds for a CreditMemo or excess funds by sending a request to a payment provider. This method inserts a background operation into an asynchronous job queue and returns the ID of that operation so you can track its status. Payment gateway responses appear in the payment gateway log and don’t affect the background operation status. - **[multipleEnsureFundsAsync(multipleEnsureFundsInput)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_ConnectAPI_OrderSummary_static_methods.htm#apex_ConnectAPI_OrderSummary_multipleEnsureFundsAsync_1)** Ensure and apply funds for one or more Invoices. If needed, capture authorized funds by sending a request to a payment provider. This method inserts a background operation into an asynchronous job queue and returns the ID of that operation so you can track its status. Payment gateway responses appear in the payment gateway log and do not affect the background operation status. - **[previewCancel(orderSummaryId, changeInput)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_ConnectAPI_OrderSummary_static_methods.htm#apex_ConnectAPI_OrderSummary_previewCancel_1)** Retrieve the expected change order values for canceling one or more OrderItemSummaries from an OrderSummary, without actually executing the cancel. - **[previewChange(orderSummaryId, changeOrderSummaryInput)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_ConnectAPI_OrderSummary_static_methods.htm#apex_ConnectAPI_OrderSummary_previewChange_1)** Retrieve the expected change order financial values for changing order summary fields and related entities, without executing the action. - **[previewReturn(orderSummaryId, changeInput)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_ConnectAPI_OrderSummary_static_methods.htm#apex_ConnectAPI_OrderSummary_previewReturn_1)** Retrieve the expected change order values for a simple return of one or more OrderItemSummaries from an OrderSummary, without actually executing the return. - **[submitCancel(orderSummaryId, changeInput)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_ConnectAPI_OrderSummary_static_methods.htm#apex_ConnectAPI_OrderSummary_submitCancel_1)** Cancel one or more OrderItemSummaries from an OrderSummary, and create a corresponding change order. - **[submitChange(orderSummaryId, changeOrderSummaryInput)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_ConnectAPI_OrderSummary_static_methods.htm#apex_ConnectAPI_OrderSummary_submitChange_1)** Submit changes to an existing order summary's non-financial fields, pre-fulfillment order item summaries, and related adjustments and taxes, including custom fields. - **[submitReturn(orderSummaryId, changeInput)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_ConnectAPI_OrderSummary_static_methods.htm#apex_ConnectAPI_OrderSummary_submitReturn_1)** Return one or more OrderItemSummaries from an OrderSummary, and create a corresponding change order. This return is a simple return that creates a change order but not a ReturnOrder. ### adjustPreview(orderSummaryId, adjustInput) Retrieve the expected results of adjusting the price of one or more OrderItemSummaries from an OrderSummary, without actually executing the adjustment. The response data contains the financial changes that would result from submitting the proposed adjustment. #### API Version 49.0 #### Requires Chatter No #### Signature public static ConnectApi.AdjustOrderSummaryOutputRepresentation adjustPreview(String orderSummaryId, ConnectApi.AdjustOrderItemSummaryInputRepresentation adjustInput) #### Parameters orderSummaryId Type: String ID of the OrderSummary. adjustInput Type: [ConnectApi.AdjustOrderItemSummaryInputRepresentation](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_connectapi_input_adjust_order_item_summary.htm "Price adjustments to order item summaries that together make up a price adjustment to an order, with options for adjusting items in the process of being fulfilled.") Price adjustments to order item summaries that together make up a price adjustment to an order, with options for adjusting items in the process of being fulfilled. #### Return Value Type: [ConnectApi.AdjustOrderSummaryOutputRepresentation](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_connectapi_output_adjust_order_summary_output.htm "Output representation of the financial changes for an adjust items action. For a preview action, these values are the expected output. For a submit action, these values are the actual output.") #### Usage When a price adjustment is applied to an OrderItemSummary, its quantities are considered in three groups: Pre-fulfillment QuantityAvailableToFulfill, which is equal to QuantityOrdered - QuantityCanceled - QuantityAllocated In-fulfillment QuantityAllocated - QuantityFulfilled Post-fulfillment QuantityAvailableToReturn, which is equal to QuantityFulfilled - QuantityReturnInitiated You can apply adjustments to these groups in three different ways, controlled by the allocatedItemsChangeOrderType input property: - Distribute the adjustment evenly between pre-fulfillment and post-fulfillment quantities. Ignore in-fulfillment quantities. Submitting the adjustment would create one change order for the adjustments to pre-fulfillment quantities and one change order for the adjustments to post-fulfillment quantities. - Distribute the adjustment evenly between pre-fulfillment, in-fulfillment, and post-fulfillment quantities. Submitting the adjustment would create one change order for the adjustments to both pre-fulfillment and in-fulfillment quantities, and one change order for the adjustments to post-fulfillment quantities. - Distribute the adjustment evenly between pre-fulfillment, in-fulfillment, and post-fulfillment quantities. Submitting the adjustment would create one change order for the adjustments to pre-fulfillment quantities, one change order for the adjustments to in-fulfillment quantities, and one change order for the adjustments to post-fulfillment quantities. #### See Also - [createCreditMemo(orderSummaryId, creditMemoInput)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_ConnectAPI_OrderSummary_static_methods.htm#apex_ConnectAPI_OrderSummary_createCreditMemo_1 "Create a credit memo to represent the refund for one or more change orders associated with an OrderSummary.") - [ensureRefundsAsync(orderSummaryId, ensureRefundsInput)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_ConnectAPI_OrderSummary_static_methods.htm#apex_ConnectAPI_OrderSummary_ensureRefundsAsync_1 "Ensure refunds for a CreditMemo or excess funds by sending a request to a payment provider. This method inserts a background operation into an asynchronous job queue and returns the ID of that operation so you can track its status. Payment gateway responses appear in the payment gateway log and don’t affect the background operation status.") - [adjustSubmit(orderSummaryId, adjustInput)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_ConnectAPI_OrderSummary_static_methods.htm#apex_ConnectAPI_OrderSummary_adjustSubmit_1 "Adjust the price of one or more OrderItemSummaries from an OrderSummary, and create corresponding change orders.") ### adjustSubmit(orderSummaryId, adjustInput) Adjust the price of one or more OrderItemSummaries from an OrderSummary, and create corresponding change orders. #### API Version 49.0 #### Requires Chatter No #### Signature public static ConnectApi.AdjustOrderSummaryOutputRepresentation adjustSubmit(String orderSummaryId, ConnectApi.AdjustOrderItemSummaryInputRepresentation adjustInput) #### Parameters orderSummaryId Type: String ID of the OrderSummary. adjustInput Type: [ConnectApi.AdjustOrderItemSummaryInputRepresentation](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_connectapi_input_adjust_order_item_summary.htm "Price adjustments to order item summaries that together make up a price adjustment to an order, with options for adjusting items in the process of being fulfilled.") Price adjustments to order item summaries that together make up a price adjustment to an order, with options for adjusting items in the process of being fulfilled. #### Return Value Type: [ConnectApi.AdjustOrderSummaryOutputRepresentation](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_connectapi_output_adjust_order_summary_output.htm "Output representation of the financial changes for an adjust items action. For a preview action, these values are the expected output. For a submit action, these values are the actual output.") #### Usage When a price adjustment is applied to an OrderItemSummary, its quantities are considered in three groups: Pre-fulfillment QuantityAvailableToFulfill, which is equal to QuantityOrdered - QuantityCanceled - QuantityAllocated In-fulfillment QuantityAllocated - QuantityFulfilled Post-fulfillment QuantityAvailableToReturn, which is equal to QuantityFulfilled - QuantityReturnInitiated You can apply adjustments to these groups in three different ways, controlled by the allocatedItemsChangeOrderType input property: - Distribute the adjustment evenly between pre-fulfillment and post-fulfillment quantities. Ignore in-fulfillment quantities. Create one change order for the adjustments to pre-fulfillment quantities and one change order for the adjustments to post-fulfillment quantities. - Distribute the adjustment evenly between pre-fulfillment, in-fulfillment, and post-fulfillment quantities. Create one change order for the adjustments to both pre-fulfillment and in-fulfillment quantities, and one change order for the adjustments to post-fulfillment quantities. - Distribute the adjustment evenly between pre-fulfillment, in-fulfillment, and post-fulfillment quantities. Create one change order for the adjustments to pre-fulfillment quantities, one change order for the adjustments to in-fulfillment quantities, and one change order for the adjustments to post-fulfillment quantities. After submitting a price adjustment, process refunds as appropriate: - If the discount only applied to OrderItemSummaries for which payment hasn’t been captured, it doesn’t require a refund. This situation normally applies to OrderItemSummaries in the US that haven’t been fulfilled. - If the discount applied to OrderItemSummaries that haven’t been fulfilled and for which payment has been captured, process a refund. In this case, pass the totalExcessFundsAmount from the output representation to the [ensureRefundsAsync()](#apex_ConnectAPI_OrderSummary_ensureRefundsAsync_1 "Ensure refunds for a CreditMemo or excess funds by sending a request to a payment provider. This method inserts a background operation into an asynchronous job queue and returns the ID of that operation so you can track its status. Payment gateway responses appear in the payment gateway log and don’t affect the background operation status.") method. - If the discount applied to OrderItemSummaries that have been fulfilled, process a refund. Pass the postFulfillmentChangeOrderId from the output representation to the [createCreditMemo()](#apex_ConnectAPI_OrderSummary_createCreditMemo_1 "Create a credit memo to represent the refund for one or more change orders associated with an OrderSummary.") method, then pass the CreditMemo to the [ensureRefundsAsync()](#apex_ConnectAPI_OrderSummary_ensureRefundsAsync_1 "Ensure refunds for a CreditMemo or excess funds by sending a request to a payment provider. This method inserts a background operation into an asynchronous job queue and returns the ID of that operation so you can track its status. Payment gateway responses appear in the payment gateway log and don’t affect the background operation status.") method. - If the discount applied to both fulfilled and unfulfilled OrderItemSummaries for which payment has been captured, process both refunds. Pass the postFulfillmentChangeOrderId from the output representation to the [createCreditMemo()](#apex_ConnectAPI_OrderSummary_createCreditMemo_1 "Create a credit memo to represent the refund for one or more change orders associated with an OrderSummary.") method, then pass the credit memo and the totalExcessFundsAmount from the output representation to the [ensureRefundsAsync()](#apex_ConnectAPI_OrderSummary_ensureRefundsAsync_1 "Ensure refunds for a CreditMemo or excess funds by sending a request to a payment provider. This method inserts a background operation into an asynchronous job queue and returns the ID of that operation so you can track its status. Payment gateway responses appear in the payment gateway log and don’t affect the background operation status.") method. #### See Also - [createCreditMemo(orderSummaryId, creditMemoInput)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_ConnectAPI_OrderSummary_static_methods.htm#apex_ConnectAPI_OrderSummary_createCreditMemo_1 "Create a credit memo to represent the refund for one or more change orders associated with an OrderSummary.") - [ensureRefundsAsync(orderSummaryId, ensureRefundsInput)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_ConnectAPI_OrderSummary_static_methods.htm#apex_ConnectAPI_OrderSummary_ensureRefundsAsync_1 "Ensure refunds for a CreditMemo or excess funds by sending a request to a payment provider. This method inserts a background operation into an asynchronous job queue and returns the ID of that operation so you can track its status. Payment gateway responses appear in the payment gateway log and don’t affect the background operation status.") - [adjustPreview(orderSummaryId, adjustInput)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_ConnectAPI_OrderSummary_static_methods.htm#apex_ConnectAPI_OrderSummary_adjustPreview_1 "Retrieve the expected results of adjusting the price of one or more OrderItemSummaries from an OrderSummary, without actually executing the adjustment. The response data contains the financial changes that would result from submitting the proposed adjustment.") ### createCreditMemo(orderSummaryId, creditMemoInput) Create a credit memo to represent the refund for one or more change orders associated with an OrderSummary. #### API Version 48.0 #### Requires Chatter No #### Signature public static ConnectApi.CreateCreditMemoOutputRepresentation createCreditMemo(String orderSummaryId, ConnectApi.CreateCreditMemoInputRepresentation creditMemoInput) #### Parameters orderSummaryId Type: String ID of the OrderSummary. creditMemoInput Type: [ConnectApi.CreateCreditMemoInputRepresentation](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_connectapi_input_create_credit_memo.htm "A list of change orders used to create a credit memo.") The list of change order IDs. #### Return Value Type: [ConnectApi.CreateCreditMemoOutputRepresentation](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_connectapi_output_create_credit_memo_output.htm "ID of a created Credit Memo.") ### createMultipleInvoices(invoicesInput) Create Invoices to represent the charges for one or more change orders. Create Invoices for change orders that increase order amounts, such as for return fees. When you ensure the refund for a return, include the invoices for any associated return fees in the request. #### API Version 56.0 #### Requires Chatter No #### Signature public static ConnectApi.CreateMultipleInvoicesFromChangeOrdersOutputRepresentation createMultipleInvoices(ConnectApi.CreateMultipleInvoicesFromChangeOrdersInputRepresentation invoicesInput) #### Parameters invoicesInput Type: [ConnectApi.CreateMultipleInvoicesFromChangeOrdersInputRepresentation](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_connectapi_input_create_multiple_invoices_from_change_orders.htm "Data about the change orders to create Invoices for.") Data about the change orders to create Invoices for. #### Return Value Type: [ConnectApi.CreateMultipleInvoicesFromChangeOrdersOutputRepresentation](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_connectapi_output_create_multiple_invoices_from_change_orders_output.htm "List of lists of invoices created from change orders for fees.") #### See Also - [ensureRefundsAsync(orderSummaryId, ensureRefundsInput)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_ConnectAPI_OrderSummary_static_methods.htm#apex_ConnectAPI_OrderSummary_ensureRefundsAsync_1 "Ensure refunds for a CreditMemo or excess funds by sending a request to a payment provider. This method inserts a background operation into an asynchronous job queue and returns the ID of that operation so you can track its status. Payment gateway responses appear in the payment gateway log and don’t affect the background operation status.") - [createReturnOrder(returnOrderInput)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_ConnectAPI_ReturnOrder_static_methods.htm#apex_ConnectAPI_ReturnOrder_createReturnOrder_1 "Create a ReturnOrder and ReturnOrderLineItems for items belonging to an OrderSummary.") - [returnItems(returnOrderId, returnItemsInput)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_ConnectAPI_ReturnOrder_static_methods.htm#apex_ConnectAPI_ReturnOrder_returnItems_1 "Process ReturnOrderLineItems belonging to a ReturnOrder. Processing a ReturnOrderLineItem generates a change Order and makes that ReturnOrderLineItem read-only. The change order for a returned item or delivery charge has a positive amount and should be used to create a credit memo. The change order for a return fee has a negative amount and should be used to create an invoice. If a processed ReturnOrderLineItem has any remaining expected quantity, then the API creates a separate ReturnOrderLineItem representing that quantity.") ### ensureFundsAsync(orderSummaryId, ensureFundsInput) Ensure funds for an Invoice and apply them to it and optional define a sequence to capture payments in. If needed, capture authorized funds by sending a request to a payment provider. This method inserts a background operation into an asynchronous job queue and returns the ID of that operation so you can track its status. Payment gateway responses appear in the payment gateway log and do not affect the background operation status. #### API Version 48.0 #### Requires Chatter No #### Signature public static ConnectApi.EnsureFundsAsyncOutputRepresentation ensureFundsAsync(String orderSummaryId, ConnectApi.EnsureFundsAsyncInputRepresentation ensureFundsInput) #### Parameters isConsiderReservedBalanceAmount Type: Boolean If true, the reserved balance amount is used for the Order Summary to fund the invoice. If not enough reserved balance amount, any available balance that isn’t reserved by another Order Summary is used. If false, any available balance is used. orderSummaryId Type: String ID of the OrderSummary. ensureFundsInput Type: [ConnectApi.EnsureFundsAsyncInputRepresentation](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_connectapi_input_ensure_funds_async.htm "ID of an Invoice to ensure funds for and apply them to.") The ID of the Invoice. If multiple payments are allowed, you can also specify a sequence to capture payments for the invoice. #### Return Value Type: [ConnectApi.EnsureFundsAsyncOutputRepresentation](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_connectapi_output_ensure_funds_async_output.htm "ID of the asynchronous background operation. This output only includes the operation ID, regardless of whether a call is made to an external payment gateway. It doesn’t include any errors from the operation.") #### Usage This method checks the OrderPaymentSummaries associated with the specified OrderSummary for funds to apply to the Invoice balance following this logic: ![Note](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/images/icon_note.png) #### Note If multiple OrderPaymentSummaries have equal BalanceAmount values, their order of selection is random. 1. Verify that the Invoice balance doesn’t exceed the total BalanceAmount of all the OrderPaymentSummaries associated with the OrderSummary. 2. If an OrderPaymentSummary has a BalanceAmount equal to the Invoice balance, apply the funds from that OrderPaymentSummary. 3. If no exact match was found, apply funds from the OrderPaymentSummary with the largest BalanceAmount. 4. If the Invoice still has a balance to ensure, repeat steps 2 and 3 until the full balance is ensured or no captured funds remain. 5. If the Invoice still has a balance, look for an OrderPaymentSummary with an authorized amount equal to the remaining Invoice balance. If one exists, capture and apply the funds from that OrderPaymentSummary. 6. If no exact match was found, capture and apply funds from the OrderPaymentSummary with the largest authorized amount. 7. If the Invoice still has a balance to ensure, repeat steps 5 and 6 until the full balance is ensured. ![Note](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/images/icon_note.png) #### Note If the method creates a payment, the payment record’s ClientContext value isn’t predictable. Don't use it in custom logic. #### See Also - [multipleEnsureFundsAsync(multipleEnsureFundsInput)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_ConnectAPI_OrderSummary_static_methods.htm#apex_ConnectAPI_OrderSummary_multipleEnsureFundsAsync_1 "Ensure and apply funds for one or more Invoices. If needed, capture authorized funds by sending a request to a payment provider. This method inserts a background operation into an asynchronous job queue and returns the ID of that operation so you can track its status. Payment gateway responses appear in the payment gateway log and do not affect the background operation status.") ### ensureRefundsAsync(orderSummaryId, ensureRefundsInput) Ensure refunds for a CreditMemo or excess funds by sending a request to a payment provider. This method inserts a background operation into an asynchronous job queue and returns the ID of that operation so you can track its status. Payment gateway responses appear in the payment gateway log and don’t affect the background operation status. #### API Version 48.0 #### Requires Chatter No #### Signature public static ConnectApi.EnsureRefundsAsyncOutputRepresentation ensureRefundsAsync(String orderSummaryId, ConnectApi.EnsureRefundsAsyncInputRepresentation ensureRefundsInput) #### Parameters isConsiderReservedBalanceAmount Type: 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. orderSummaryId Type: String ID of the OrderSummary. ensureRefundsInput Type: [ConnectApi.EnsureRefundsAsyncInputRepresentation](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_connectapi_input_ensure_refunds_async.htm "ID of a credit memo to ensure refunds for, an amount of excess funds to refund, or both. At least one is required. Also includes any invoices for fees that reduce the refund amount, such as return fees. If multiple payment methods are available, you can specify how to distribute the refund.") ID of a credit memo to ensure refunds for, an amount of excess funds to refund, or both. At least one is required. Also includes any invoices for fees that reduce the refund amount, such as return fees. If multiple payment methods are available, you can specify how to distribute the refund. #### Return Value Type: [ConnectApi.EnsureRefundsAsyncOutputRepresentation](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_connectapi_output_ensure_refunds_async_output.htm "ID of the asynchronous background operation. This output only includes the operation ID, regardless of whether a call is made to an external payment gateway. It doesn’t include any errors from the operation.") #### Usage This method applies the refund to the OrderPaymentSummaries associated with the specified OrderSummary following this logic. ![Note](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/images/icon_note.png) #### Note If multiple OrderPaymentSummaries have equal AvailableToRefund amounts, their order of selection is random. 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. ![Note](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/images/icon_note.png) #### Note If the method creates a refund, the refund record’s ClientContext value isn’t predictable. Don't use it in custom logic. #### See Also - [createReturnOrder(returnOrderInput)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_ConnectAPI_ReturnOrder_static_methods.htm#apex_ConnectAPI_ReturnOrder_createReturnOrder_1 "Create a ReturnOrder and ReturnOrderLineItems for items belonging to an OrderSummary.") - [returnItems(returnOrderId, returnItemsInput)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_ConnectAPI_ReturnOrder_static_methods.htm#apex_ConnectAPI_ReturnOrder_returnItems_1 "Process ReturnOrderLineItems belonging to a ReturnOrder. Processing a ReturnOrderLineItem generates a change Order and makes that ReturnOrderLineItem read-only. The change order for a returned item or delivery charge has a positive amount and should be used to create a credit memo. The change order for a return fee has a negative amount and should be used to create an invoice. If a processed ReturnOrderLineItem has any remaining expected quantity, then the API creates a separate ReturnOrderLineItem representing that quantity.") - [createMultipleInvoices(invoicesInput)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_ConnectAPI_OrderSummary_static_methods.htm#apex_ConnectAPI_OrderSummary_createMultipleInvoices_1 "Create Invoices to represent the charges for one or more change orders. Create Invoices for change orders that increase order amounts, such as for return fees. When you ensure the refund for a return, include the invoices for any associated return fees in the request.") ### multipleEnsureFundsAsync(multipleEnsureFundsInput) Ensure and apply funds for one or more Invoices. If needed, capture authorized funds by sending a request to a payment provider. This method inserts a background operation into an asynchronous job queue and returns the ID of that operation so you can track its status. Payment gateway responses appear in the payment gateway log and do not affect the background operation status. #### API Version 56.0 #### Requires Chatter No #### Signature public static ConnectApi.MultipleAsyncOutputRepresentation multipleEnsureFundsAsync(ConnectApi.MultipleEnsureFundsAsyncInputRepresentation multipleEnsureFundsInput) #### Parameters multipleEnsureFundsInput Type: [ConnectApi.MultipleEnsureFundsAsyncInputRepresentation](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_connectapi_input_multiple_ensure_funds_async.htm "List of Invoices and the associated OrderSummaries.") List of Invoices and the associated OrderSummaries. #### Return Value Type: [ConnectApi.MultipleAsyncOutputRepresentation](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_connectapi_output_multiple_async_output.htm "IDs of the asynchronous background operations. This output only includes the operation IDs, regardless of whether calls are made to an external payment gateway. It doesn’t include any errors from the operations.") #### Usage For each Invoice in the request, this method checks the OrderPaymentSummaries associated with the specified OrderSummary for funds to apply to the Invoice balance following this logic. ![Note](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/images/icon_note.png) #### Note If multiple OrderPaymentSummaries have equal BalanceAmount values, their order of selection is random. 1. Verify that the Invoice balance doesn’t exceed the total BalanceAmount of all the OrderPaymentSummaries associated with the OrderSummary. 2. If an OrderPaymentSummary has a BalanceAmount equal to the invoice balance, apply the funds from that OrderPaymentSummary. 3. If no exact match was found, apply funds from the OrderPaymentSummary with the largest BalanceAmount. 4. If the Invoice still has a balance to ensure, repeat steps 2 and 3 until the full balance is ensured or no captured funds remain. 5. If the Invoice still has a balance, look for an OrderPaymentSummary with an authorized amount equal to the remaining Invoice balance. If one exists, capture and apply the funds from that OrderPaymentSummary. 6. If no exact match was found, capture and apply funds from the OrderPaymentSummary with the largest authorized amount. 7. If the Invoice still has a balance to ensure, repeat steps 5 and 6 until the full balance is ensured. ![Note](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/images/icon_note.png) #### Note If the method creates a payment, the payment record’s ClientContext value isn’t predictable. Don't use it in custom logic. #### See Also - [ensureFundsAsync(orderSummaryId, ensureFundsInput)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_ConnectAPI_OrderSummary_static_methods.htm#apex_ConnectAPI_OrderSummary_ensureFundsAsync_1 "Ensure funds for an Invoice and apply them to it and optional define a sequence to capture payments in. If needed, capture authorized funds by sending a request to a payment provider. This method inserts a background operation into an asynchronous job queue and returns the ID of that operation so you can track its status. Payment gateway responses appear in the payment gateway log and do not affect the background operation status.") ### previewCancel(orderSummaryId, changeInput) Retrieve the expected change order values for canceling one or more OrderItemSummaries from an OrderSummary, without actually executing the cancel. #### API Version 48.0 #### Requires Chatter No #### Signature public static ConnectApi.PreviewCancelOutputRepresentation previewCancel(String orderSummaryId, ConnectApi.ChangeInputRepresentation changeInput) #### Parameters orderSummaryId Type: String ID of the OrderSummary. changeInput Type: [ConnectApi.ChangeInputRepresentation](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_connectapi_input_change.htm "A list of changes to OrderItemSummaries that make up an order change, such as a cancel or return.") A list of changes to OrderItemSummaries that make up an order change, such as a cancel or return. #### Return Value Type: [ConnectApi.PreviewCancelOutputRepresentation](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_connectapi_output_preview_cancel_output.htm "Expected financial values for a proposed cancel action.") #### See Also - [createCreditMemo(orderSummaryId, creditMemoInput)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_ConnectAPI_OrderSummary_static_methods.htm#apex_ConnectAPI_OrderSummary_createCreditMemo_1 "Create a credit memo to represent the refund for one or more change orders associated with an OrderSummary.") - [ensureRefundsAsync(orderSummaryId, ensureRefundsInput)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_ConnectAPI_OrderSummary_static_methods.htm#apex_ConnectAPI_OrderSummary_ensureRefundsAsync_1 "Ensure refunds for a CreditMemo or excess funds by sending a request to a payment provider. This method inserts a background operation into an asynchronous job queue and returns the ID of that operation so you can track its status. Payment gateway responses appear in the payment gateway log and don’t affect the background operation status.") - [submitCancel(orderSummaryId, changeInput)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_ConnectAPI_OrderSummary_static_methods.htm#apex_ConnectAPI_OrderSummary_submitCancel_1 "Cancel one or more OrderItemSummaries from an OrderSummary, and create a corresponding change order.") ### previewChange(orderSummaryId, changeOrderSummaryInput) Retrieve the expected change order financial values for changing order summary fields and related entities, without executing the action. #### API Version 66.0 #### Requires Chatter No #### Signature public static ConnectApi.PreviewChangeOrderSummaryOutputRepresentation previewChange(String orderSummaryId, ConnectApi.ChangeOrderSummaryInputRepresentation changeOrderSummaryInput) #### Parameters orderSummaryId Type: [String](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_string.htm#apex_methods_system_string "Contains methods for the String primitive data type.") ID of the OrderSummary. changeOrderSummaryInput Type: [ConnectApi.ChangeOrderSummaryInputRepresentation](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_connectapi_input_change_order_summary.htm "A change to an order summary. There are several general validations for this input. The maximum number of changes allowed per request is 100. You must include at least one change for an entity, and each change that's associated with an entity counts as one change. You can modify only order item summaries in Ordered status.") A change to an order summary. There are several general validations for this input. The maximum number of changes allowed per request is 100. You must include at least one change for an entity, and each change that's associated with an entity counts as one change. You can modify only order item summaries in Ordered status. #### Return Value Type: [ConnectApi.PreviewChangeOrderSummaryOutputRepresentation](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_connectapi_output_preview_change_order_summary_output.htm "Expected financial values for a proposed change order summary action.") #### See Also - [submitChange(orderSummaryId, changeOrderSummaryInput)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_ConnectAPI_OrderSummary_static_methods.htm#apex_ConnectAPI_OrderSummary_submitChange_1 "Submit changes to an existing order summary's non-financial fields, pre-fulfillment order item summaries, and related adjustments and taxes, including custom fields.") ### previewReturn(orderSummaryId, changeInput) Retrieve the expected change order values for a simple return of one or more OrderItemSummaries from an OrderSummary, without actually executing the return. #### API Version 48.0 #### Requires Chatter No #### Signature public static ConnectApi.PreviewReturnOutputRepresentation previewReturn(String orderSummaryId, ConnectApi.ChangeInputRepresentation changeInput) #### Parameters orderSummaryId Type: String ID of the OrderSummary. changeInput Type: [ConnectApi.ChangeInputRepresentation](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_connectapi_input_change.htm "A list of changes to OrderItemSummaries that make up an order change, such as a cancel or return.") A list of changes to OrderItemSummaries that make up an order change, such as a cancel or return. #### Return Value Type: [ConnectApi.PreviewReturnOutputRepresentation](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_connectapi_output_preview_return_output.htm "Expected financial values for a proposed return action.") #### See Also - [createCreditMemo(orderSummaryId, creditMemoInput)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_ConnectAPI_OrderSummary_static_methods.htm#apex_ConnectAPI_OrderSummary_createCreditMemo_1 "Create a credit memo to represent the refund for one or more change orders associated with an OrderSummary.") - [ensureRefundsAsync(orderSummaryId, ensureRefundsInput)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_ConnectAPI_OrderSummary_static_methods.htm#apex_ConnectAPI_OrderSummary_ensureRefundsAsync_1 "Ensure refunds for a CreditMemo or excess funds by sending a request to a payment provider. This method inserts a background operation into an asynchronous job queue and returns the ID of that operation so you can track its status. Payment gateway responses appear in the payment gateway log and don’t affect the background operation status.") - [submitReturn(orderSummaryId, changeInput)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_ConnectAPI_OrderSummary_static_methods.htm#apex_ConnectAPI_OrderSummary_submitReturn_1 "Return one or more OrderItemSummaries from an OrderSummary, and create a corresponding change order. This return is a simple return that creates a change order but not a ReturnOrder.") ### submitCancel(orderSummaryId, changeInput) Cancel one or more OrderItemSummaries from an OrderSummary, and create a corresponding change order. #### API Version 48.0 #### Requires Chatter No #### Signature public static ConnectApi.SubmitCancelOutputRepresentation submitCancel(String orderSummaryId, ConnectApi.ChangeInputRepresentation changeInput) #### Parameters orderSummaryId Type: String ID of the OrderSummary. changeInput Type: [ConnectApi.ChangeInputRepresentation](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_connectapi_input_change.htm "A list of changes to OrderItemSummaries that make up an order change, such as a cancel or return.") A list of changes to OrderItemSummaries that make up an order change, such as a cancel or return. #### Return Value Type: [ConnectApi.SubmitCancelOutputRepresentation](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_connectapi_output_submit_cancel_output.htm "ID of the change order created for a cancel action, and a set of its financial values.") #### See Also - [createCreditMemo(orderSummaryId, creditMemoInput)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_ConnectAPI_OrderSummary_static_methods.htm#apex_ConnectAPI_OrderSummary_createCreditMemo_1 "Create a credit memo to represent the refund for one or more change orders associated with an OrderSummary.") - [ensureRefundsAsync(orderSummaryId, ensureRefundsInput)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_ConnectAPI_OrderSummary_static_methods.htm#apex_ConnectAPI_OrderSummary_ensureRefundsAsync_1 "Ensure refunds for a CreditMemo or excess funds by sending a request to a payment provider. This method inserts a background operation into an asynchronous job queue and returns the ID of that operation so you can track its status. Payment gateway responses appear in the payment gateway log and don’t affect the background operation status.") - [previewCancel(orderSummaryId, changeInput)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_ConnectAPI_OrderSummary_static_methods.htm#apex_ConnectAPI_OrderSummary_previewCancel_1 "Retrieve the expected change order values for canceling one or more OrderItemSummaries from an OrderSummary, without actually executing the cancel.") ### submitChange(orderSummaryId, changeOrderSummaryInput) Submit changes to an existing order summary's non-financial fields, pre-fulfillment order item summaries, and related adjustments and taxes, including custom fields. #### API Version 66.0 #### Requires Chatter Yes #### Signature public static ConnectApi.SubmitChangeOrderSummaryOutputRepresentation submitChange(String orderSummaryId, ConnectApi.ChangeOrderSummaryInputRepresentation changeOrderSummaryInput) #### Parameters orderSummaryId Type: [String](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_string.htm#apex_methods_system_string "Contains methods for the String primitive data type.") ID of the OrderSummary. changeOrderSummaryInput Type: [ConnectApi.ChangeOrderSummaryInputRepresentation](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_connectapi_input_change_order_summary.htm "A change to an order summary. There are several general validations for this input. The maximum number of changes allowed per request is 100. You must include at least one change for an entity, and each change that's associated with an entity counts as one change. You can modify only order item summaries in Ordered status.") A change to an order summary. There are several general validations for this input. The maximum number of changes allowed per request is 100. You must include at least one change for an entity, and each change that's associated with an entity counts as one change. You can modify only order item summaries in Ordered status. #### Return Value Type: [ConnectApi.SubmitChangeOrderSummaryOutputRepresentation](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_connectapi_output_submit_change_order_summary_output.htm "ID of the change order created for a submit change order summary action, and a set of its financial values.") #### See Also - [previewChange(orderSummaryId, changeOrderSummaryInput)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_ConnectAPI_OrderSummary_static_methods.htm#apex_ConnectAPI_OrderSummary_previewChange_1 "Retrieve the expected change order financial values for changing order summary fields and related entities, without executing the action.") ### submitReturn(orderSummaryId, changeInput) Return one or more OrderItemSummaries from an OrderSummary, and create a corresponding change order. This return is a simple return that creates a change order but not a ReturnOrder. #### API Version 48.0 #### Requires Chatter No #### Signature public static ConnectApi.SubmitReturnOutputRepresentation submitReturn(String orderSummaryId, ConnectApi.ChangeInputRepresentation changeInput) #### Parameters orderSummaryId Type: String ID of the OrderSummary. changeInput Type: [ConnectApi.ChangeInputRepresentation](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_connectapi_input_change.htm "A list of changes to OrderItemSummaries that make up an order change, such as a cancel or return.") A list of changes to OrderItemSummaries that make up an order change, such as a cancel or return. #### Return Value Type: [ConnectApi.SubmitReturnOutputRepresentation](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_connectapi_output_submit_return_output.htm "ID of the change order created for a return action, and a set of its financial values.") #### Usage After submitting a return, process a refund. Pass the changeOrderId from the output representation to the [createCreditMemo()](#apex_ConnectAPI_OrderSummary_createCreditMemo_1 "Create a credit memo to represent the refund for one or more change orders associated with an OrderSummary.") method, then pass the credit memo to the [ensureRefundsAsync()](#apex_ConnectAPI_OrderSummary_ensureRefundsAsync_1 "Ensure refunds for a CreditMemo or excess funds by sending a request to a payment provider. This method inserts a background operation into an asynchronous job queue and returns the ID of that operation so you can track its status. Payment gateway responses appear in the payment gateway log and don’t affect the background operation status.") method. #### See Also - [createCreditMemo(orderSummaryId, creditMemoInput)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_ConnectAPI_OrderSummary_static_methods.htm#apex_ConnectAPI_OrderSummary_createCreditMemo_1 "Create a credit memo to represent the refund for one or more change orders associated with an OrderSummary.") - [ensureRefundsAsync(orderSummaryId, ensureRefundsInput)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_ConnectAPI_OrderSummary_static_methods.htm#apex_ConnectAPI_OrderSummary_ensureRefundsAsync_1 "Ensure refunds for a CreditMemo or excess funds by sending a request to a payment provider. This method inserts a background operation into an asynchronous job queue and returns the ID of that operation so you can track its status. Payment gateway responses appear in the payment gateway log and don’t affect the background operation status.") - [previewReturn(orderSummaryId, changeInput)](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_ConnectAPI_OrderSummary_static_methods.htm#apex_ConnectAPI_OrderSummary_previewReturn_1 "Retrieve the expected change order values for a simple return of one or more OrderItemSummaries from an OrderSummary, without actually executing the return.")