Order Transactions: Sample Flows

This article presents possible use cases and corresponding sample flows that you can support. It provides a useful starting point as you plan your implementation.

Retrieve transactions related to eCommerce orders

Your app can retrieve details about payments and refunds associated with an order. For example, you can check for payments that were made by credit card, payments made by gift card, or orders that were not successfully refunded.

To retrieve info about an order's transactions:

1. Call List Transactions For Single Order with an eCommerce order ID.
   • To retrieve transaction details about more than 1 order, call List Transactions For Multiple Orders with an array of eCommerce order IDs.
2. You can use the returned info to check payment and refund details in the relevant provider or gateway systems, pass the details on to your accounting or invoice apps, and more.

Add payment records to imported orders

If you are importing orders from other systems, you may want to add payment records to those orders. To add a payment record to an order that is already in the eCommerce system:

1. Once you have the order ID, pass it to the Add Payments method.
2. In the request, specify payment details such as createdDate, amount, and regularPaymentDetails.paymentMethodName.
3. When using Add Payments you can add up to 50 payment records to a single order with 1 API call.

Break down sales by payment method

Your app can report how a site's sales split across payment methods, such as how much buyers paid by card, by gift card, or in cash. Orders don't include payment method details, so you read them from each order's transactions and group the payments yourself.

To break down sales by payment method:

1. Call Search Orders. Filter by createdDate for the reporting period and by the paymentStatus values you want to include. Page through the results with cursorPaging and collect each order's id and currency.

2. Call List Transactions For Multiple Orders with up to 100 order IDs per call.

3. For each payment in orderTransactions.payments, identify the payment type by the details object the payment contains. Each payment contains exactly one of regularPaymentDetails, giftcardPaymentDetails, or membershipPaymentDetails, directly on the payment object. For example, a card payment looks like this:

   Copy

4. For regular payments, take the payment method name from regularPaymentDetails.paymentMethodName:

   • When userDefinedName is set, use it, because it takes precedence. It contains either a predefined value (CASH, BANK_TRANSFER, or CHECK) or a custom name. Map predefined values to display names, such as CASH to "Cash".
   • Otherwise, use siteLanguageName. It's in the site's language, so payments made with the same method are usually grouped together regardless of the buyer's language. For some older payments, and when no translation into the site's language is available, siteLanguageName holds the same value as buyerLanguageName, so the same method can appear under more than one name.
   • To break down card payments by card network, use regularPaymentDetails.creditCardDetails.brand.

5. Add each payment's amount to the total for its payment method. Summing payments instead of order totals correctly splits orders that buyers paid with more than one method, such as a gift card and a card.

   • Keep a separate total for each order currency, because buyers on a multi-currency site can pay in different currencies.
   • Include only payments whose status is APPROVED, PARTIALLY_REFUNDED, or REFUNDED. A refunded gift card payment has the status VOIDED, so it isn't included in these totals, even before you subtract refunds.
   • When the payment has cashRounding.unroundedAmount, use it instead of amount, because the order's balance is calculated from it.
   • Membership payments don't have an amount, so they don't add to any total.

6. To report net sales, subtract refunds:

   • For a payment whose status is REFUNDED, subtract the full amount you added in the previous step. For a cash-rounded payment, a full refund can differ slightly from the payment amount, so don't use the refund transaction amounts.
   • For a payment whose status is PARTIALLY_REFUNDED, go through the transactions array of each refund in orderTransactions.refunds. Find the transactions whose paymentId matches the payment's id and whose refundStatus is SUCCEEDED. Subtract their amount.