The Compliance API is used to retrieve listing violations for five different compliance types. Once listing violations are discovered in active listings for the seller, it is up to the seller to make revisions to these listings to correct the listing violations. The five different listing compliance types are summarized below:
- Product Adoption: this compliance type is used to see if any listings (or variations within multiple-variation listings) are violating eBay's Product-Based Shopping Experience (PBSE) requirement. Beginning with Phase 1 in May 2018, some eBay categories and product brands now require that sellers list those products using an eBay catalog product. If a seller does not use a catalog product for categories/brands applicable to the PBSE requirement, a create or revise listing action may be blocked, or the listing will not surface in the product-based search results. For more information on Product-Based Shopping Experience , see the Product-Based Shopping Experience Playbook. The Product Adoption compliance type also applies to any listings (or variations within multiple-variation listings) that are missing product identifiers in item specifics, and when variations within multiple-variation listings are wrongfully sharing the same identifier values. In the API interface, the enumeration value for this compliance type is
- HTTPS protocol: this compliance type is used to see if any listings are violating eBay's policy of using HTTP links in the listing description instead of HTTPS links. This requirement includes links to externally-hosted listing images. If the server hosting the listing images does not support the HTTPS protocol, this server cannot be used to host listing images. In the API interface, the enumeration value for this compliance type is
- Non-eBay Links: this compliance type is used to see if any listings are violating eBay's policy of not allowing links in the listing description to sites outside of eBay. The seller including a personal email address and/or a phone number in the listing description is also a violation of this policy. All communication between seller and buyers should be handled through eBay's communication system. The only exceptions to this outside links rule are links to product videos, information on freight shipping services, or any legally required information. In the API interface, the enumeration value for this compliance type is
- Return Policy: this compliance type is used to see if any listings have return periods that are no longer supported. Recently, many eBay sites (including US) deprecated the 14-day return period, so the minimum return period is now 30 days for many eBay sites. In the API interface, the enumeration value for this compliance type is
- Product Adoption Conformance: this compliance type is used to see if any details of product-based listings (associated with an eBay catalog product) are out of synch with the eBay catalog product that the listing (or variation) is based upon. Four types of violations (and associated messages) may get returned for this compliance type, including 'product mismatch' (listing may be associated with wrong product), 'title mismatch' (listing title and catalog product title not aligned), 'item specifics mismatch' (Item Specifics in listing and catalog product not aligned), or 'price or condition mismatch' (price and condition don't match what is expected based on catalog product). In the API interface, the enumeration value for this compliance type is
The Compliance API has the following two methods:
- getListingViolationsSummary: this method returns the number of active listings that are currently violating one or more compliance types. Results are grouped by each unique eBay marketplace and compliance type combination.
- getListingViolations: this method returns data on each listing violation in the seller's active listings. Results are grouped by listing, so if one eBay listing has multiple listing violations for a specific compliance type, these violations will be shown together. Only one compliance type can be used per call.
This overview covers the following Compliance API topics:
The Compliance API is a REST-based API that retrieves listing violations for any eBay listings, regardless of which user interface, tool, or API was used to create those listings. For those who are new to using eBay RESTful APIs, it is recommended that you read the Using eBay RESTful APIs document, which summarizes eBay developer account requirements, OAuth access tokens, handling error messages, and more.
The getListingViolations method is enabled with pagination control. With pagination control, the user can set a limit of the number of listing violations returned per page of data, and can use an offset query parameter to scroll through multiple pages of results (if applicable).
Business use cases
Below are the high-level use cases addressed by the Compliance API.
- Retrieve the number of active listings that have one or more listing violations.
- Retrieve data on all listing violations. The retrieved data includes the unique identifier of the eBay listing (and unique identifier of variation, if applicable) and details on the listing violation. Once the seller has this information on listing violation(s), the seller can use the createOrReplaceInventoryItem method of the Inventory API or ReviseItem/ReviseFixedPriceItem call of the Trading API to revise these listings.
Compliance API requirements and restrictions
To use the Compliance API (or any other eBay public API), the user must have an eBay Developers Program account. If you already have an account, but have never used eBay RESTful APIs, there are additional requirements that are covered in the Using eBay RESTful APIs document.
The Compliance API is supported on all eBay marketplaces that have API support and that require product identifiers based on the eBay Category. However, only five sites (US, UK, CA, AU, and DE) will start requiring eBay catalog products for limited categories/brands in 2018, so the 'EPID Required' listing violation will only be applicable to those five sites.