Charity API

Many buyers are dedicated to charitable giving for a variety of personal and financial reasons. Some buyers 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.

The eBay Charity API provides buyers a formal way to search for supported charitable organizations and charitable organization details, which can help integrate the donation process directly into regular business processes.

Charity API methods overview

The Charity API has the following methods:

• getCharityOrg – This method is used to retrieve detailed information about charitable organizations that are registered with the eBay for Charity program. It allows buyers to retrieve the details for a specific charitable organization using its charity organization ID.
• getCharityOrgs – This method is used to search for charitable organizations that are registered with the eBay for Charity program. It allows buyers 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 method 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.

Charity API functionality

The eBay Charity API supports the following general use cases: 

• Search for supported charitable organizations
• Retrieve charitable organization details

Search for supported charitable organizations

Buyers 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

Buyers 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

Charity API usage

After using the Charity API methods to retrieve the details for supported charitable organizations, buyers can leverage the eBay Browse API to search for listings that support a specific charitable organization.

For example, you can use the item_summary resource to run a search for available listings filtered through the charity_ids container. The charity_ids string value can include one charity registration ID, or a comma-separated list of IDs, and limits the results to only the items associated with the specified charitable organization. You can also use any combination of the category_ids and q fields along with charity_ids to filter your search, which gives you additional control over the result set.

This sample retrieves paginated search results for listings associated with the 13-1788491 and 300108469 charity IDs:

/buy/browse/v1/item_summary/search?charity_ids=13-1788491,300108469

For more information, see the Browse API section of this Buying Integration Guide.