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.
Getting Information about a User's Store
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.
||eBay user ID for the user whose data is being returned. If not specified, then the user data returned is for the requestor.|
||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.
||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:
- Bidders can see their own information
- Information is made anonymous in other cases
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:
Figure: An Example of User ID Made Anonymous for Different Users
UserAnonymizedtag is returned as false to the bidder
UserAnonymizedtag that pertains to a bidder is returned as false to the seller of the item
For other users, this tag is returned as
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:
- FeedbackScore: Replaced by the value "
- UserID when bidding on items: UserID. In bidding situations (such as when listing the high bidder in an auction), eBay replaces the UserID value with an anonymous bidder name value, such as "
- UserID (GetMyeBayBuying only) when bidding on items: UserID is replaced with the string "HighBidder".
Note that in this format, the anonymous bidder ID stays the same for a given auction, but is different for different auctions.
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:
- Offer combined invoice preferences
- Same-day shipping preferences
- Payment preferences
- Unpaid Item Assistant preferences
- Global Shipping Program opt-in status
- Business Policies opt-in status (Customers can enable Business Policies in their Sandbox account by going to the Business Policies Sandbox Opt-in page)
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:
||Specifies whether the seller accepts Combined Invoice orders for multiple items, and whether a discount is provided up front or later.|
||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.|
||Specifies whether to use the daily rates or the on-demand rates for UPS.|
||Specifies whether to use the discounted or retail rates for USPS.|
||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:
- All History
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.
- AccountHistorySelection: Determines which type of report is generated.
- InvoiceDate: Used with invoice reports, the value of the InvoiceDate property indicates the month for which to generate an invoice report.
- BeginDate: Used with period reports, the value of the BeginDate property indicates the start of the date range for a period report. Data retrieved for this report type will be that for charges that occurred (were posted to the account) on or after this date. Used with EndDate to establish a finite date range for the returned data. You can retrieve information that is up to 4 months old.
- EndDate: Used with period reports, the value of the EndDate property indicates the end of the date range for a period report. Data retrieved for this report type will be that for charges that occurred (were posted to the account) on or before this date. Used with BeginDate to establish a finite date range for the returned data.
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
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:
- AccountEntries: Contains a list of zero, one, or multiple individual account entries.
- AccountID: The AccountID property (type
string) contains the unique identifier for the requesting user's seller account.
- AccountSummary: Contains summary data for the requesting user's seller account and information on additional accounts.
- Currency: The value of the Currency property (type
CurrencyCodeType) indicates the currency in which the currently active account's data is expressed.
- HasMoreEntries: Indicates whether there are more account entries yet to be retrieved, considering the number of entries retrieved so far.
- EntriesPerPage: Indicates the number of account entries (the
AccountEntryTypeobjects retrieved in AccountEntries property).
- PaginationResult: The PaginationResult property (type
PaginationResultType). The child elements of this property indicate the total number of pages of data and the total number of individual account entries there are to be returned.
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.
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.
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.
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:
- See if you qualify for improved visibility in Best Match searches with your Search standing.
- Check your Performance Status to see if you are a Top-Rated seller; Top-Rated sellers qualify for the best discounts and eBay services.
- Check your PowerSeller level and see if you qualify for a reduction of your Final Value Fees.
- View your Buyer Satisfaction Status to keep track of your customer service rating and see how you can improve your buyers' experiences.
- Find out if you have any eBay policy violations that might negatively affect your selling, or other situations that require your immediate attention to avoid having restrictions placed on your account.
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)
Zum Thema Verkäufer-Cockpit (eBay Germany online help)
For information on becoming a PowerSeller, see the following link:
For information on qualifying as a Top-rated Seller and creating Top-rated Plus listings, see the following link:
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.