Sales Maximizer APIs

Sales Maximizer APIs Users Guide

Sales Maximizer Service Introduction

Sales Maximizer helps sellers upsell related items by creating and managing product bundles.

Benefits of Using Sales Maximizer

Some of the benefits to using this service are:

Seller

Buyer

Prerequisite

The following lists the prerequisites for using this service.

Current Limitations

The following are the limitations as of June 2013.

Also see Important Things to Note when using Sales Maximizer.

Related Items Management Service Overview Version 1.0.0

Related Items Management is a service that is intended to be consumed by sellers in the US and UK. 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, there is a getVersion call that returns the current version of the service.

Refer to the Related Items Management API API Reference documentation for detailed information on each call, including input fields, output fields, and samples.

Note: The primary item in a related items offer can carry a shipping cost. However, all related items must offer free shipping as one of the domestic shipping options. The related items listings can charge a fee for international shipping. Make sure you offer the same class of service on the primary item as the related item's service that has free shipping to consolidate bundled purchases into one order, so you can ship the order in one box and reduce your shipping costs.

For example, a buyer purchases a camera that offers standard shipping for $5 and additional related items that offer standard shipping for free, when the buyer completes the purchase all items will be consolidated into a single order with a total shipping cost of $5 for standard shipping.

Tips for Creating Successful Related Item Offers

Related Items Management Use Cases

The following table lists the 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.

Creating a Product Bundle

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.

For information about the fields in the Bundle type, see the Bundle Type API Reference page.

Multiple product bundles can be created, updated, or retrieved with one Related Items Management call.

Creating Product Groups

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).

Bundle States and Lifecycles

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.

The Successful Creation of Product Bundles

For creation calls, 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:

Common Errors/Mistakes for createBundles Call

The following are some common errors that can occur when using the createBundles call:

Updating a Product Bundle

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.

Common Errors/Mistakes for updateBundles Call

The following are some common errors that can occur when using the updateBundles call:

Common Errors/Mistakes for updateBundleStatus Call

The following are some common errors that can occur when using the updateBundleStatus call:

Retrieving a Product Bundle

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.

Using Filters in findBundles

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 both values must be valid for the same bundle. 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 a 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.

The Successful Retrieval of Product Bundles

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.

Common Errors/Mistakes for getBundles Call

The most common errors that can occur when using the getBundles is call the bundleID value(s) are missing or invalid.

Common Errors/Mistakes for findBundles Call

The most common errors that can occur when using the findBundles call is invalid values for bundleID, primarySKU, or BundleStatusEnum.

Deleting Product Bundles

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:

Common Errors/Mistakes for deleteBundles Call

The most common errors that can occur when using the deleteBundles call is the bundleID value(s) are missing or the values is invalid.

Important Things to Note

The following are things that are important to remember when using the Sales Maximizer.

Discounts

Listings

Refunds

If the buyer exercises his right to cancel his order and return one or more of the items in a Special Offer, the seller shall refund the buyer at least the weighted discounted value of the item being returned. For items purchased as part of a Special Offer, the returns policy specified in each individual listing will apply to the return of each respective item. If a seller's return policy for an item permits returns, the item price that the seller reimburses the buyer must at a minimum be the cost-weighted discounted price of the returned item as displayed in My eBay. For example, a buyer purchases a TV for $900 and adds a $100 Blu-ray player to his order to get a $50 discount as a part of your related items offer; $45 discount was applied to the TV and $5 discount was applied to the Blu-ray player. If the buyer returns the TV, but keeps the Blu-ray player, you should refund him $900-$45 = $855.

Shipping

Back to top

Working with the Sales Maximizer

The following section contains links to other information you might need in order to use the APIs in Sales Maximizer.

API Call Limits

Please refer to the API Call Limits page on the eBay Developer Program 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 Program provides to its members.

Sandbox Environment

For more information about testing, refer to Testing Overview in the Making a Sales Maximizer APIs Call document.

Additional Resources

You can get more information about the eBay Sales Maximizer APIs at these locations:

Copyright © 2009–2016 eBay, Inc. All rights reserved. This documentation and the API may only be used in accordance with the eBay Developers Program and API License Agreement.