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)
  • If your application supports guest checkout, the following requirements apply:
    • Application must 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
    • Full billing and shipping address must be provided for every payment

Application requirements for checkout_session resource (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 guest_checkout_session resource. However, there could be additional requirements and some guest checkout requirements may not apply.

Application requirements for guest_checkout_session resource (Order API)

Partners must include the following data elements within the commerce flow and adhere to all other requirements detailed below.

User Experience
Browse API and Feed API Methods

Notes (including API Method or Manual Implementation)
Browse and Feed API

Fixed Price Items Required: Only surface FIXED PRICE items

filter=buyingOptions:{FIXED_PRICE}

Sort Required: Disable sort functionality: Partner 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 Strongly Suggested: Surface only items offering free shipping

   filter=maxDeliveryCost:0

Delivery Country Required: Filter Delivery Country for domestic market

   You can sell only items that are in and delivered within the same country. Cross-border transaction are not supported.

   filter=deliveryCountry:US
   filter=deliveryCountry:DE

 

User Experience
eBay View Item Page

Notes (including API Method or Manual Implementation)
Browse API Methods

eBay logo Required: Show eBay logo
  • For Guest checkout: at View Item screen.
  • For Universal Checkout: at View Item, Cart, and Checkout.

Provided by eBay (ebay-logos.zip).

Seller Required:
  • Show eBay seller user name

       Response field name = seller.username

  • For GB and DE marketplaces, show all the seller's business information

    This can be done using a hyperlink or behind labeled collapsible text.

       Response container name = seller.sellerLegalInfo

Strongly Suggested: Show Seller Ratings

   Response field names = seller.feedbackPercentage and seller.feedbackScore

Item Title Required: Show item title

   Response field name = title

Item description Required: Show Item Description

   Response field name = description or for item variations that share the same description the commonDescriptions container.

EEK (Energy Efficiency Rating) Required: Show EEK when returned

   This is returned only by some European countries.

   Response field name = energyEfficiencyClass

Base Unit Price (BUP) and unit measure

Required: Show BUP when returned

   This is returned only by some European countries. The BUP is calculated using a measurement, such as weight, volume, etc.

   Response field names = unitPrice and unitPricingMeasure

Condition Required: Show item condition

   Response field name = condition

Item Cost Required: Show item cost

   Response field name = price

   Note:

  • Shipping costs must always be called out separately (even if it is to say ‘free shipping’).
  • When using the Germany site (DE marketplace) you must disclose that the cost includes any 'value added taxes' (VAT).


Strongly Suggested:
Show strikethrough price / discount / savings

   Response container name = marketingPrice

Payments Strongly Suggested: Show that transaction will be processed by credit card only.

   Manually coded by partner.

Shipping Required:
  • Show shipping options

    Response container name = shippingOptions

  • Show shipping cost

    Response field name = 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 in and delivered within the same country. Cross-border transaction are not supported.

    Manually coded by partner.

  • Show estimated delivery date

       Response field names = shippingDetail.minEstimatedDeliveryDate and shippingDetail.maxEstimatedDeliveryDate

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


Strongly Suggested: Show item location

   Response field names = itemLocation.city and itemLocation.country

Returns policy Required: Show seller's return policy

   Response container name = returnTerms

   Note: Can be accessed through a hyperlink or behind labeled collapsible text.

Report Item Required: Surface a "Report Item on eBay" hyperlink

   This link takes the buyer to the View Item page on eBay. From there they can report any issues to eBay.

   Response field name = itemWebUrl

eBay User Agreement and
eBay Privacy Policy
Required: In the footer, include links to eBay agreement and privacy policy pages.

   https://pages.ebay.com/help/policies/user-agreement.html
   https://pages.ebay.com/help/policies/privacy-policy.html

   Manually coded by partner.

 

User Experience
Cart Feature

Notes (including API Method or Manual Implementation)
Browse API item Resource Methods

eBay Logo Required: For universal checkout

   Provided by eBay (ebay-logos.zip).

Seller Required: Show eBay seller user name

   Response field name = seller.username

Item Title Required: Show item title

   Response field name = title

Quantity

Required: Show the total number of items being purchased.

   Manually coded by partner.

Item Price Required: Show item cost

   Response field name = price

   Note:

  • Shipping costs must always be called out separately (even if it is to say ‘free shipping’).
  • When using the Germany site (DE marketplace) you must disclose that the cost includes any 'value added taxes' (VAT).

Shipping Required: Show shipping cost
  • Show shipping options

       Response container name = shippingOptions

  • Show shipping cost

       Response field name = 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 in and delivered within the same country. Cross-border transaction are not supported.

       Manually coded by partner.

  • Show estimated delivery date

       Response field names = shippingDetail.minEstimatedDeliveryDate and shippingDetail.maxEstimatedDeliveryDate

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

eBay User Agreement and
eBay Privacy Policy
Required: In the footer, include links to eBay agreement and privacy policy pages.

   https://pages.ebay.com/help/policies/user-agreement.html
   https://pages.ebay.com/help/policies/privacy-policy.html

   Manually coded by partner.

 

User Experience
Checkout Feature

Notes (including API Method or Manual Implementation)
Order API guest_checkout_session and guest_purchase_order Resource Methods

Seller Required: Show seller name

   Response field name = lineItems[].seller.username

Item Title Required: Show item title

   Response field name = lineItems[].title

Quantity Required: Show quantity

   Response field name = lineItems[].quantity

Item Price Required: Show price of each item in cart

   Response field name = lineItems[].netPrice

Payments Required: Show that the transaction will be processed by credit card only.

   Manually coded by partner.

Total Shipping Required: Show shipping cost
  • Show shipping options

       Response container name = shippingOptions

  • Show shipping address

       Response container name = shippingAddress

  • Show shipping cost

       Response field name = pricingSummary.deliveryCost

  • Show estimated deliver date

       Response field names = shippingDetail.minEstimatedDeliveryDate and shippingDetail.maxEstimatedDeliveryDate

Total Cost (Item Prices + Shipping + Tax) Required: Show total cost

   Response field name = pricingSummary.total

Note: When using the Germany site (DE marketplace) you must disclose that the Total Cost includes any 'value added taxes' (VAT).

   Total Cost (Item Prices + Shipping + Tax + VAT)

Guest Purchase Order ID Required: 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 name = purchaseOrderId

Buyer's email address Required: Provide buyer's email

   This is needed to facilitate post-transaction communication between the seller and buyer.

   initiateGuestCheckoutSession method request field name = contactEmail

eBay User Agreement and
eBay Privacy Policy
Required: The following disclosure, which includes the links to eBay agreement and privacy policy pages.

   https://pages.ebay.com/help/policies/user-agreement.html
   https://pages.ebay.com/help/policies/privacy-policy.html

Disclosure text
"By clicking Purchase, you agree that you've read and accepted eBay's User Agreement and you consent to eBay's Privacy Notice."

  • Disclosure must be placed immediately before the "Purchase" method to action.
  • Manually coded by partner.
Marketing Consent

US marketplace
Optional until Q1 2019: The following consent message and a checkbox must be included below the "Buy" button for items on the EBAY_US - eBay USA (ebay.com) marketplace.

"I would like to receive exclusive promotions, offers, and surveys from eBay."

Important! When the checkbox appears it is to be enabled (checked).

Marketing Consent

DE and GB marketplaces
Required: The following consent message and a checkbox must be included below the "Buy" button for items on the EBAY_DE - eBay Germany (ebay.de) and EBAY_GB - eBay Great Britain (ebay.co.uk) marketplaces.

"I would like to receive emails about promotions, special offers, and surveys."

Important! When the checkbox appears it is to be disabled (un-checked).

 

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, dataflows 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 (<4‑digit EPN code>)" in the subject line. In the ticket, include the following:
    • 4‑digit EPN code
    • EPN registered email address (or eBay user ID, if registered with an eBay account)
    • Detailed instructions on how to access and test the 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