Buy APIs Requirements

 

The use of eBay’s Buy APIs in production is intended for eBay partners only. Users must apply for production access through the eBay Partner Network. Acceptance of applications is based on the proposed business model, as well as a formal agreement to abide by the policies and requirements stipulated by eBay and PayPal. There is no guarantee that your application for production use of the APIs will be approved.

Using the APIs in sandbox

Anyone with an eBay developer account can use the Buy APIs in the sandbox with the exception of the methods in the checkout_session resource (i.e., methods used for eBay member checkout). If you are approved for production use of the Buy APIs for a member checkout use case, you will be granted access to use the member checkout methods in the sandbox, too. We advise you to complete the production application process and get approval before you invest significantly in application development and testing.

Beta launch phase

All of the eBay Buy APIs are beta releases, currently. This means, in short, that they are subject to change and that consumers may be asked to update their integration accordingly, depending upon the nature of the change. For details about the implications of different phases of eBay API releases, see API launch stages in the Using eBay RESTful APIs guide.

Production eligibility requirements

Users must meet standard eligibility requirements, get approvals from eBay support organizations, and sign contracts with eBay and PayPal to access the Buy APIs in production. Meeting the standard eligibility is not a guarantee that production access will be granted. See Production access process for additional information and instructions for requesting production access.

These requirements are grouped into:

Contractual requirements

Use of the eBay APIs in production requires the following accounts:

In addition to all the contracts and agreements associated with the accounts, such as the eBay User Agreement, API License Agreement, eBay Partner Network Agreement, and the PayPal User Agreement, there are contracts with eBay and PayPal that are specific to the eBay Buy APIs and your business model. If your application uses the guest checkout model, PCI compliance is required and there may be additional PayPal risk provisions and safeguards for your application and the API flow. You may also be required to sign Mutual Non-disclosure Agreements (MNDAs), depending upon your business model.

Also, if you want to download the item feed files or get paid for selling eBay items, you need to become an affiliate by joining the eBay Partner Network. For additional information, see Affiliate Marketing Resources.

Technical requirements

Depending upon your use case, your application must meet some or all of the following requirements:

  • Application must be fully functional and reviewable on the eBay sandbox
  • Application must implement affiliate tracking details (needed for revenue share capability)

Application requirements for checkout (Order API)

There are two types of checkouts; one for eBay members who are signed in and one of eBay guests who are anonymous. The following describes the requirements for these checkout types.

Application requirements for eBay member checkout (Order API)

To use the checkout_session resource, which supports eBay member checkout, you need approval. This approval will give you access for member checkout in both the sandbox and production API environment. To request approval, see Production access process.

The requirement for using the eBay member checkout will be communicated to you with your access approval. They will be similar to the requirements for the Application requirements for eBay guest checkouts. However, there could be additional requirements and some guest checkout requirements may not apply.

Application requirements for eBay guest checkouts (Order API)

The following describes the guest checkout payment flows supported by the Order API by resource:

  • guest_checkout_session - Lets eBay guests purchase items in the following ways:
    • Using the Order API guest flow, which lets eBay guests purchase items using a credit card, which is processed by PayPal.
    • Using the PayPal Smart Button flow, which lets eBay guests purchase items by direct debit or credit card or any payment method associated with their PayPal account.
  • proxy_guest_checkout_session - Using the vault provider flow, which lets eBay guests purchase items through vault provider, such as Braintree.

Partners must include the following data elements within the commerce flow and adhere to all use experience requirements detailed in the tables below.

User experience requirements for eBay guest checkouts

The following sections list the requirements browse, view item, Partner cart and checkout experiences by marketplace. For a list of marketplaces supported by the Buy APIs, see Buy API Support by Marketplace.

Note: The following user experience requirements apply to all guest checkouts except where noted.

User experience guest checkout item requirements

The following table lists what is required for the items on the browse/search for all marketplaces.


Fields Returned by Browse and Feed APIs

Fixed Price Items Required: Only surface FIXED PRICE items

Browse and Feed APIs: filter buyingOptions for FIXED_PRICE
Sort browse Prohibited: Disabling eBay's sort functionality. Partners and users are not permitted to sort items.
Note: The data provided is already sorted to present the most relevant/best match according to eBay's algorithms; further sorting would produce a sub-optimal experience.
Free Shipping Recommended: Surface only items offering free shipping

Browse API: filter maxDeliveryCost for 0
Delivery Country Required: Filter delivery country for domestic market
You can sell only items that are delivered within the same country as the marketplace of the item. For example, if the marketplace is EBAY_DE you can sell only items delivered in Germany.

Browse API: filter deliveryCountry
Feed API: filter shipToIncludedRegions

User experience guest checkout view item and Partner's cart pages

The following table lists the information required on the View Item and Partner's Cart pages for all marketplaces supported by the Order API.

 

AU Groceries

AU

CA

DE

ES

FR

GB

IT

US

Page

Fields Returned by Browse API

eBay Logo

View Item

Cart
Show the eBay logo

Provided by eBay (ebay-logos.zip).
eBay Item Image

View Item

Cart
Show an eBay image of the item
The image of the item must be an eBay image.

Response fields:

  • image.imageUrl
  • additionalImages.imageUrl

Title View Item

Cart
Show the title of the item

DE: Full title required.
Other sites: You can show a shorten version of the full title as long as the full title can be displayed if the buyer hovers over it.

ES, FR, GB, IT: Full title recommended

Response field = title

Price

View Item

Cart
Show the BIN (Buy It Now) Price

  • Shipping costs must always be called out separately. Even if it is free shipping.
  • DE: You must disclose that the cost includes any 'value added taxes' (VAT) see Value Added Tax below.

Response field = price

Recommended: Show strikethrough price / discount / savings

Response container = marketingPrice

Unit Price

 

       

 

View Item Show the unit price and unit measure when returned
This is returned only by some European marketplaces.

Response fields:

  • unitPrice
  • unitPricingMeasure
CA, ES, FR, GB, IT: Recommended
Description

View Item Show item description
You can show a shorten version of the description as long as there is a link to the full description.

Response fields:

  • description
  • shortDescription

For item variations that share the same description.

Response container = commonDescriptions

Quantity

View Item

Cart
Show the total number of items being purchased

Manually coded by partner.
Condition

 

View Item

Cart
Show item condition
You must indicate when the item is not new. Note: All items in the groceries category are new.

Response field = condition

Shipping Cost

View Item

Cart
Show shipping cost

Response field = shippingOptions[i].shippingCost


Note: This requires providing the buyer's US zip code in the X-EBAY-C-ENDUSERCTX contextualLocation request header.

Show domestic shipping only
You can sell only items that are delivered within the same country as the marketplace of the item. For example, if the marketplace is EBAY_DE you can sell only items delivered in Germany.

Exception on View Item page: Items on the US marketplace that are shippable or delivered to Taiwan can be shown.

Recommended: Show item location

Response fields:

  • itemLocation.city
  • itemLocation.country
Manually coded by partner.
Shipping Options    

View Item

Cart
Show shipping option
Show the shipping options.

Response container name = shippingOptions

CA, DE, ES, FR, GB, IT: This can be a link to this information.
Estimated Delivery Date              

View Item

Cart
Show estimated delivery date

Response fields:

  • shippingOptions.minEstimatedDeliveryDate
  • shippingOptions.maxEstimatedDeliveryDate

Note: For some shipping types these fields are null because the data is not available. When this happens, after the purchase is complete, you need to show the buyer the following.

To get the estimated date, click on the link in the purchase confirmation email from eBay. On the page that appears, you can contact the seller and ask them for the delivery date.


US: This requires providing the buyer's US zip code in the X-EBAY-C-ENDUSERCTX contextualLocation request header.

DE: This can be a link to this information.

CA, ES, FR, GB, IT: Recommended
Shipping Exclusions    

 

 

 

 

 

View Item Link to shipping exclusions

GB: Wherever "Free postage" is included, the "see exclusions" link must be added in close proximity to the postage information and the text must be red as required by Trading Standards.

DE, ES, FR, IT: Recommended

Manually coded by partner.
Payment Methods    

 

View Item

Cart
Show Available Payment Methods

CA, DE, ES, FR, GB, IT: You can use a link to this information so long as the payment information is also available at checkout out.

Manually coded by partner.
Seller Name

View Item

Cart
Show the eBay seller user name

Response field = seller.username

Strongly Suggested: Show Seller Ratings

Response fields:

  • seller.feedbackPercentage
  • seller.feedbackScore

Seller Terms and Conditions    

  View Item Show the seller's terms and conditions
This can be one click away if the link is transparent, such as labeled "Terms and Conditions" or grouped with the seller information under "legal information".

Response field: seller.termsOfService

CA, DE, ES, FR, GB, IT: This can be a link to this information.
Return Information    

View Item Show seller return information
This can be one click away if the link is transparent (i.e. labeled "returns policy" or grouped with seller information under "legal information".

Response container: returnTerms

DE, FR, GB: Must link to the seller's full return policy.
(EEK) European Energy Efficiency rating    

 

 

 

 

 

View Item Show the European energy efficiency rating

Response field = energyEfficiencyClass

ES, FR, GB, IT: Recommended
Value Added Tax      

          View Item

Cart
Show the Value Added Tax (VAT)
VAT is included in the price and does not need to be specifically stated.

DE: This must be shown like this:

In Footer: Links to eBay User Agreement and Partner's Privacy Policy

View Item

Cart
In the footer, include the following links:
  • Link to the eBay User Agreement
    For the link specific to the marketplace see, eBay and PayPal Disclosure Links.
  • Link to the Partner's privacy policy
    Partner's must create a privacy policy and provide the link to this document in the footer.
    For information about privacy policies, see the Protecting User Privacy section of the API License Agreement.

Manually coded by partner.

User experience guest checkout purchase page

The following table lists the information required on the checkout (Buy button) page for all marketplaces supported by the Order API.

 

Fields Returned by Order API Guest Methods

eBay Logo Show the eBay logo

Provided by eBay (ebay-logos.zip).
Seller Name Show seller name of each item in cart

Response field = lineItems[].seller.username

Title Show item title of each item in cart

Response field = lineItems[].title

Quantity Show quantity of each item in cart

Response field = lineItems[].quantity

Item Price Show price of each item in cart

Response field = lineItems[].netPrice

Total Shipping Cost Show shipping costs and delivery date
  • Show shipping options

       Response container name = shippingOptions

  • Show shipping address

       Response container name = shippingAddress

  • Show shipping cost

       Response field name = pricingSummary.deliveryCost

  • Show import charges

       Response field name = lineItems.shippingOptions.importCharges

  • Show estimated deliver date

    Response fields:

    • shippingOptions.minEstimatedDeliveryDate
    • shippingOptions.maxEstimatedDeliveryDate
Total Cost Show total cost of the order

Response field = pricingSummary.total

DE: You must disclose that the Total Cost includes any 'value added taxes' (VAT).

Requirements if there are import charges
  • You must show a breakdown of the shipping and import costs. At a minimum you must show the subtotal, shipping cost, import charges, and order total. You can also show additional cost breakdown, such as delivery discount, etc.

    Response fields:

    • subtotal = pricingSummary.total - pricingSummary.importCharge - pricingSummary.deliveryCost
    • shipping cost = pricingSummary.deliveryCost
    • import charges = pricingSummary.importCharges
    • order total = pricingSummary.total

  • You must show the buyer the details about the shipping and import costs and there must be a link to the eBay Global Shipping Program terms and conditions) https://pages.ebay.com/shipping/globalshipping/buyer-tnc.html). This information can be displayed in a pop-up.
The following are examples of the text:
  • This amount includes seller specified domestic shipping charges as well as applicable shipping and handling fees, but is independent of import charges. For additional information, see the Global Shipping Program terms and conditions.
  • This amount includes applicable customs duties, taxes, brokerage, and other fees. Exclusions apply. For additional details, see the terms and conditions.
"Buy" Button Page
eBay and PayPal Disclosure

(above "buy" button)

For an example, click here.

eBay and PayPal disclosures
eBay Disclosure

This requirement applies to the Order API guest flow and the vault provider flow guest checkout flows.


Required: Include the eBay disclosures above the buy button. This disclosure include links to the eBay User Agreement and Privacy Policy.

eBay disclosure text

By clicking <buy-button-name>, you agree to eBay's User Agreement and Privacy Policy.

 

PayPal Disclosure

This requirement applies only when using the Order API guest flow and is in addition to the eBay disclosure and links (described above).

Note: This does not apply to the PayPal Smart Button flow.

Required: Include the PayPal disclosures above the buy button. This disclosure includes links to the PayPal User Agreement and Privacy Policy.

PayPal disclosure text

By placing your order you authorize PayPal to process your payment, and you agree to PayPal's User Agreement and Privacy Policy.

Manually coded by partner.

For links to the eBay and PayPal User Agreements and Privacy Policies for specific marketplaces for see, eBay and PayPal Disclosure Links.

"Buy" Button Page
Marketing Consent Notice

(below "buy" button)
Marketing Consent Notice (all guest checkout flows)
There are three guest checkout flows; Order API guest flow, the PayPal Smart Button flow, and the vault provider flow.

Note: This requirement applies to all three guest checkout flows.

Required in guest place order methods:

  • Expose an expressed checkbox and the marketing consent message.
  • When the checkbox appears:
    • It is to be disabled (un-checked) for marketplaces other than the US.
    • For the US, the checkbox is to be enabled.

When buyer's are purchasing an item, you must give them the option to opt-in or opt-out-of receiving marketing messages from eBay. A checkbox and the following legal consent message must be included below the "buy" button. Note: The consent message is returned in the marketingMessages.legalMessage field by the guest initiate, get, and update methods.

I agree to receive marketing offers, promotions, and surveys from eBay through email.

Manually coded by partner.

In Footer: Links to eBay User Agreement and Partner's Privacy Policy Required: In the footer, include the following links:
  • Link to the eBay User Agreement
    For the link specific to the marketplace see, eBay and PayPal Disclosure Links.
  • Link to the Partner's privacy policy
    Partner's must create a privacy policy and provide the link to this document in the footer. For information about privacy policies, see the Protecting User Privacy section of the API License Agreement.

Manually coded by partner.

Guest checkout flow requirements

The following table lists the requirements for guest checkout flows for all marketplaces supported by the Order API.

 

Order API Guest Resources

Guest Purchase Order ID Do not show the purchase order ID to the buyer
This ID is used only by the partner in the getGuestPurchaseOrder method to retrieve the purchase order details.

Response field = purchaseOrderId

Buyer's Contact Information Provide buyer's email and their full billing and shipping address
This is needed to facilitate the checkout and post-transaction communication between the seller and buyer.

initiateGuestCheckoutSession and initiateProxyGuestCheckoutSession method request fields

Credit Card There are three guest checkout flows; Order API guest flow, the PayPal Smart Button flow, and the vault provider flow.
Required: For guest checkouts using either the Order API guest or the vault provider flow
  • Integrate with PayPal's risk management library (details provided upon execution of MNDA)
  • Full credit card data, including CSV or CVV, must be provided for every payment

Production access process

The following is the application process for obtaining production access.

  1. If you haven't already, sign up for an eBay Partner Network (EPN) account:
    • Ensure that the information you provide is accurate and be as thorough as possible when completing your application.
    • Read and understand the EPN Policies.
  2. Completely fill out and submit the Buy API Application.
    • Reply to the submission confirmation email and include mocks, data flows of your user experience, plus your certificate of PCI Compliance.
    • Within 10 business days, the eBay Partner Network will respond, approving or declining your application.
  3. If your business model is approved by the eBay Partner Network, open a support ticket with eBay Developer Support, using "Buy API Production Access (eBay User ID)" in the subject line. In the ticket, include the following:
    • EPN registered eBay user ID
    • Detailed instructions on how to access and test your application in Sandbox
    • The approval email from EPN as an attachment
  4. The eBay Developer Support team will initiate the application review/approval process:
    1. eBay Developer Support team reviews the application for compliance
    2. You must make changes as requested by the eBay Support team
    3. When the Support team is satisfied with your app, you are given eBay and PayPal contracts
    4. Upon return of signed contracts, the eBay Support team enables production access for your application