Opening and Managing an eBay Store
This chapter discusses using the API to manage an eBay Store.
eBay Stores is the premium merchandising space on eBay. A seller with an eBay Store ( eBay Stores sellers) can showcase their listings in one customized, searchable location. They can show all of their items together and tell buyers more about their business on their own customized pages. When a buyer goes to the seller's store, they can choose to search within that seller's items only. A Stores seller can list in multiple quantities for longer durations and create custom categories (which are like store departments). Plus, sellers with an eBay Store have advanced merchandising tools that allow them to control which of their items are displayed on key buyer pages.
Sellers with an eBay Store get a powerful set of features to help them sell more on eBay. Plus, Stores sellers get their own distinctive location to showcase all their eBay listings with their own customized storefront and custom Store URL.
When a user who happens to be an eBay Stores seller lists auction-style and fixed price listings on eBay, those listings also appear in the seller's eBay Store.
Each distinct Stores purchase is assigned a unique identifier, or transaction ID. This transaction ID is used for the operations that follow the purchase, including payment and feedback.
For more information on eBay Stores, please see the Store Benefits page on the eBay Web site.
Learn More about the Benefits of eBay Stores
https://pages.ebay.com/storefronts/openbenefits.html
Sellers can create, edit, and manage their Stores on the eBay web site using the Store Builder tool, while the API allows sellers to edit and manage their eBay Store.
Subtopics
Managing a User's Store Preferences
Special Listing Fields for eBay Stores Sellers
Creating a Store
These instructions explain how to use an online form to create eBay Stores in the Production environment and in the Sandbox.
In the Production environment, a user is eligible to create an eBay Store if he or she is a registered seller on eBay and meets one of the following conditions:
- Has a cumulative feedback score of at least 20
- Is registered with ID Verify
In the Sandbox, to be eligible to create an eBay Store:
- You need to use a Sandbox test user (not your normal eBay username, not your eBay Developers
Program username).
For information about creating test users, see Creating a Sandbox Test User.
- The test user must first list at least one item for sale in the Sandbox.
To set up an eBay Store:
- Using a browser, go to the eBay Stores site:
eBay Stores (US) in Production
eBay Stores in the Sandbox
- Click the Open an eBay Store link in the upper right-hand corner of the eBay Stores page.
- Sign in and follow the instructions to create the user's eBay Store. (If you are creating a Store in the Sandbox, be sure to sign in as the test user who will be the store owner.)
Once you have set up an eBay Store, you can edit and manage it programmatically through the API .
Resources of Interest Related to eBay Stores
Build your store quickly and easily
https://pages.ebay.com/storefronts/seller-landing.html
Frequently Asked Seller Questions About eBay Stores
https://pages.ebay.com/storefronts/faq.html
Editing the Store Settings
eBay Store owners can customize the look and feel of a store in two ways:
- By choosing a predefined theme
- By specifying the exact colors and graphics
In addition to specifying the look and feel of the Store, you can specify such things as how items are to be listed and a custom header and header style for the Store. No matter what change you want to make to the Store configuration using the API, you follow the same general procedure.
Step 1: Retrieve the List of Store Options
Some of the options for eBay Stores can change frequently. For this reason, these options are not specified in the Schema, since this would require users to update their Schema every time an option changed. You can obtain the current list of options for eBay Stores by calling GetStoreOptions. These are the types of options that can be retrieved with this call:
- Themes (basic and advanced)
- Logos
- Color schemes
- Subscription names and rates
You should make this call before making changes to a Store configuration to ensure that you are using the most recent set of options.
The returned list of options splits the themes into basic (in the BasicThemeArray property) and advanced (in the AdvancedThemeArray property). Each BasicThemeArray.Theme property contains a color scheme that is compatible with it in the BasicThemeArray.Theme.ColorScheme.ColorSchemeID property. You will notice that the ThemeID properties are repeated; each basic theme has a number of color schemes that are compatible with it. The advanced themes do not contain color schemes, because you can use any AdvancedThemeArray.Theme.ThemeID with any of the generic color scheme IDs in AdvancedThemeArray.GenericColorSchemeArray.ColorScheme.ColorSchemeID.
You can get a user-friendly name for the themes, color schemes, and logos that are returned by this call:
- BasicThemeArray.Theme.Name
- BasicThemeArray.Theme.ColorScheme.Name
- AdvancedThemeArray.Theme.Name
- AdvancedThemeArray.GenericColorSchemeArray.ColorScheme.Name
- LogoArray.Logo.Name
Step 2: Retrieve the Current Store Configuration
Before making any changes to a Store configuration, you may want to display the current configuration for the Store. You obtain the configuration by making a call to GetStore.
You can reuse the Store object that you retrieve from the call to GetStore if you choose to make a change to the Store configuration in SetStore. Simply change the values of one or more properties of the object before submitting it make the changes.
Step 3: Submit the Modified Store Configuration
You make changes to the Store configuration by calling SetStore. You submit a Store object to this call, which contains all the properties that specify the configuration.
Refer to the SetStore Input section of the eBay Trading API Reference for descriptions of the SetStore input fields for configuring an eBay Store.
When you are configuring the look and feel of a Store, you can choose between picking a pre-defined theme and color scheme, or manually filling in the properties that define the look and feel. Following are the rules for how the configuration when various properties of the Store object are specified:
- If ThemeID is specified, and it is different from the existing ThemeID for the Store, then the ColorSchemeID should be specified too, and vice-versa.
- If a ThemeID and ColorSchemeID are specified, and they are same as the ones already on record (the ThemeID and ColorSchemeID are not being changed), then one of the following occurs:
- If you specify one or more of the 12 look and feel settings (colors, fonts, etc...) , they will replace the existing values on record (the values will be set to the defaults if you are editing the theme for the first time).
- If none of these 12 settings are specified, nothing changes.
- If ThemeID and ColorSchemeID are specified, and they are different from the ones on record (the ThemeID and ColorSchemeID are being changed), then one of the following occurs:
- First the ThemeID and ColorSchemeID combination is validated (Is the ThemeID correct? Is the ColorSchemeID correct? Is the ColorSchemeID valid for this ThemeID?)
- If you specify one or more of the 12 look and feel settings, then they will be saved in the database. The missing ones are populated with default values.
- If you don't specify any of those 12 settings, all the 12 settings will have default settings.
All properties of the Store object are optional, so you only need fill in those properties with those values that you wish to change.
The following figure shows how the custom look and feel properties are used on the Store page:
There is no built-in capability in the API to preview how the modified Store will appear. Once changes to a Store configuration are submitted, you can view the URL for the Store to see how it looks.
Updating the Store Design
To update a Store to the New eBay store design, seller's in the US can go to https://www.pages.ebay.com/storefronts/update/ and follow the instructions there.
Below are links to the instructions for all sites with Stores.
Managing Store Categories
An eBay Store owner can use SetStoreCategories to modify the category structure of his or her eBay Store. Store categories can be added, deleted, moved, and renamed with SetStoreCategories. Changes can be made to a single store category or to a list of store categories. Using the API, you can add up to 300 store categories to an eBay Store. Stores support three levels of categories. Use GetStore to retrieve the category structure for your store.
Store categories will not appear in the site user interface unless they contain items.
Items can only be contained within child store categories. A parent category cannot contain items. If adding, moving, or deleting categories displaces items, you must use the ItemDestinationCategoryID input field to specify a destination child category under which the displaced items will be moved. The destination category must have no child categories.
For more information on SetStoreCategories, including input/output fields and samples of the API call structures, please see SetStoreCategories.
Managing Custom Pages
Every Store can optionally include a number of custom pages. These pages can include static HTML content as well as dynamic content that is added using the special eBay Stores tags. The number of custom pages allowed for a Store depends on the subscription level.
Examples of custom pages include the following:
- Frequently Asked Questions (FAQ) page
- Custom storefront page
- General information about one or more items for sale in a Store
You can use the API to add or delete custom pages. You can also mark pages as inactive so that they are not visible to users.
Step 1: Getting the Custom Page List
Each eBay Store contains a list of its custom pages. Unless you already know which custom page you want to edit, then the first thing you must do is retrieve the current list of the Store's custom pages. To retrieve the list, make a call to GetStoreCustomPage without specifying any specific PageID. The call returns information about all the custom pages, including the PageID, Name, and the Order in which the page appears.
Refer to the GetStoreCustomPage section of the eBay Trading API Reference for descriptions of the GetStoreCustomPage input and output fields.
Links to a Store's custom pages appear on the bottom left of the Store's navigation bar:
The Name of the custom page is used in links to the page, and the Order property is used to determine the order of the pages in the list of links.
Step 2: Getting a Single Custom Page
Once you have retrieved the list of custom pages for a Store, you can get the whole content of a single page by making a call to GetStoreCustomPage, specifying the PageID for which page to return.
The return value contains all the same properties for the page you are requesting as were returned when calling GetStoreCustomPage with no PageID, plus a few more. The most significant property returned is CustomPageArray.CustomPage.Content. This property contains the HTML content of the custom page.
For more information on GetStoreCustomPage, please see GetStoreCustomPage.
Step 3: Submitting a Modified or New Custom Page
You can either modify the custom page that you have retrieved, or you can create a new one if you are starting from scratch. Once you have created the HTML content of the custom page, submit the changes by using SetStoreCustomPage.
eBay provides a set of special HTML tags for use in Store custom pages and headers. You can use these tags to do such things as display your feedback rating, a list of items for sale, or a particular item. To use these special HTML tags in your custom page, simply include them in the content of your page which you specify in the CustomPage.Content property. For more information on these special tags, please see the following page in the eBay Help:
https://pages.ebay.com/help/stores/stores-specific-tags.html
The custom page preview feature allows you to view how the page will appear to buyers before the page is added or modified. This is especially useful when you use any of the special Stores HTML tags in your custom page, so that you can see how the page appears when eBay processes the special tags. To use the preview feature, specify the
CustomPage.PreviewEnabled property as
true. To add or modify the custom page after you have previewed it, make a call to
SetStoreCustomPage with either the same or with different inputs, specifying the
CustomPage.PreviewEnabled property as
false.
For more information on SetStoreCustomPage, please see SetStoreCustomPage.
Managing a User's Store Preferences
You can use the API to manage a user's eBay Store preferences. Such preferences include the ability for the Store owner to indicate that they are currently away on vacation, and options on how to handle current listings during a vacation, such as by hiding fixed price items for the duration.
Setting Store Preferences
You set Store preferences by using SetStorePreferences. You specify the preferences that are being set in the StorePreferences property of the request object. This property contains one sub-property, StoreVacationPreferences.
For more information on the call, see SetStorePreferences.
When you set the Store preferences, if you specify in
OnVacation that the Store owner is on vacation, then you must specify one or more of
HideFixedPriceStoreItems,
MessageItem, or
MessageStore as
true.
For all item types, if a
ReturnDate is specified and the
MessageItem property is
true then the
Item.SellerVacationNote property on the
GetItem response indicates that the Store owner will return on the specified date.
After a
ReturnDate has been set, the only way to remove it is to set the date to
1900-1-1. If the property is set to this value when the preferences are submitted, the system will recognize this value and make the field null. Note that if a
ReturnDate is specified, the system will not change the
OnVacation property to
false at that time. The
OnVacation property must always be explicitly changed by the user.
Getting Store Preferences
You can get the current set of Store preferences for a user by using GetStorePreferences. This call returns the same set of preferences as can be set using SetStorePreferences. For more information on this call, see GetStorePreferences.
Special Listing Fields for eBay Stores Sellers
An eBay Stores seller can create up to three levels of custom categories within their Store (either using the eBay Web site or the API) and up to 300 custom categories can be added. Custom categories are often given names that sound like store departments. When executing AddItem (or any call in the AddItem family of calls) the seller can specify one of these custom categories to place the item within that store category. The custom category information is only applicable when the listing is viewed in the seller's Store. For example, if the listing is for a basic Fixed Price item, the store category won't be applicable when the listing is viewed on the main eBay site. GetItem will also return this category ID information.
If a user is an eBay Stores seller, additional fields are returned within the seller role information.
User Information For eBay Stores Sellers
| Item Property | Purpose |
|---|---|
| Item.Storefront.StoreCategoryID | Enables a seller to associate a listing with one of up to 300 custom categories they have previously set up in their eBay Store. Each custom category has a unique ID. A value of 0 indicates that the item is not an eBay Store item. A value of 1 is used for "Other". Applicable for input and output. |
| User.SellerBusinessType.Commercial | Indicates whether the specified user is an eBay Stores seller. Output only. (Only returned for sites that have implemented Seller Business Types.) |
| User.SellerInfo.StoreOwner | Indicates whether the specified user is an eBay Stores seller. Output only. |
| User.SellerInfo.StoreURL | URL pointing to the user's eBay Store page, if any. Output only. |
| Item.Seller.SellerInfo.StoreOwner | Indicates whether the specified user is an eBay Stores seller. Output only. |
| Item.Seller.SellerInfo.StoreURL | URL pointing to the user's eBay Store page, if any. Output only. |
| Item.SellingStatus.HighBidder.SellerInfo.StoreOwner | Indicates whether the specified user is an eBay Stores seller. Output only. |
| Item.SellingStatus.HighBidder.SellerInfo.StoreURL | URL pointing to the user's eBay Store page, if any. Output only. |
Other calls provide no specialized features for eBay Stores sellers. That is, they treat eBay Store sellers' listings just like listings by sellers who are not Store sellers.
Listing US eBay Motors Items in eBay Stores
Items that an eBay Stores seller lists to the US eBay Motors site (site ID of
eBayMotors) also appear in the seller's eBay Store.
eBay Motors items within the Parts & Accessories and the Everything Else categories can be listed in auction-style or fixed-price formats. eBay Motors items within vehicle categories can be listed in either auction-style or fixed-price formats.
Putting Items on Sale
Sales are a great way to promote the items in your eBay store. You can create sales that are seasonal, for specific holidays, for specific categories, or just to clear out inventory. Sales events promote your eBay store by creating excitement and encouraging buyers to browse and buy. Promotional sales apply to fixed-price and auction listings (including Buy It Now listings). For auction listings, only free shipping can be offered as a promotion.
Subtopics
Promotional Sale API
Using the promotional sale APIs, store owners can easily create price discount and/or free shipping sales for many listings at a time. The following API calls can be used to create and manage promotional sales:
While the Promotional Sale calls of the Trading API continue to support item promotions for an eBay store owner, these calls do not support Promoted Listings, and these calls will no longer be enhanced to support any item promotion capabilities as they are developed by eBay. For this reason, it is recommended that sellers/developers make plans to migrate to the Marketing API, which provides all Promotions Manager and Promoted Listings capabilities, and this API will continue to be improved and enhanced as more marketing features become available to sellers.
- SetPromotionalSale
- SetPromotionalSaleListings
- GetPromotionalSaleDetails
Once you have established a promotional sale, several other calls, such as GetItem, can retrieve the original price of a discounted item, along with the start time and end time of a discount. The data is returned in a PromotionalSaleDetails container. Additional information about retrieving this data is accessible from the GetItem, GetSellerList, GetBidderList, GetMyeBayBuying, and GetMyeBaySelling Call Reference documentation.
Defining a Promotional Sale
The first step in applying a discount across many listings is creating a promotional sale using SetPromotionalSale. This call (see SetPromotionalSale) is used to add, modify, or remove a promotional sale. If you are adding a sale, the input fields include the action (add), sale name, sale type ( PromotionalSaleDetails.PromotionalSaleType), and time period.
Sale Types
There are three types of promotional sales:
- Price discount only
- Free shipping only
- Price discount and free shipping
Any of these sale types can be applied to fixed-price listings. Only free shipping can be applied to auction and auction BIN listings.
Price Discount
If your sale includes price discount, you will need to set the discount type as either a percentage reduction of the price or a fixed value to subtract from the price. Set PromotionalSaleDetails.DiscountType to "Percentage" for a percentage discount or "Price" for a fixed value price discount. For either type, you must specify the discount value ( PromotionalSaleDetails.DiscountValue), which is the percentage price reduction for a percentage discount, or the specific amount taken off the price for a fixed price discount. For example, a value of "10" means a 10% price discount for a percentage discount or a $10 discount for a fixed price discount. Fixed amount discounts will be in the currency of the original listing.
Free Shipping
When a listing is in a free shipping sale, the first shipping service cost will be set to free. Any other shipping services in addition to the standard free shipping will still be available. Only the first shipping service/cost appears at the top of the View Item page and in the Shipping column on Search Results. The other options would only show at the very bottom of the View Item page. This is consistent with the behavior for listings with standard free shipping.
Time Period
A start time ( PromotionalSaleDetails.PromotionalSaleStartTime) and end time ( PromotionalSaleDetails.PromotionalSaleEndTime) must be specified for most sales. You can schedule a Sale up to 6 months in advance, or you can schedule a sale to start as early as the next hour. Sale durations must be a minimum of 1 day and cannot exceed 45 days.
Sale end time does not apply to free shipping sales for auction-style listings. When free shipping is added to an auction-style listing it is required to stay on for the duration of the listing. The end date of the sale is synonymous with the end date of the listing, therefore entering a sale end date in not applicable.
Promotional Sale ID
When you successfully define a new promotional sale, the SetPromotionalSale call output includes the unique ID for the sale (PromotionalSaleID). The PromotionalSaleID is used as input for the following calls:
- GetPromotionalSaleDetails to get information about a sale
- SetPromotionalSale to modify a sale
- SetPromotionalSaleListings to add or remove listings for a sale
Managing a Promotional Sale
Once you have defined a promotional sale, you can (with some restrictions) add listings, change sale types, change sale start and end times, change price discounts, remove listings from the sale, and delete the sale.
Getting Information about Promotional Sales
You can get information about an existing promotional sale using GetPromotionalSaleDetails (see GetPromotionalSaleDetails). If you specify a PromotionalSaleID, you get details for the specified promotional sale only, otherwise you get details for all of your promotional sales.
Adding or Removing Listings for a Promotional Sale
After you have added a promotional sale, use SetPromotionalSaleListings to add or remove listings for the sale. To add or remove listings, you must specify the sale ID (PromotionalSaleID) and set Action to "Add" or "Delete."
When adding listings to a sale, you can specify an array of individual item listings ( PromotionalSaleItemIDArray.ItemID) and/or you can specify criteria for including multiple listings, such as all fixed price items (AllFixedPriceItems) or all items listed in a specific store category ( StoreCategoryID). When removing listings from a sale, you must specify an array of individual item listings (PromotionalSaleItemIDArray.ItemID) you want to remove.
See SetPromotionalSaleListings for additional information.
Modifying a Sale
Use SetPromotionalSale to modify a sale. To modify a sale, you must specify the sale ID ( PromotionalSaleDetails.PromotionalSaleID) and set Action to "Update." Modification of a sale can include changing the sale type, changing the sale start and end times, and changing price discounts.
Deleting a Sale
Use SetPromotionalSale to delete a sale. To delete a sale, you must specify the sale ID ( PromotionalSaleDetails.PromotionalSaleID) and set Action to "Delete." You can delete a sale as long as it is not active or pending. Sales cannot be deleted if they contain contains auction-style listings that have bids.
Promotional Sale Rules
Refer to Markdown Manager rules in the eBay site help for rules and restrictions for promotional sales. See the Markdown Manager and Creating a Free Shipping sale with Markdown Manager sections of the eBay Stores FAQ page for additional information about the rules, restrictions, and behavior for promotional sales.
Refer to Promotional Sale Differences for a list of promotional sale restriction and logic differences by eBay site.
Markdown Manager
The promotional sale APIs provide the same functions as Markdown Manager in the eBay Stores Toolkit. For more information about Markdown Manager, the benefits of promotional sales, and marketing tips, please see the Markdown Manager page in the eBay Stores advanced selling pages:
Markdown Manager rules
https://pages.ebay.com/help/sell/items_on_sale.html#markdown