charity APIv1.2.0

Charity API

The eBay Charity API provides buyers and sellers a formal way to search for supported charitable organizations and charitable organization details.

Note: Currently, the Charity API is supported through the UK and US marketplaces only.

This overview covers the following topics:

For more information about using RESTful APIs, see Using eBay Restful APIs.

Technical overview

The Charity API allows third-party developers to search for supported charitable organizations and to access the details for those charitable organization using the primary methods and fields listed in the sections that follow.

Primary methods

The primary methods used for the Charity API are:

  • getCharityOrg – 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 charity organization ID.
  • getCharityOrgs – This call is used to search for charitable organizations that are registered with the eBay for Charity program. It allows users 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.

Primary fields

The primary fields used in the Charity API methods are:

  • Organization ID – The charityOrgId field contains the ID of the charitable organization.
  • Legacy Organization ID – The legacy_charity_org_id URI parameter contains the legacy ID of the charitable organization.
  • Description – The description field contains the description of the charitable organization.
  • Location – The location field contains the location details of the charitable organization, such as city, state, and geo-coordinates.
  • Logo – The logoImage field contains the logo details for the charitable organization, such as image size and URL.
  • Mission Statement – The missionStatement field contains the mission statement for the charitable organization.
  • Name – The name field contains the name of the charitable organization.
  • Registration ID – The registrationId field contains the registration ID of the charitable organization (EIN number).
  • Website – The website field contains a link to the charitable organization website.

Business use cases

Many buyers and sellers are dedicated to charitable giving for a variety of personal and financial reasons. Some buyers and sellers are particularly interested in donating to specific charitable organizations. Others just like to donate in general. A buyer may choose to do more business with charitable organizations, as well as sellers who give to charitable organizations or who support the same causes as the buyer.

Your application can benefit in several ways by retrieving the eBay Charity information. For example:

  • Integrate the donation process directly into regular business processes.
  • Include information about a listing's benefiting nonprofit organization when presenting the listing to users.

See the following sections for the high-level use cases addressed by the Charity API.

Retrieve a list of charities

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

Note: The marketplace ID is required when using this method. Field groups and filters are also supported.

Retrieve charity details

Users 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

Note: The marketplace ID is required when using this method. Field groups and filters are also supported.

API restrictions

This section outlines the restrictions for use of the eBay Charity API.

Supported marketplaces

Currently, the Charity API is supported in the UK and US marketplaces.

Sandbox vs. Production data

The data in the eBay Sandbox environment is static. It can be limited in scope and quantity, and is sometimes simulated or mock data. As a result, you should not depend on data in the Production environment to have the same limitations. Use good coding practices to anticipate the wider range and variability of data that your application is likely to encounter.