finances API1.3.0

getTransactionSummary

GET
/transaction_summary
This method is used to retrieve cumulative values for five types of monetary transactions (order sales, seller credits, buyer refunds, buyer-initiated payment disputes, eBay shipping label purchases, and transfers). If applicable, the number of payment holds and the amount of the holds are also returned.

See the description for the filter query parameter for more information on the available filters.

Note: Unless the transactionType filter is used to retrieve a specific type of monetary transaction (sale, buyer refund, seller credit, payment dispute, shipping label, transfer), the creditCount and creditAmount response fields account for both order sales and seller credits (the count and value is not distinguished between the two monetary transaction types).

Input

Resource URI (production)

GET https://apiz.ebay.com/sell/finances/v1/transaction_summary?

URI parameters

ParameterTypeDescription
filterarray of FilterFieldNumerous filters are available for the getTransactionSummary method, and these filters are discussed below. One or more of these filter types can be used. The transactionStatus filter must be used. All other filters are optional.
  • transactionStatus: the data returned in the response pertains to the sales, payouts, and transfer status set. The supported transactionStatus values are as follows:
    • PAYOUT: only consider monetary transactions where the proceeds from the sales order(s) have been paid out to the seller's bank account.
    • FUNDS_PROCESSING: only consider monetary transactions where the proceeds from the sales order(s) are currently being processed.
    • FUNDS_AVAILABLE_FOR_PAYOUT: only consider monetary transactions where the proceeds from the sales order(s) are available for a seller payout, but processing has not yet begun.
    • FUNDS_ON_HOLD: only consider monetary transactions where the proceeds from the sales order(s) are currently being held by eBay, and are not yet available for a seller payout.
    • COMPLETED: this indicates that the funds for the corresponding TRANSFER monetary transaction have transferred and the transaction has completed.
    • FAILED: this indicates the process has failed for the corresponding TRANSFER monetary transaction.
    Below is the proper syntax to use when setting up the transactionStatus filter:

    https://apiz.ebay.com/sell/finances/v1/transaction_summary?filter=transactionStatus:{PAYOUT}
  • transactionDate: only consider monetary transactions that occurred within a specific range of dates. The date format to use is YYYY-MM-DDTHH:MM:SS.SSSZ. Below is the proper syntax to use if filtering by a date range:

    https://apiz.ebay.com/sell/finances/v1/transaction_summary?filter=transactionDate:[2018-10-23T00:00:01.000Z..2018-11-09T00:00:01.000Z]

    Alternatively, the user could omit the ending date, and the date range would include the starting date and up to 90 days past that date, or the current date if the starting date is less than 90 days in the past.
  • transactionType: only consider a specific type of monetary transaction. The supported transactionType values are as follows:
    • SALE: a sales order.
    • REFUND: a refund to the buyer after an order cancellation or return.
    • CREDIT: a credit issued by eBay to the seller's account.
    • DISPUTE: a monetary transaction associated with a payment dispute between buyer and seller.
    • SHIPPING_LABEL: a monetary transaction where eBay is billing the seller for an eBay shipping label. Note that the shipping label functionality will initially only be available to a select number of sellers.
    • TRANSFER: A transfer is a monetary transaction where eBay is billing the seller for reimbursement of a charge. An example of a transfer is a seller reimbursing eBay for a buyer refund.
    Below is the proper syntax to use if filtering by a monetary transaction type:

    https://apiz.ebay.com/sell/finances/v1/transaction_summary?filter=transactionType:{SALE}
  • buyerUsername: only consider monetary transactions involving a specific buyer (specified with the buyer's eBay user ID). Below is the proper syntax to use if filtering by a specific eBay buyer:

    https://apiz.ebay.com/sell/finances/v1/transaction_summary?filter=buyerUsername:{buyer1234}
  • salesRecordReference: only consider monetary transactions corresponding to a specific order (identified with a Selling Manager order identifier). Below is the proper syntax to use if filtering by a specific Selling Manager Sales Record ID:

    https://apiz.ebay.com/sell/finances/v1/transaction_summary?filter=salesRecordReference:{123}

    Note: For all orders originating after February 1, 2020, a value of 0 will be returned in the salesRecordReference field. So, this filter will only be useful to retrieve orders than occurred before this date.
  • payoutId: only consider monetary transactions related to a specific seller payout (identified with a Payout ID). This value is auto-generated by eBay once the seller payout is set to be processed. Below is the proper syntax to use if filtering by a specific Payout ID:

    https://apiz.ebay.com/sell/finances/v1/transaction_summary?filter=payoutId:{5000106638}
  • transactionId: the unique identifier of a monetary transaction. For a sales order, the orderId filter should be used instead. Only the monetary transaction(s) associated with this transactionId value are returned. Below is the proper syntax to use if filtering by a specific transaction ID:

    https://apiz.ebay.com/sell/finances/v1/transaction_summary?filter=transactionId:{03-03620-33763}
  • orderId: the unique identifier of a sales order. For any other monetary transaction, the, the transactionId filter should be used instead. Only the monetary transaction(s) associated with this orderId value are returned. Below is the proper syntax to use if filtering by a specific order ID:

    https://apiz.ebay.com/sell/finances/v1/transaction_summary?filter=orderId:{03-03620-33763}

Occurrence: Required

HTTP request headers

All requests made to eBay REST operations require you to provide the Authorization HTTP header for authentication authorization.

OAuth scope

This request requires an access token created with the authorization code grant flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application):

https://api.ebay.com/oauth/api_scope/sell.finances

See OAuth access tokens for more information.

Output

HTTP response headers

Output container/fieldTypeDescription
creditAmountAmountThis amount is the total dollar value of all the seller's sales and/or credits that match the input criteria.

Note: Unless the transactionType filter is used in the request to retrieve a specific type of monetary transaction, the creditCount and creditAmount fields account for both order sales and seller credits (the count and value is not distinguished between the two monetary transaction types).

If there are no sales/credits (creditCount=0), this container is not returned.

Occurrence: Conditional

creditAmount.currencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the value field. This field is always returned with the amount container.

Default: The currency of the authenticated user's country.

Occurrence: Conditional

creditAmount.valuestringThe monetary amount, in the currency specified by the currency field. This field is always returned with the amount container.

Occurrence: Conditional

creditBookingEntryBookingEntryEnumThe enumeration value indicates whether the dollar amount in the creditAmount field is a charge (debit) to the seller or a credit. Typically, the enumeration value returned here will be CREDIT.

Occurrence: Conditional

creditCountintegerThis integer value indicates the total number of the seller's sales and/or credits that match the input criteria.

Note: Unless the transactionType filter is used in the request to retrieve a specific type of monetary transaction (sale, buyer refund, or seller credit), the creditCount and creditAmount fields account for both order sales and seller credits (the count and value is not distinguished between the two monetary transaction types).

This field is generally returned, even if 0, but it will not be returned if a transactionType filter is used, and its value is set to either REFUND, DISPUTE, or SHIPPING_LABEL.

Occurrence: Conditional

disputeAmountAmountThis amount is the total dollar value associated with any existing payment disputes that have been initiated by one or more buyers. Only the orders that match the input criteria are considered. The Payment Disputes methods in the Fulfillment API can be used by the seller to retrieve more information about any payment disputes.

If there are no payment disputes (disputeCount=0), this container is not returned.

Occurrence: Conditional

disputeAmount.currencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the value field. This field is always returned with the amount container.

Default: The currency of the authenticated user's country.

Occurrence: Conditional

disputeAmount.valuestringThe monetary amount, in the currency specified by the currency field. This field is always returned with the amount container.

Occurrence: Conditional

disputeBookingEntryBookingEntryEnumThe enumeration value indicates whether the dollar amount in the disputeAmount field is a charge (debit) to the seller or a credit. Typically, the enumeration value returned here will be DEBIT, but its possible that CREDIT could be returned if the seller contested one or more payment disputes and won the dispute.

Occurrence: Conditional

disputeCountintegerThis integer value indicates the total number of payment disputes that have been initiated by one or more buyers. Only the orders that match the input criteria are considered. The Payment Disputes methods in the Fulfillment API can be used by the seller to retrieve more information about any payment disputes.

This field is generally returned, even if 0, but it will not be returned if a transactionType filter is used, and its value is set to any value other than DISPUTE.

Occurrence: Conditional

onHoldAmountAmountThis amount is the total dollar value of order sales where the associated funds are on hold. Only the orders that match the input criteria are considered.

If there are no seller payment holds (onHoldCount=0), this container is not returned.

Occurrence: Conditional

onHoldAmount.currencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the value field. This field is always returned with the amount container.

Default: The currency of the authenticated user's country.

Occurrence: Conditional

onHoldAmount.valuestringThe monetary amount, in the currency specified by the currency field. This field is always returned with the amount container.

Occurrence: Conditional

onHoldBookingEntryBookingEntryEnumThe enumeration value indicates whether the dollar amount in the onHoldAmount field is a charge (debit) to the seller or a credit. Typically, the enumeration value returned here will be CREDIT, since on-hold funds should eventually be released as part of a payout to the seller once the hold is cleared.

Occurrence: Conditional

onHoldCountintegerThis integer value indicates the total number of order sales where the associated funds are on hold. Only the orders that match the input criteria are considered.

This field is generally returned, even if 0, but it will not be returned if a transactionStatus filter is used, and its value is set to any value other than FUNDS_ON_HOLD.

Occurrence: Conditional

refundAmountAmountThis amount is the total dollar value of buyer refunds that match the input criteria.

If there are no refunds (refundCount=0), this container is not returned.

Occurrence: Conditional

refundAmount.currencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the value field. This field is always returned with the amount container.

Default: The currency of the authenticated user's country.

Occurrence: Conditional

refundAmount.valuestringThe monetary amount, in the currency specified by the currency field. This field is always returned with the amount container.

Occurrence: Conditional

refundBookingEntryBookingEntryEnumThe enumeration value indicates whether the dollar amount in the refundAmount field is a charge (debit) to the seller or a credit. Typically, the enumeration value returned here will be DEBIT since this a refund from the seller to the buyer.

Occurrence: Conditional

refundCountintegerThis integer value indicates the total number of buyer refunds that match the input criteria.

This field is generally returned, even if 0, but it will not be returned if a transactionType filter is used, and its value is set to any value other than REFUND.

Occurrence: Conditional

shippingLabelAmountAmountThis is the total dollar value of the eBay shipping labels purchased by the seller.

Occurrence: Conditional

shippingLabelAmount.currencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the value field. This field is always returned with the amount container.

Default: The currency of the authenticated user's country.

Occurrence: Conditional

shippingLabelAmount.valuestringThe monetary amount, in the currency specified by the currency field. This field is always returned with the amount container.

Occurrence: Conditional

shippingLabelBookingEntryBookingEntryEnumThe enumeration value indicates whether the dollar amount in the shippingLabelAmount field is a charge (debit) to the seller or a credit. Typically, the enumeration value returned here will be DEBIT, as eBay will charge the seller when eBay shipping labels are purchased, but it can be CREDIT if the seller was refunded for a shipping label or was possibly overcharged for a shipping label.

Occurrence: Conditional

shippingLabelCountintegerThis is the total number of eBay shipping labels purchased by the seller. The count returned here may depend on the specified input criteria.

Occurrence: Conditional

transferAmountAmountThis amount is the total dollar value of buyer refund transfers that match the input criteria.

If there are no transfers (refundCount=0), this container is not returned.

Occurrence: Conditional

transferAmount.currencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the value field. This field is always returned with the amount container.

Default: The currency of the authenticated user's country.

Occurrence: Conditional

transferAmount.valuestringThe monetary amount, in the currency specified by the currency field. This field is always returned with the amount container.

Occurrence: Conditional

transferBookingEntryBookingEntryEnumThe enumeration value indicates whether the dollar amount in the transferAmount field is a charge (debit) to the seller or a credit. Typically, the enumeration value returned here will be DEBIT since this a seller reimbursement to eBay for buyer refunds.

Occurrence: Conditional

transferCountintegerThis integer value indicates the total number of buyer refund transfers that match the input criteria.

This field is generally returned, even if 0, but it will not be returned if a transactionType filter is used, and its value is set to any value other than TRANSFER.

Occurrence: Conditional

HTTP status codes

This call can return one of the following HTTP status codes. For an overview of the status codes, see HTTP status codes in Using eBay RESTful APIs.

StatusMeaning
200Success
400Bad Request
500Internal Server Error

Error codes

For more on errors, plus the codes of other common errors, see Handling errors.

CodeDomainCategoryMeaning
135000API_FINANCESAPPLICATIONThere was a problem with an eBay internal system or process. Contact eBay developer support for assistance.
135006API_FINANCESREQUESTThe value of transaction type filter is invalid.
135007API_FINANCESREQUESTThe value of transaction status filter is invalid.
135008API_FINANCESREQUESTThe value of transaction date filter is invalid.
135009API_FINANCESREQUESTTransaction type filter is missing.
135011API_FINANCESREQUESTTransaction status filter is mandatory.

Warnings

Samples

New to making API calls? Please see Making a Call.

Note: Identifiers, such as order IDs or user IDs, and personal data in these samples might be anonymized or may no longer be active on eBay. If necessary, substitute current, relevant eBay data in your requests.

Sample 1: Get Counts and Values for Paid Out Monetary Transactions

This call sample retrieves a summary of all transaction types for sales orders that have been paid out to the seller. The transaction status filter is set to 'PAYOUT'.

Input

The transactionStatus filter is required and set to PAYOUT.

Below is the syntax to use for a non-date filter:

?filter=filter_type:{filter_value}
GET
https://apiz.ebay.com/sell/finances/v1/transaction_summary?filter=transactionStatus:{PAYOUT}

Output

The output shows the total count and cumulative dollar values of seller payouts/credits and purchased eBay shipping labels. In the getTransactionSummary response, there is no distinction between seller proceeds from orders and seller credits issued by eBay. There were a total of two credits for a cumulative amount of $217.60, and one purchased shipping label for an amount of $9.22. Notice that there are no buyer refunds, buyer-initiated disputes, or seller payments on hold, so these counts are shown as 0, but their corresponding 'amount' and 'booking entry' fields are not shown since they are not applicable.

Sample 2: Get Seller Credit Counts and Values for Paid Out Monetary Transactions

This call sample retrieves the total seller credit count and cumulative dollar values for these credits associated with all sales transactions that have been paid out. The transaction status filter is set to 'PAYOUT' and the transaction type filter is set to 'CREDIT'.

Input

The transactionStatus filter is required and set to PAYOUT, and transactionType filter is included and set to CREDIT.

Below is the syntax to use for a non-date filter:

?filter=filter_type:{filter_value}
GET
https://api.ebay.com/sell/finances/v1_alpha/transaction_summary?filter=transactionStatus:{PAYOUT}&filter=transactionType:{CREDIT}

Output

The output shows the total count and cumulative dollar values of seller credits. Since transactionType filter was included and set to CREDIT, the creditCount and creditAmount values are only from seller credits (and none are from seller payouts).

Sample 3: Get Counts and Values for Transfers

This call sample retrieves the counts and cumulative dollar values for these credits associated with all transfer transactions that have been paid out. The transaction type filter is set to 'TRANSFER'.

Input

The transactionType filter is included and set to TRANSFER.

Below is the syntax to use for a non-date filter:

?filter=filter_type:{filter_value}
GET
https://apiz.ebay.com/sell/finances/v1/transaction_summary?filter=transactionType:{TRANSFER}

Output

The output shows the total count and cumulative dollar values of monetary transfers.