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 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:

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

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

 

User Experience Guest Checkout

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

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

   filter=deliveryCountry:DE

 

User Experience Guest Checkout
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
  • 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
  • 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

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 shipping domestically 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.

    Manually coded by partner.

  • Show estimated delivery date

    Response field names:

    • shippingOptions.minEstimatedDeliveryDate
    • shippingOptions.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
  • 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

In Footer
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.

 

User Experience Guest Checkout
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 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.

    Manually coded by partner.

  • Show estimated delivery date

    Response field names:

    • shippingOptions.minEstimatedDeliveryDate
    • shippingOptions.maxEstimatedDeliveryDate

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

In Footer
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.

 

User Experience Guest Checkout
Checkout Feature

Notes (including API Method or Manual Implementation)
Order API Guest Checkout 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

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:

    • shippingOptions.minEstimatedDeliveryDate
    • shippingOptions.maxEstimatedDeliveryDate
Total Cost 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 Contact Information Required: 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 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 flow 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
"Buy" Button Page
eBay and PayPal Disclosure

(above "buy" button)

For an example, click here.

eBay and PayPal disclosures (all guest checkout flows)
There are three guest checkout flows; Order API guest flow, the PayPal Smart Button flow, and the vault provider flow.

eBay Disclosure

Note: 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

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

Required: Include the PayPal disclosures above the buy button. This disclosure include 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: Expose an expressed checkbox and the marketing consent message.

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,

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

Note: There are different requirements for items purchased on the US and other eBay marketplaces.


Requirement for the EBAY_US marketplace:
  • The legal message and checkbox are optional until Q1 of 2019. After that, they will be required.
  • When the checkbox appears it is to be enabled (checked).

Requirement for all other marketplaces:
  • The legal message and checkbox are required.
  • When the checkbox appears it is to be disabled (un-checked).

Manually coded by partner.

In Footer
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.

 

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