Managing charitable listings

eBay for Charity gives sellers a formal way to donate a percentage of their listings' proceeds to supported charitable organizations.

Sellers can list items through the normal Sell Your Item flow on the eBay site, or through use of the Sell APIs. A seller selects a qualified charitable organization and specifies that a percentage of the item purchase price be used as a donation. After the item is purchased, the eBay for Charity provider bills the seller and sends the donation amount to the selected charitable organization on the seller's behalf. Charitable organizations can also list items on their own behalf through eBay for Charity.

Note: This feature also provides functionality that makes it easier for buyers to find items that are listed by charitable organizations, or that benefit charitable organizations. For more information, see the Charity API section of the Buying Integration Guide.

Refer to the following sections for more information about:

Retrieving charitable organization details

Sellers can use the following methods to search for supported charitable organizations and charitable organization details:

  • getCharityOrg – This call is used to retrieve detailed information about charitable organizations that are registered with the eBay for Charity program. It allows sellers to retrieve the details for a specific charitable organization using its charity organization ID.
  • getCharityOrgs – This call is used to search for charitable organizations that are registered with the eBay for Charity program. It allows sellers to search for a specific charitable organization, or for multiple charitable organizations, from a particular charitable domain and/or geographical region, or by using search criteria.
  • getCharityOrgByLegacyId – This call is used to retrieve detailed information about charitable organizations that are registered with the eBay for Charity program. It allows users to retrieve the details for a specific charitable organization using its legacy charity ID, which has also been referred to as the charity number, external ID, and PayPal Giving Fund ID. The legacy charity ID is separate from eBay’s generic charity ID.

These methods are outlined in the use cases that follow.

Note: The marketplace ID is required when using these methods. Currently, the Charity API is supported through the UK and US marketplaces only.

Search for supported charitable organizations

Sellers can search for charities using a set of keywords for a specific marketplace or by using registration IDs. The search returns a paginated list of available charities for that marketplace.

This sample retrieves the search results for 3 charitable organizations that match the Red Cross query string:

/commerce/charity/v1/charity_org/?q=red cross&limit=3

This sample retrieves the search results for the charitable organization that matches the 340709901 registration ID:

/commerce/charity/v1/charity_org/?registration_ids=340709901

Retrieve charitable organization details

Sellers can retrieve the full details for a specific charitable organization using its charity organization ID or its legacy charity organization ID. These details include:

  • The name, description, and mission statement for the organization
  • The organization and registration IDs (EIN)
  • The logo, location, and website URL for the organization

This sample retrieves detailed information for the supported charitable organization that matches the 302 charity ID:

/commerce/charity/v1/charity_org/302

Adding a charitable listing

Whether the seller is only going to contribute a percentage of the proceeds to a registered charitable organization, or the seller is a charitable organization direct-seller, the Charity container must be included in a createOffer call to indicate:

  • charityId – The eBay-assigned unique identifier of the charitable organization that will receive a percentage of the sales proceeds.
  • donationPercentage – The percentage of the purchase price that the charitable organization will receive for each sale that the listing generates.

Note: The createOffer call only stages an offer for publishing. The seller must run the publishOffer call to convert the offer to an active eBay listing. See the Managing Offers section of this Seller Integration Guide for more information.

Revising a listing to add charity

For sellers who want to update an existing offer to add a registered charitable organization, the updateOffer call can be used. Similar to adding a charitable listing, the Charity container fields must be included in the call.

When revising a listing, the existing offer can be in either the published state (active eBay listing), or in an unpublished state and yet to be published with the publishOffer call.