The Sales Maximizer APIs have two primary uses: to perform a product search and return the lowest price for the product's active auction listings; and to search for and retrieve the lowest price trend for the product over the last three months. Additionally, the Sales Maximizer APIs can be used to return the current count of products available for purchase in auction listings, and to return the price of the auction listing ending the soonest (relative to the call).
Related Items Management is a SOA service that is intended to be consumed by sellers in the US, UK, and Germany. This service allows sellers to create and manage product bundles, which consist of one primary product and multiple related items. Product bundles assist sellers in increasing sales by marketing related items to buyers. The incentive of product bundles to buyers is order discounts when multiple items in a product bundle are purchased.
The Related Items Management API has calls to create, update, retrieve, and delete product bundles. Additionally, the getVersion call simply returns the current version of the Related Items Management service.
Refer to the Related Items Management API Call Reference documentation for detailed information on each call, including input fields, output fields, and samples.
Order Size Discounts is a SOA service that is intended to be consumed by sellers in the US, UK, and Germany. This service allows sellers to create and manage discount campaigns. Discount campaigns allow sellers to offer discounts to buyers based on order size (number of items in order or total order value). To be eligible for a discount, buyers must purchase the primary product and at least one related item in a product bundle. Product bundles assist sellers in increasing sales by marketing related items to buyers.
The Order Size Discounts API has calls to create, update, retrieve, and delete discount campaigns. Additionally, the getVersion call simply returns the current version of the Order Size Discounts service.
Refer to the Order Size Discounts API Call Reference documentation for detailed information on each call, including input fields, output fields, and samples.
As previously mentioned, the Related Items Management API is used to create and manage product bundles. The following table lists the possible use cases for this service and the corresponding calls to use to perform that use case.
| Use Case | Call | Notes |
|---|---|---|
| Create one or more product bundles | createBundles | Use one bundle node per product bundle |
| Update one or more product bundles | updateBundles | Use one bundle node per product bundle |
| Update the status of one or more product bundles | updateBundleStatus | Use one bundleStatusMap container per product bundle |
| Delete one or more product bundles | deleteBundles | Pass in one or more bundle IDs to delete the corresponding product bundles. |
| Retrieve all product bundles associated with seller's account | findBundles | Use no filters. |
| Retrieve one or more specific product bundles by bundleID | findBundles, getBundles | For findBundles, use one bundleFilter container per product bundle, and specify the bundleFilter.bundleID value (the primarySKU value will be optional). For getBundles, pass in one or more bundle IDs to retrieve the corresponding product bundles. |
| Retrieve one or more specific product bundles by the primary product's SKU value | findBundles | Use one bundleFilter container per product bundle, and specify the bundleFilter.primarySKU value (the bundleID value will be optional). |
| Retrieve one or more product bundles by status | findBundles | Specify a BundleStatusEnum value in the findAllByStatus field. |
| Retrieve the current version of the service | getVersion | This call has no input fields. |
A bundle object is created with createBundles, updated with updateBundles, and retrieved with the findBundles and getBundles calls. These four calls all use each field in the Bundle type, with the exception being bundleID, which is not used in the createBundles request. Instead, the bundleID is returned under the bundleStatus container of the createBundles response.
The unique identifier of a product bundle is bundleID. A bundleID value is created by eBay and mapped to a product bundle upon creation. A bundleID is required in updateBundles, and is always returned in the findBundles and getBundles calls. bundleID values are also used as arguments in the deleteBundles, findBundles, getBundles, and updateBundleStatus calls.
The Bundle type contains the following fields and containers:
Multiple product bundles can be created, updated, or retrieved with one Related Items Management call.
Each product bundle consists of one or more product groups, and each product group consists of one or more related products. All product bundles have a primary product, and the seller-defined SKU (stock-keeping unit) of the primary product is required for all product bundles. The related items in the product bundle will appear on all listings for the primary product, which is defined by the primarySKU.
Once the primary product is established, it is time to create a group of related items that are tied to the primary SKU. Product groups are defined through the relatedProductGroup container. All product groups must be named using the groupName field.
Products within a product group are defined through the relatedProduct container. Each product within a product group must have a title or a SKU value, or both values can be assigned. A discount rule must be set for each product in the bundle using the discount container. The discount type will either be a fixed amount discount (such as $20 off) or a percentage discount (20% off).
When creating a product bundle, a scheduledStartTime and scheduledEndTime must be specified. The related items will be included on all primary product listings during this defined time frame. The start time must be a date in the future and the end time must be a date later than the start time.
In the createBundles call, the common use case is to create a new product bundle and have that product bundle automatically activated once the scheduledStartTime is reached. For this use case, the bundleStatus field is not necessary. However, there may a use case where a seller wants to create a new product bundle, but does not want it active yet, even after the scheduledStartTime is reached. In this case, the seller would include the bundleStatus field and set its value to Disabled.
The four bundle states are Active, Scheduled, Ended , and Disabled. Disabled is the only BundleStatusEnum value that is applicable for the createBundles call. However, there are use cases where Active or Disabled would be passed in an updateBundles or updateBundleStatus call, and any of the four values may be returned in a findBundles or getBundles call.
If they occur, errors and/or warnings are returned at the call level and at the product bundle level. If an error or warning appears at the call level, there is an issue with the call request. If an error or warning occurs at the product bundle level, there is an issue with the creation of the bundle.
If a product bundle is created successfully with a createBundles call, the following is returned under the bundleStatus container in the call response:
The following are some common errors that can occur when using the createBundles call:
One or more product bundles can be updated with the updateBundles call. The bundleID value is required to identify the product bundle to be updated. Except for the bundle ID, any existing product bundle data can be modified with the updateBundles call. Below are examples of changes that can be made with the updateBundles call:
If you only want to update the status of one or more product bundles, use the updateBundleStatus call.
The following are some common errors that can occur when using the updateBundles call:
The following are some common errors that can occur when using the updateBundleStatus call:
One or more product bundles can be retrieved by using the getBundles or findBundles calls. In the getBundles call, one or more product bundles are returned by passing in one or more bundleID values in the request. The findBundles call can be used to find all product bundles associated with the seller's account, or specific product bundles can be returned based on bundleID, primarySKU, or bundle status. For findBundles, there is also an option to return a condensed version of product bundles by including and setting the bundleDetailSelector field to Summary.
To retrieve a product bundle by bundleID or primarySKU, include the bundleFilter container in findBundles and specify either a bundleFilter.bundleID or bundleFilter.primarySKU value. Both values can be used, but they should match. Multiple bundleFilter containers can be used in the same call.
To retrieve a product bundle based on bundle status, include the findAllByStatus field in findBundles and specify an BundleStatusEnum value.
Boolean OR logic is used when bundleFilter and findAllByStatus are both used. In other words, all product bundles matching the specified bundleID value(s), primarySKU value(s), or the BundleStatusEnum value, or any combination thereof, are returned in the output.
For retrieval calls, errors and/or warnings are only returned at the call level. If an error or warning appears at the call level, there is an issue with the call request. If there is no error or warning, it can be assumed that all product bundles matching the filter criteria were returned.
The following are some common errors that can occur when using the getBundles call:
The following are some common errors that can occur when using the findBundles call:
One or more product bundles can be deleted by using the deleteBundles call. In the deleteBundles call, one or more product bundles are deleted by passing in one or more bundleID values in the request.
Similar to the request of the createBundles call, errors and/or warnings can be returned at the call level and at the product bundle level. If an error or warning appears at the call level, there is an issue with the call request. If an error or warning occurs at the product bundle level (bundleStatus.errorMessage), there is an issue with the creation of that corresponding bundle (identified by bundleID).
If a product bundle is deleted successfully with a deleteBundles call, the following is returned under the bundleStatus container in the call response:
The following are some common errors that can occur when using the deleteBundles call:
As previously mentioned, this service allows sellers to create and manage discount campaigns. Discount campaigns allow sellers to offer discounts to buyers based on order size (number of items in order or total order value). To be eligible for a discount, buyers must purchase the primary product and at least one related item in a product bundle. Product bundles assist sellers in increasing sales by marketing related items to buyers.
| Use Case | Call | Notes |
|---|---|---|
| Create one or more discount campaigns | createCampaigns | Use one campaign node per discount campaign |
| Update one or more discount campaigns | updateCampaigns | Use one campaign node per discount campaign |
| Update the status of one discount campaign | setCampaignStatus | Pass in the campaignId value of the discount campaign to be changed, and include a valid campaigStatus value. |
| Delete one or more discount campaigns | deleteCampaigns | Pass in one or more campaignId values to delete the corresponding discount campaigns. |
| Retrieve one specific discount campaign | getCampaign | Pass in a valid campaignId value. |
| Retrieve all discount campaigns associated with seller's account | getCampaigns | Use no filters. |
| Retrieve one or more discount campaigns by date range | getCampaigns | Specify valid fromDate and toDate values. |
| Retrieve one or more discount campaigns by status | getCampaigns | Specify a valid CampaignStatusEnum value in the campaignStatus field. |
| Retrieve the current version of the service | getVersion | This call has no input fields. |
A campaign object is created with createCampaigns, updated with updateCampaigns, and retrieved with the getCampaign and getCampaigns calls. With the exception of createCampaigns, which doesn't use campaignId or offerId in the request (campaignId is returned under the campaignStatus container of the createCampaigns response), each of these four calls use each field in the Campaign type.
The unique identifier of a discount campaign is campaignId. A campaignId value is created by eBay and mapped to a discount campaign upon creation. A campaignId is required in updateCampaigns, and is always returned in the getCampaign and getCampaigns calls. campaignId values are also used as arguments in the deleteCampaigns, getCampaign, and setCampaignStatus calls.
The Campaign type contains the following fields and containers:
Multiple discount campaigns, each with multiple discount offers, can be created, updated, or retrieved with one Order Size Discounts call.
The two major components of a discount offer are the buyer condition and the discount terms. Multiple discount offers, each with different condition and discount term combinations, can be created for each discount campaign. An
The buyer condition for an offer is set with the offer.buyerCondition container in the createCampaigns request. The buyer condition is simply the number of related items a buyer must purchase or the amount of money that the buyer must spend on related items to qualify for the discount offer.
To set a buyer condition based on the number of related items purchased, include the offer.buyerCondition.orderSize container and set the number of items that the buyer must purchase with the fromSize and toSize fields.
To set a buyer condition based on the amount of money spent on the related items, include the offer.buyerCondition.orderTotal container and set the amount of money that the buyer must spend with the fromAmount and toAmount fields.
Discount offers are created using the offer.sellerOffer container in the createCampaigns request. The following is a summary of the type of discount offers that can be created:
When creating a discount campaign, a startDate and endDate must be specified. All active discount offers within the campaign will be valid during this defined time frame. The start time must be a date in the future and the end time must be a date later than the start time.
In the createCampaigns call, the common use case is to create a new discount campaign and have that discount campaign automatically activated once the startDate is reached. For this use case, the campaignStatus field is not necessary. However, there may a use case where a seller wants to create a new discount campaign, but does not want it active yet, even after the startDate is reached. In this case, the seller would include the campaignStatus field and set its value to ONHOLD or DRAFT.
The six discount campaign states are ACTIVE, SCHEDULED, ENDED, ONHOLD, DRAFT, and DELETED. ONHOLD and DRAFT are the only applicable CampaignStatusEnum values that are applicable for the createCampaigns call. However, there are use cases where the other values would be passed in an updateCampaigns or setCampaignStatus call, and any of the six values may be returned in a getCampaign or getCampaigns call.
If they occur, errors and/or warnings are returned at the call level and at the discount campaign level. If an error or warning appears at the call level, there is an issue with the call request. If an error or warning occurs at the discount campaign level, there is an issue with the creation of the discount campaign.
If a discount campaign is created successfully with a createCampaigns call, the following is returned under the campaignStatus container in the call response:
By default, all related items in a product bundle are eligible for discount offers, regardless of categories, product aspects, or SKU values. With the restriction container, the seller can include or exclude specific categories, specific category aspects, or specific SKU values from the discount campaign. When categories or products are included through the restriction container, these specified products are eligible for discount offers, and all other products that do not match the category ID, aspect, or SKU are not eligible for the discount. Conversely, when categories or products are excluded through the restriction container, the products that match the category ID, aspect, or SKU values are not eligible for the discount, and all other products are eligible for the discount. The include or exclude rule is set through the restriction.restrictionType field. Currently, only the include rule is available, so EXCLUDE is not a valid RestrictionTypeEnum value.
To specify a category to include or exclude from the discount campaign, pass in an eBay category ID in the restriction.categoryId field. Multiple eBay categories may be specified, each of them listed in separate restriction.categoryId fields.
To specify specific SKU values to include or exclude from the discount campaign, use the restriction.SKU container. Individual SKU values are passed in through one or more restriction.SKU.SKUs fields. Sellers also have the option of associating SKU values to an eBay category ID, essentially adding another layer to the filter criteria. Multiple restriction.SKU containers can be used in one call.
To specify specific product aspects to include or exclude from the discount campaign, use the restriction.aspect container. Individual aspect pairs are passed in through one or more restriction.aspect.aspects containers. Sellers also have the option of associating product aspects to an eBay category ID, essentially adding another layer to the filter criteria. Multiple restriction.aspect containers can be used in one call.
The following are some common errors that can occur when using the createCampaigns call:
One or more discount campaigns can be updated with the updateCampaigns call. The campaignId value is required to identify the discount campaign to be updated. Except for the campaignId or offerId values, any existing discount campaign data can be modified with the updateCampaigns call. Below are examples of changes that can be made with the updateBundles call:
If you only want to update the status of one or more discount campaigns, use the setCampaignStatus call.
You can use the updateCampaigns call to delete an individual offer within a discount campaign. First, the seller should verify that the right discount offer is about to be deleted by referencing and verifying the offer.offerId value. Once the discount offer is verified, include the campaign.offer.status field, and set its value to DELETED before running the call request.
The following are some common errors that can occur when using the updateCampaigns call:
The following are some common errors that can occur when using the setCampaignStatus call:
One or more discount campaigns can be retrieved by using the getCampaigns call. The getCampaigns call can be used to find all discount campaigns associated with the seller's account, or inclusion filters can be used. The filters of the getCampaigns call are discussed in the next section.
The getCampaign call retrieves one specific discount campaign, which is specified with a campaignId value in the request.
To retrieve all discount campaigns created within a date range, specify a date range in the getCampaigns request by including and setting fromDate and toDate values. The fromDate value must be older than the toDate value, and it cannot be set back more than 18 months in the past. The toDate field is optional. If it is omitted, all discount campaigns created from the fromDate up to the present (system date) are returned, unless the range specified by the fromDate and the present date is greater than 90 days, in which case the toDate defaults to 90 days forward from the fromDate.
To retrieve all discount campaigns in a particular status, include the campaignStatus field in getCampaigns and specify a CampaignStatusEnum value.
Boolean OR logic is used when the date range and campaign status filters are both used. In other words, all discount campaigns either created within the date range, matching the specified CampaignStatusEnum value, or meeting both criteria, are returned in the output.
For retrieval calls, errors and/or warnings are only returned at the call level. If an error or warning appears at the call level, there is an issue with the call request. If there is no error or warning, it can be assumed that all discount campaigns matching the filter criteria were returned.
The following are some common errors that can occur when using the getCampaigns call:
The following are some common errors that can occur when using the getCampaign call:
One or more discount campaigns can be deleted by using the deleteCampaigns call. In the deleteCampaigns call, one or more discount campaigns are deleted by passing in one or more campaignId values in the request.
To verify if the deleteCampaigns call was successful in deleting all specified discount campaigns, view the output and look for the campaignDeleteStatus field. This boolean field is returned as "true" if all discount campaigns passed into the request are successfully deleted. If one or more discount campaign deletions are unsuccessful, this field is not returned, and the caller will need to view any corresponding error messages in the response.
The following are some common errors that can occur when using the deleteCampaigns call:
Please refer to the API Call Limits page on the eBay Developer Network site for current default call limits and call limits for applications that have completed the Compatible Application Check, which is a free service that the eBay Developer Network provides to its members.
For more information about testing, refer to Testing Overview in the Making a Sales Maximizer APIs Call document.
Refer to the Call Reference for a list of calls in the Sales Maximizer APIs. The Call Reference includes the following information:
You can get more information about the eBay Sales Maximizer APIs at these locations:
Share tips or code samples related to this call or topic. Questions or observations are welcome, too.
eBay employees moderate these notes to ensure they are pertinent to the document and relevant to the community. Your submission will show up for all developers when it is activated by the moderator.
This documentation and the API may only be used in accordance with the eBay Developer Network and API License Agreement.
© 2009–2012 eBay Inc. All rights reserved.
eBay and the eBay logo are registered trademarks of eBay Inc.
All other brands are the property of their respective owners.
