GetSellerPayments

Half.com only. Retrieves a summary of pending or paid payments that Half.com created for the seller identified by the authentication token in the request. Only retrieves payments that occurred within a particular pay period. Each payment is for one order line item in one order. An order can contain order line items for multiple items from multiple sellers, but this call only retrieves payments that are relevant to one seller. The financial value of a payment is typically based on an amount that a buyer paid to Half.com for an order line item, with adjustments for shipping costs and Half.com's commission. For most sellers, each month contains two pay periods: One from the 1st to the 15th of the month, and one from the 16th to the last day of the month. Sellers can refer to their account information on the Half.com site to determine their pay periods. (You cannot retrieve a seller's pay periods by using eBay Web Services.) When a buyer makes a purchase and an order is created, Half.com creates a payment for the seller and marks it as Pending in the seller's Half.com account. Within a certain number of days after the pay period ends, Half.com settles payments for that period and marks each completed payment as Paid. See the Half.com Web site online help for more information about how payments are managed.

See Half.com.

GetSellerPayments Input

The box below lists all fields that could be included in the call request. To learn more about an individual field or its type, click its name in the box (or scroll down to find it in the table below the box).

See also Samples.

See also the Deprecated Objects link above. Fields presented in this color are deprecated, and fields presented in this color are (or soon will be) non-operational.

The XML prototype does not include requester credentials. This is a documentation limitation only (see Standard Requester Credentials for Making Calls).

<?xml version="1.0" encoding="utf-8"?>
<GetSellerPaymentsRequest xmlns="urn:ebay:apis:eBLBaseComponents">
  <!-- Call-specific Input Fields -->
  <Pagination> PaginationType
    <EntriesPerPage> int </EntriesPerPage>
    <PageNumber> int </PageNumber>
  </Pagination>
  <PaymentStatus> RCSPaymentStatusCodeType </PaymentStatus>
  <PaymentTimeFrom> dateTime </PaymentTimeFrom>
  <PaymentTimeTo> dateTime </PaymentTimeTo>
  <!-- Standard Input Fields -->
  <ErrorLanguage> string </ErrorLanguage>
  <MessageID> string </MessageID>
  <OutputSelector> string </OutputSelector>
  <!-- ... more OutputSelector values allowed here ... -->
  <Version> string </Version>
  <WarningLevel> WarningLevelCodeType </WarningLevel>
</GetSellerPaymentsRequest>

Argument	Type	Occurrence	Meaning

Call-specific Input Fields [Jump to standard fields]

Pagination	PaginationType	Optional	If many payments are available, you may need to call GetSellerPayments multiple times to retrieve all the data. Each result set is returned as a page of entries. Use this Pagination information to indicate the maximum number of entries to retrieve per page (i.e., per call), the page number to retrieve, and other data.
Pagination.EntriesPerPage	int	Optional	This integer value is used to specify the maximum number of entries to return in a single "page" of data. This value, along with the number of entries that match the input criteria, will determine the total pages (see PaginationResult.TotalNumberOfPages) in the result set. For most Trading API calls, the maximum value is 200 and the default value is 25 entries per page. For GetOrders, the maximum value is 100 and the default value is 25 orders per page. For GetUserDisputes, this value is hard-coded at 200, and any pagination input is ignored. For GetProducts, the maximum value is 20, and any higher values are ignored. Min: 1. Max: 200. Default: 200.
Pagination.PageNumber	int	Optional	Specifies the number of the page of data to return in the current call. Default is 1 for most calls. For some calls, the default is 0. Specify a positive value equal to or lower than the number of pages available (which you determine by examining the results of your initial request). See the documentation for other individual calls to determine the correct default value. Min: 1. Max: 2147483647. Default: 1.
PaymentStatus	RCSPaymentStatusCodeType	Required	Filter to retrieve only items with the specified payment status (Paid or Pending). "Pending payments" are payments that Half.com has created but that have not yet been sent to the seller's financial institution. Pending payments are typically available once a buyer pays for an order. As Half.com processes payments by using periodic batch jobs, the GetSellerPayments response might not include an order line item's payment for up to 20 minutes after the buyer has paid. You can retrieve pending payments for the current pay period. Pending payments that have not been settled yet can also be retrieved for previous pay periods. "Paid payments" are payments that Half.com processed during previous pay periods. Paid payments might not appear in the seller's financial institution account balance until a certain number of days after the current pay period ends (see the Half.com online help for details). You can only retrieve paid payments for one previous pay period at a time. Applicable values: • CustomCode (in) Reserved for internal or future use. • Paid (in) Order line item payment is completed. • Pending (in) Order line item is awaiting payment. (Not all values in RCSPaymentStatusCodeType apply to this field.)
PaymentTimeFrom	dateTime	Required	Time range filter that retrieves Half.com payments that were created within a single pay period. Sellers can refer to the Half.com site to determine their pay periods. PaymentTimeFrom is the earliest (oldest) time and PaymentTimeTo is the latest (most recent) time in the range. Half.com pay periods start and end at midnight Pacific time, but the time values are stored in the database in GMT (not Pacific time). See "Time Values" in the eBay Web Services guide for information about converting between GMT and Pacific time. If you specify a PaymentStatus of Pending, add a buffer of one hour (or one day) to both ends of the time range to retrieve more data than you need, and then filter the results on the client side as needed. If any pending payments match the request, the response may include all payments since the beginning of the period. If you specify a PaymentStatus of Paid, the time range must contain one full pay period. That is, PaymentTimeFrom must be earlier or equal the start time of the pay period, and PaymentTimeTo must be later than or equal to the end time of the pay period. Otherwise, no paid payments are returned. For example, if the pay period starts on 2005-09-16 and ends on 2005-09-30, you could specify an earlier PaymentTimeFrom value of 2005-09-16T00:00:00.000Z and a later PaymentTimeTo value of 2005-10-01T12:00:00.000Z. If you specify a time range that covers two pay periods, only the payments from the most recent pay period are returned. The earliest time you can specify is 18 months ago.
PaymentTimeTo	dateTime	Required	Time range filter that retrieves Half.com payments for a single pay period. See the description of PaymentTimeTo for details about using this time range filter. For paid payments, this value should be equal to or later than the end of the last day of the pay period, where the time is converted to GMT. For example, if the period ends on 2005-09-30, you could specify 2005-10-01T09:00:00.000Z, which is later than the end of the last day.

Standard Input Fields

ErrorLanguage	string	Optional	Use ErrorLanguage to return error strings for the call in a different language from the language commonly associated with the site that the requesting user is registered with. Specify the standard RFC 3066 language identification tag (e.g., en_US). ID--- country ----- ----- de_AT Austria de_CH Switzerland de_DE Germany en_AU Australia en_CA Canada en_GB United Kingdom en_SG Singapore en_US United States es_ES Spain fr_BE Belgium (French) fr_CA Canada (French) fr_FR France it_IT Italy nl_BE Belgium (Dutch) nl_NL Netherlands zh_CN China en_IN India en_IE Ireland zh_HK Hong Kong See Tags for the Identification of Languages.
MessageID	string	Optional	Most Trading API calls support a MessageID element in the request and a CorrelationID element in the response. If you pass in a MessageID in a request, the same value will be returned in the CorrelationID field in the response. Pairing these values can help you track and confirm that a response is returned for every request and to match specific responses to specific requests. If you do not pass a MessageID value in the request, CorrelationID is not returned. Note: GetCategories is designed to retrieve very large sets of metadata that change once a day or less often. To improve performance, these calls return cached responses when you request all available data (with no filters). When this occurs, the MessageID and CorrelationID fields aren't applicable. However, if you specify an input filter to reduce the amount of data returned, the calls retrieve the latest data (not cached). When this occurs, MessageID and CorrelationID are applicable.
OutputSelector	string	Optional, repeatable: [0..*]	You can use the OutputSelector field to restrict the data returned by this call. When you make a call such as GetItem that retrieves data from eBay, the OutputSelector field is useful for restricting the data returned. This field makes the call response easier to use, especially when a large payload would be returned. If you use the OutputSelector field, the output data will include only the fields you specified in the request. For example, if you are using GetItem and you want the item data in the response to be restricted to the ViewItemURL (the URL where a user can view the listing) and BuyItNowPrice, then within the GetItem request, specify those output fields. To use this field, see the information at the following link. See Selecting Fields to Retrieve.
Version	string	Conditional	The version number of the API code that you are programming against (e.g., 549). The version you specify for a call has these basic effects: - It indicates the version of the code lists and other data that eBay should use to process your request. - It indicates the schema version you are using. You need to use a version that is greater than or equal to the lowest supported version. For the SOAP API: If you are using the SOAP API, this field is required. Specify the version of the WSDL your application is using. For the XML API: If you are using the XML API, this field has no effect. Instead, specify the version in the X-EBAY-API-COMPATIBILITY-LEVEL HTTP header. (If you specify Version in the body of an XML API request and it is different from the value in the HTTP header, eBay returns an informational warning that the value in the HTTP header was used instead.) See: Routing the Request (Gateway URLs) eBay Schema Versioning Strategy Lowest Supported Version
WarningLevel	WarningLevelCodeType	Optional	Controls whether or not to return warnings when the application passes unrecognized or deprecated elements in a request. An unrecognized element is one that is not defined in any supported version of the schema. Schema element names are case-sensitive, so using WarningLevel can also help you remove any potential hidden bugs within your application due to incorrect case or spelling in field names before you put your application into the Production environment. WarningLevel only validates elements; it doesn't validate XML attributes. It also doesn't control warnings related to user-entered strings or numbers, or warnings for logical errors. We recommend that you only use this during development and debugging. Do not use this in requests in your production code. Applicable values: • High (in) Return warnings when the application passes unrecognized or deprecated elements in a request. • Low (in) Do not return warnings when the application passes unrecognized or deprecated elements in a request. This is the default value if WarningLevel is not specified. See Warning Level.

GetSellerPayments Output

The box below lists all fields that might be returned in the response. To learn more about an individual field or its type, click its name in the box (or scroll down to find it in the table below the box).

See also Samples.

See also the Deprecated Objects link above. Fields presented in this color are deprecated, and fields presented in this color are not returned (or soon will not be returned) or are not operational (or soon will be non-operational).

<?xml version="1.0" encoding="utf-8"?>
<GetSellerPaymentsResponse xmlns="urn:ebay:apis:eBLBaseComponents">
  <!-- Call-specific Output Fields -->
  <HasMorePayments> boolean </HasMorePayments>
  <PageNumber> int </PageNumber>
  <PaginationResult> PaginationResultType
    <TotalNumberOfEntries> int </TotalNumberOfEntries>
    <TotalNumberOfPages> int </TotalNumberOfPages>
  </PaginationResult>
  <PaymentsPerPage> int </PaymentsPerPage>
  <ReturnedPaymentCountActual> int </ReturnedPaymentCountActual>
  <SellerPayment> SellerPaymentType
    <AmountPaid> AmountType (double) </AmountPaid>
    <Commission> AmountType (double) </Commission>
    <ExternalProductID> ExternalProductIDType
    </ExternalProductID>
    <ItemID> ItemIDType (string) </ItemID>
    <OrderID> OrderIDType (string) </OrderID>
    <OrderLineItemID> string </OrderLineItemID>
    <PaidTime> dateTime </PaidTime>
    <PaymentType> PaymentTypeCodeType </PaymentType>
    <PrivateNotes> string </PrivateNotes>
    <SellerInventoryID> string </SellerInventoryID>
    <ShippingReimbursement> AmountType (double) </ShippingReimbursement>
    <Title> string </Title>
    <TransactionID> string </TransactionID>
    <TransactionPrice> AmountType (double) </TransactionPrice>
  </SellerPayment>
  <!-- ... more SellerPayment nodes allowed here ... -->
  <!-- Standard Output Fields -->
  <Ack> AckCodeType </Ack>
  <Build> string </Build>
  <CorrelationID> string </CorrelationID>
  <Errors> ErrorType
    <ErrorClassification> ErrorClassificationCodeType </ErrorClassification>
    <ErrorCode> token </ErrorCode>
    <ErrorParameters ParamID="string"> ErrorParameterType
      <Value> string </Value>
    </ErrorParameters>
    <!-- ... more ErrorParameters nodes allowed here ... -->
    <LongMessage> string </LongMessage>
    <SeverityCode> SeverityCodeType </SeverityCode>
    <ShortMessage> string </ShortMessage>
  </Errors>
  <!-- ... more Errors nodes allowed here ... -->
  <HardExpirationWarning> string </HardExpirationWarning>
  <Timestamp> dateTime </Timestamp>
  <Version> string </Version>
</GetSellerPaymentsResponse>

Return Value	Type	Occurrence	Meaning

Call-specific Output Fields [Jump to standard fields]

HasMorePayments	boolean	Always	If true, there are more payments yet to be retrieved. Additional GetSellerPayments calls with higher page numbers or more entries per page must be made to retrieve these payments. If false, no more payments are available or no payments match the request (based on the payment status and time filter).
PageNumber	int	Always	Indicates which page of data holds the current result set. Will be the same as the value specified in the Pagination.PageNumber input. (If the input is higher than the total number of pages, the call fails with an error.) If no payments are returned, the value is 0. If payments are returned, the first page number is 1.
PaginationResult	PaginationResultType	Always	Contains information regarding the pagination of data (if pagination is used), including total number of pages and total number of entries.
PaginationResult .TotalNumberOfEntries	int	Always	Indicates the total number of entries that could be returned by repeated call requests. Returned with a value of 0 if no entries are available.
PaginationResult .TotalNumberOfPages	int	Always	Indicates the total number of pages of data that could be returned by repeated requests. Returned with a value of 0 if no pages are available.
PaymentsPerPage	int	Always	Indicates the number of payments that can be returned per page of data (i.e., per call). This is the same as the value specified in the Pagination.EntriesPerPage input (or the default value, if EntriesPerPage was not specified). This is not necessarily the actual number of payments returned per page (see ReturnedPaymentCountActual).
ReturnedPaymentCountActual	int	Always	Indicates the total number of payments returned (i.e., the number of SellerPayment entries returned.
SellerPayment	SellerPaymentType	Conditionally, repeatable: [0..*]	Information about a single payment that matches the criteria in the request. A payment is between Half.com and a seller. Each payment is for one transaction for one item in one order. An order can contain transactions for multiple items from multiple sellers, but this call only retrieves payments that are relevant to one seller. The financial value of a payment is typically based on an amount that a buyer paid to Half.com for a transaction, plus the shipping cost the buyer paid for the item, minus Half.com's commission. Payments can also describe refunds that the seller has issued. Multiple SellerPayment entries can be returned per page of results. Typically, they are returned in reverse chronological order (most recent PaidTime first). Only returned if payments exist that match the request.
SellerPayment.AmountPaid	AmountType (double)	Always	Total amount paid by buyer for the Half.com order.
SellerPayment.Commission	AmountType (double)	Always	Amount of commission charged by Half.com.
SellerPayment .ExternalProductID	ExternalProductIDType	Always	Contains an ISBN, UPC, or EAN value from the catalog product associated with the Half.com item. All Half.com items are listed with Pre-filled Item Information.
SellerPayment.ItemID	ItemIDType (string)	Always	Unique identifier for the Half.com item listing. Max length: 19 (Note: The eBay database specifies 38. ItemIDs are usually 9 to 12 digits).
SellerPayment.OrderID	OrderIDType (string)	Always	A unique identifier that identifies a single line item or multiple line item (Combined Payment) Half.com order. For a single line item order, the OrderID value is identical to the OrderLineItemID value that is generated upon creation of the order line item. For a Combined Payment order, the OrderID value is created by eBay when the buyer or seller (sharing multiple, common order line items) combines multiple order line items into a Combined Payment order through the Half.com site.
SellerPayment.OrderLineItemID	string	Always	A unique identifier for a Half.com order line item. This field is created as soon as there is a commitment to buy from the seller, and its value is based upon the concatenation of ItemID and TransactionID, with a hyphen in between these two IDs. For a single line item order, the OrderLineItemID value is identical to the OrderID value. Max length: 50 (Note: The eBay database specifies 38. ItemIDs and TransactionIDs are usually 9 to 12 digits.).
SellerPayment.PaidTime	dateTime	Always	The time and date when Half.com created the payment. Half.com creates a payment when the buyer pays for an order. This time is specified in GMT (not Pacific time). See "Time Values" in the eBay Web Services guide for information about converting between GMT and other time zones.
SellerPayment.PaymentType	PaymentTypeCodeType	Always	Indicates whether the payment is for a Half.com sale or a refund. Applicable values: • Refund (out) The seller issued a refund to the buyer. Applicable to Half.com. • Sale (out) The buyer paid the seller. Applicable to Half.com. (Not all values in PaymentTypeCodeType apply to this field.)
SellerPayment.PrivateNotes	string	Conditionally	A text note that the seller specified for the Half.com item, if any. Only visible to the seller. Not returned if the seller specified no notes.
SellerPayment .SellerInventoryID	string	Conditionally	An ID that the seller specified when they listed the Half.com item, if any. It can be used for the seller's SKU. Note that SellerInventoryID is not returned if no ID was specified. (Note: The SKU field used for eBay.com listings is not applicable to Half.com listings.)
SellerPayment .ShippingReimbursement	AmountType (double)	Always	The adjusted shipping cost that Half.com pays the seller. For a multiple line item (Combined Payment) order, the total shipping cost may be less than the cost to ship the items individually, which makes the adjustment necessary. The shipping cost may also be adjusted due to Half.com handling charges. Note: Due to the way shipping costs are calculated, this value may be different for identical items in different orders.
SellerPayment.Title	string	Always	The title of the item listing as it appears on Half.com. Max length: 80.
SellerPayment.TransactionID	string	Always	Unique identifier for a Half.com order line item (transaction). An order line item is created once there is a commitment from a buyer to purchase an item. Along with its corresponding ItemID, a TransactionID is used and referenced during an order checkout flow and after checkout has been completed. Max length: 19 (Note: The eBay database specifies 38. TransactionIDs are usually 9 to 12 digits.).
SellerPayment.TransactionPrice	AmountType (double)	Always	Price of the order line item (transaction) before shipping and other costs.

Standard Output Fields

Ack	AckCodeType	Always	A token representing the application-level acknowledgement code that indicates the response status (e.g., success). The AckCodeType list specifies the possible values for Ack. Applicable values: • CustomCode (out) Reserved for internal or future use. • Failure (out) Request processing failed • Success (out) Request processing succeeded • Warning (out) Request processing completed with warning information being included in the response message (Not all values in AckCodeType apply to this field.)
Build	string	Always	This refers to the specific software build that eBay used when processing the request and generating the response. This includes the version number plus additional information. eBay Developer Support may request the build information when helping you resolve technical issues.
CorrelationID	string	Conditionally	Most Trading API calls support a MessageID element in the request and a CorrelationID element in the response. If you pass in a MessageID in a request, the same value will be returned in the CorrelationID field in the response. Pairing these values can help you track and confirm that a response is returned for every request and to match specific responses to specific requests. If you do not pass a MessageID value in the request, CorrelationID is not returned. Note: GetCategories is designed to retrieve very large sets of metadata that change once a day or less often. To improve performance, these calls return cached responses when you request all available data (with no filters). When this occurs, the MessageID and CorrelationID fields aren't applicable. However, if you specify an input filter to reduce the amount of data returned, the calls retrieve the latest data (not cached). When this occurs, MessageID and CorrelationID are applicable.
Errors	ErrorType	Conditionally, repeatable: [0..*]	A list of application-level errors (if any) that occurred when eBay processed the request. See Error Handling.
Errors.ErrorClassification	ErrorClassificationCodeType	Conditionally	API errors are divided between two classes: system errors and request errors. Applicable values: • CustomCode (out) Reserved for internal or future use. • RequestError (out) An error has occurred either as a result of a problem in the sending application or because the application's end-user has attempted to submit invalid data (or missing data). In these cases, do not retry the request. The problem must be corrected before the request can be made again. If the problem is due to something in the application (such as a missing required field), the application must be changed. If the problem is a result of end-user data, the application must alert the end-user to the problem and provide the means for the end-user to correct the data. Once the problem in the application or data is resolved, resend the request to eBay with the corrected data. • SystemError (out) Indicates that an error has occurred on the eBay system side, such as a database or server down. An application can retry the request as-is a reasonable number of times (eBay recommends twice). If the error persists, contact Developer Technical Support. Once the problem has been resolved, the request may be resent in its original form.
Errors.ErrorCode	token	Conditionally	A unique code that identifies the particular error condition that occurred. Your application can use error codes as identifiers in your customized error-handling algorithms. See the "Errors by Number" document.
Errors.ErrorParameters	ErrorParameterType	Conditionally, repeatable: [0..*]	This optional element carries a list of context-specific error variables that indicate details about the error condition. These are useful when multiple instances of ErrorType are returned.
Errors.ErrorParameters [ attribute ParamID ]	string	Conditionally	The index of the parameter in the list of parameter types returned within the error type.
Errors.ErrorParameters.Value	string	Conditionally	The value of the variable (e.g., the attribute set ID)
Errors.LongMessage	string	Conditionally	A more detailed description of the condition that raised the error.
Errors.SeverityCode	SeverityCodeType	Conditionally	Indicates whether the error is a severe error (causing the request to fail) or an informational error (a warning) that should be communicated to the user. Applicable values: • CustomCode (out) Reserved for internal or future use • Error (out) Application-level error • Warning (out) Warning or informational error
Errors.ShortMessage	string	Conditionally	A brief description of the condition that raised the error.
HardExpirationWarning	string	Conditionally	Expiration date of the user's authentication token. Only returned within the 7-day period prior to a token's expiration. To ensure that user authentication tokens are secure and to help avoid a user's token being compromised, tokens have a limited life span. A token is only valid for a period of time (set by eBay). After this amount of time has passed, the token expires and must be replaced with a new token.
Timestamp	dateTime	Always	This value represents the date and time when eBay processed the request. The time zone of this value is GMT and the format is the ISO 8601 date and time format (YYYY-MM-DDTHH:MM:SS.SSSZ). See Time Values in the eBay Web Services guide for information about this time format and converting to and from the GMT time zone. Note: GetCategories and other Trading API calls are designed to retrieve very large sets of metadata that change once a day or less often. To improve performance, these calls return cached responses when you request all available data (with no filters). When this occurs, this time value reflects the time the cached response was created. Thus, this value is not necessarily when the request was processed. However, if you specify an input filter to reduce the amount of data returned, the calls retrieve the latest data (not cached). When this occurs, this time value does reflect when the request was processed.
Version	string	Always	The version of the response payload schema. Indicates the version of the schema that eBay used to process the request. See "Standard Data for All Calls" in the eBay Web Services Guide for information on using the response version when troubleshooting "CustomCode" values that appear in the response.

GetSellerPayments Detail Controls

Detail Control: DetailLevel

This call does not support varying Detail Levels. You do not need to pass DetailLevel in the request.

GetSellerPayments Samples

An inline sample will be added in a future release. Please refer to the Samples section of the eBay Web Services Guide chapter for GetSellerPayments.

GetSellerPayments Change History

Version	Description
705 2011-01-19	OrderLineItemID (modified): The OrderLineItemID value is now returned in Production under each SellerPayment node.
691 2010-10-14	OrderLineItemID (added): A unique identifier for an eBay transaction, which is based upon the concatenation of ItemID and TransactionID with a hyphen in between these two IDs. OrderLineItemID is only returned if you set your request version to 705.
503 2007-03-07	SellerPayment.ExternalProductID.Value (added): When ExternalProductID defines multiple ISBN values (ISBN-13 and ISBN-10), AlternateValue returns the ISBN-10 value.
487 2006-11-15	SellerPayment.ExternalProductID.Value (doc change): In mid-February 2007, the maximum length of ISBN numbers will increase to 13 (instead of 10). Both 10-digit and 13-digit ISBN numbers will be supported.

User-Contributed Notes

eBay Trading API Call Reference Version 821