Managing User Information

This topic discusses the means for working with and managing various types of user information, from the data for an eBay user to a user's preference settings.

Every person who participates in an item auction—as a seller, a buyer, or a bidder—must first be a registered eBay user to do so. Registering as an eBay user confers on that person a unique identifier by which that person is known in the eBay environment. Additionally, various properties store information about the user, such as the date the user registered on eBay and whether that user is also an eBay Store owner. These user properties can be retrieved by another user, on the eBay site or through an application. (For more information about users, see Users and eBay User Roles.)

Users can control many aspects of their eBay experience through preference settings. These settings are made on the eBay site, on a user's My eBay pages. A number of important settings can also be made from an application.

eBay Stores allows a seller to set up a virtual, online storefront in which that seller conducts business. In setting up a store, the seller can define custom store categories, in which that seller may list items that prospective buyers see in and purchase from the storefront. These custom categories and other Store details can be retrieved by an application. To place an item into the proper Store category, the seller must know the ID for the custom category in the Store. An application can retrieve this data and supply it for selection by the seller when the seller is in the process of defining a new item.

Subtopics

Retrieving User Information

Managing User Preferences

Getting Account Information

Getting Information about a User's Store

Email and Address Privacy Policy

For information on GetUser, including executing the call and business logic, see the GetUser call reference.

Retrieving User Information

To retrieve the data for a particular eBay user, use GetUser. Doing this involves three general steps: setting up the execution environment, specifying the data to return (based on the target user's eBay user ID), and making the API call.

Indicate the user whose data is to be returned by assigning the eBay user ID for that user to the UserID property of the object. Certain private data (such as email addresses) is normally not returned with call responses. See Email Privacy Policy. To indicate this relationship, pass the item ID of the successfully concluded auction in the ItemID property.

Item Property Required Type Purpose
UserID N string eBay user ID for the user whose data is being returned. If not specified, then the user data returned is for the requestor.
ItemID N string Item ID for a listing in which both the requestor and the target user participated (as seller or buyer). Needed to return certain information otherwise hidden, like the email address.

GetUser returns a User object that contains the data for the specified user. An application needs to inspect the properties of this object to get individual data values. See the documentation for UserType for a complete list of its properties.

Returned Values Type Meaning
User UserType User object containing the data for one user.

Uniquely Identifying a User

While the value returned in the User.UserId property uniquely identifies an eBay user, this value cannot be relied on 100% of the time. This is because the user may choose to change his or her eBay user name. When this happens, applications can not rely on the User.UserID value to associate the user with such things as item listings and item sales.

To uniquely and consistently identify a user, use the value returned in User.EIASToken. The EIAS value for a given user does not change, even if the user's eBay user name changes. An application stores this value the same way it stores the eBay user name. When making calls that return a User object (which contains both the UserID and EIASToken), the application checks the user ID returned against the one it has stored and changes the stored user ID as necessary. This check is done based on the EIASToken property. For example, if the application stores the data in a database, it would query the database for the EIASToken value to find the right record and compare the eBay user ID values.

Note that the unique user identifier returned in the EIASToken property has nothing to do the authentication token that you pass in API calls. It also cannot be used as input in places that call for an eBay user ID (such as the UserID input property for GetUser). It does serve as a way to connect user references that have different eBay user names in returned user data. For example, GetItem returns information about the item's current high bidder. Assuming two different item listings where the same user is the high bidder and where that user changed eBay user names between bidding on the two listings, then the value returned in the EIASToken property would allow the application to associate the two with the same buyer and to identify both bidders as the same user.

Working with Anonymous User Information

To protect bidders from fraud, information about a user is made anonymous during bidding. The following rules apply:

When the auction has ended, the User ID of the high bidder is no longer anonymous.

The following API calls may return data that has been made anonymous, depending on who is making the call:

During bidding:

For other users, this tag is returned as true.

In most cases, a field is made anonymous by removing it from the response. Some fields are made anonymous by replacing the real value with a value that doesn't reveal anything about the user:

The Call Reference identifies the fields that are made anonymous for a given call.

Managing User Preferences

On the eBay site, user preferences can be viewed and set on the user's My eBay pages. In an application, managing user preferences is accomplished with SetUserPreferences and GetUserPreferences. Some of the user preferences that can be retrieved or set include the following:

By using calls to manage a user's preferences, an application can improve the user experience, because the user does not have to be redirected to the eBay site to change certain of his or her preferences. Note that for privacy, legal, or other reasons, some user preferences can only be updated by the user through the eBay site.

Getting User Preferences

Applications can get user preferences with GetUserPreferences. The call takes a set of boolean values as input that define whether each category of user preferences is returned.

Once you have made the call, you can retrieve the user preferences from the response. You can display the current set of preferences to the user, and you can use modify the same preferences object or objects and use them as input to set the preferences by using SetUserPreferences. The next section provides more information on the individual preferences and discusses how to set the user preferences.

Setting User Preferences

Use SetUserPreferences to set the user preferences. For more information on this call, see the SetUserPreferences call reference.

Each preference container has properties. The following table contains examples of some of the properties:

Field Type Purpose
CombinedPaymentOption CombinedPaymentOptionCodeType Specifies whether the seller accepts Combined Invoice orders for multiple items, and whether a discount is provided up front or later.
DispatchCutoffTimePreference DispatchCutoffTimePreferencesType The lone field in this container, CutoffTime, sets the seller's default order "cut off time", which is the time that a buyer must make payment on an item in order for that item to qualify for same-day shipping.
UPSRateOption UPSRateOptionCodeType Specifies whether to use the daily rates or the on-demand rates for UPS.
USPSRateOption USPSRateOptionCodeType Specifies whether to use the discounted or retail rates for USPS.
UnpaidItemAssistancePreferences UnpaidItemAssistancePreferencesType The fields in this container set the default behavior of the Unpaid Item Assistant feature.

For more information on this call, see SetUserPreferences.

Getting Account Information

You use GetAccount to retrieve the seller account data of an eBay user. GetAccount retrieves the seller account data for the user making the request (i.e., the eBay user specified in the credentials of the security header for the call). A call requestor can only retrieve his or her own seller account data. No requestor may retrieve the seller account data for another user.

Seller account data consists of a set of account entries. Each account entry can be either a debit assessed against the account or a credit applied to the account.

GetAccount returns the seller account data in one of three report formats:

Indicate which type of report and (if applicable to a particular report type) the date period for the data using properties of the GetAccount object.

For all report types, the Pagination property can be used to control how many account entries are returned per single call. The Pagination.EntriesPerPage property controls how many account entries are returned with the current call. An account entry is one AccountEntryType object returned in the AccountEntries property of the object. The Pagination.PageNumber property controls which page of data is returned by the current call.

Generating an Invoice Report

Invoice reports are sets of seller account data that are analogous to the invoices that eBay issues on a monthly basis to sellers. An invoice report contains the account activities and charges for a one-month period. To get the last generated invoice using GetAccount, set the AccountHistorySelection property to LastInvoice.

eBay archives user account data older than four months. As a result, that data is not available for retrieval. Specify an invoice month that is within the past four months.

Do not specify values for the BeginDate or EndDate properties. They do not apply to this report type.

Generating a Period Report

A period report contains the charges that were applied to the seller's account between two specified dates. Unlike an invoice report, a period report may cover less than one full month or it may cover more than a single month.

To generate a period report, set the AccountHistorySelection property to BetweenSpecifiedDates. To indicate the dates between which charge dates must fall to be included in the report, specify date values for the BeginDate and EndDate properties. A particular charge to the seller's account is returned as an account entry (an AccountEntryType object in the AccountEntries property of the response object) if the date of the charge is on or after the date specified in BeginDate and on or before the date specified in EndDate.

Note: eBay archives user account data older than four months. As a result, that data is not available for retrieval. Specify a beginning data for the report four months not more than four months prior to the date and time the call is made.

Do not specify a value for the InvoiceDate property as it does not apply to this report type.

Working with the GetAccount Result Set

GetAccount returns seller account data in the following primary properties of the GetAccount object:

Accessing Data in the AccountEntries Property

The AccountEntries property (which is of type AccountEntriesType) contains the individual account entries for the report. Each account entry is represented by an AccountEntryType object. Zero, one, or multiple AccountEntryType objects may be returned by a single call, depending on how many account entries there are to be returned and how the pagination of data is configured.

Each AccountEntryType object contains the data for one account entry. Data returned for an account entry includes the date of the charge or credit, the amount of the entry, an item ID with which the entry is associated (if applicable, such as for the Final Value Fee for an item listing), the balance of the account, a flag indicating the reason for the charge or credit, and more.

Accessing Data in the AccountSummary Property

The AccountSummary property (type AccountSummaryType) contains the summary data for the account. Summary information includes such account attributes as account state, bank account information, the date of the last invoice to the seller, and the date of the last payment to eBay made by the seller.

The payment types a user may select for making payments to eBay is not the same for all eBay sites. See SellerPaymentMethod Differences for a list of the seller payment methods that are applicable to each eBay site. A user may only select a payment method from those available on the eBay site with which the user is registered. (Seller payment methods are defined in the SellerPaymentMethodCodeType code list.

In addition to summary information for the requesting user's seller account, the AccountSummary property may contain information for zero, one, or multiple additional accounts. An additional account is one that the user held with a country of residency other than the current one. An eBay user can have only one active account at a time. If a user changes the country of residency, then the new country of residence becomes the currently active account. Any account associated with a previous country of residency is treated as an additional account. Because the currency for these additional accounts are different than the active account, each additional account includes an indicator of the currency for that account. Users who never change their country of residence will not have any additional accounts. Each additional account is represented by an AdditionalAccount object and the AccountSummary.AdditionalAccountsCount property indicates how many additional accounts there are.

Uniquely Identifying an Account Entry

You can uniquely identify the entries that are returned within the AccountEntries tag.

Specifically, the following fields, returned within the AccountEntries tag, can be used in combination as a unique key: AccountEntry.Date, AccountEntry.AccountDetailsEntryType, AccountEntry.ItemID, and AccountEntry.RefNumber.

Getting Information about a User's Store

You can retrieve information about a user's Store, including the custom categories, by using GetStore. For more information, see Editing the Store Settings.

Email and Address Privacy Policy

Email Privacy Policy

You cannot retrieve an email address for any user with whom you do not have an order relationship, regardless of site.

Email is only returned for applicable calls when you are retrieving your own user data OR when you and the other user are in an order relationship and the call is being executed within a certain amount of time after the order line item is created. Based on Trust and Safety policies, the time is unspecified and can vary by site.

RegistrationAddress Privacy Policy

eBay always returns complete RegistrationAddress details (including Phone) when you retrieve your own user data. RegistrationAddress for another user (except for Phone) is only returned if you have an order relationship with that user AND that user is registered on DE/AT/CH, regardless of your registration site and the site to which you send the request.

Using the Seller Dashboard

If you are a seller, your Seller Dashboard gives you a quick way to see how you're doing as an eBay seller. eBay appreciates how hard you work and how important it is to keep track of your business. We designed this tool to help you monitor your progress, maintain your excellent service to our community of buyers, and keep your account in good standing.

We suggest you check your Seller Dashboard regularly to keep track of your performance. For example:

For the latest information about the Seller Dashboard features and policies, see the eBay Web site online help:

About Your Seller Dashboard (eBay US online help)

https://pages.ebay.com/help/myebay/seller-dashboard.html

Zum Thema Verkäufer-Cockpit (eBay Germany online help)

https://pages.ebay.de/help/myebay/seller-dashboard.html

For information on becoming a PowerSeller, see the following link:

https://pages.ebay.com/help/sell/sell-powersellers.html

For information on qualifying as a Top-rated Seller and creating Top-rated Plus listings, see the following link:

https://pages.ebay.com/help/sell/top-rated.html

Use GetSellerDashboard to retrieve your Seller Dashboard. See GetSellerDashboard.

If your application is displaying a Seller Dashboard to a user, it may also be helpful to use GetFeedback to provide related information, such as Detailed Seller Ratings. See GetFeedback.