openapi: 3.0.0
info:
title: Charity API
description: The Charity API allows third-party developers to search for and access details on supported charitable organizations.
contact:
name: eBay Inc,
license:
name: eBay API License Agreement
url: https://go.developer.ebay.com/api-license-agreement
version: v1.2.1
servers:
- url: https://api.ebay.com{basePath}
description: Production
variables:
basePath:
default: /commerce/charity/v1
paths:
/charity_org/{charity_org_id}:
get:
tags:
- charity_org
description: This call is used to retrieve detailed information about supported charitable organizations. It allows users to retrieve the details for a specific charitable organization using its charity organization ID.
operationId: getCharityOrg
parameters:
- name: charity_org_id
in: path
description: The unique ID of the charitable organization.
required: true
schema:
type: string
- name: X-EBAY-C-MARKETPLACE-ID
in: header
description: A header used to specify the eBay marketplace ID.
Valid Values: EBAY_GB
and EBAY_US
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CharityOrg'
'400':
description: Bad Request
x-response-codes:
errors:
'165001':
domain: API_CHARITY
category: REQUEST
description: Invalid, missing or unsupported marketplace. Please refer to documentation.
'404':
description: Not found
x-response-codes:
errors:
'165002':
domain: API_CHARITY
category: REQUEST
description: Charity Org Id is invalid or missing.
'500':
description: Internal Server Error
x-response-codes:
errors:
'165000':
domain: API_CHARITY
category: APPLICATION
description: There was a problem with an eBay internal system or process. Contact eBay developer support for assistance.
security:
- api_auth:
- https://api.ebay.com/oauth/api_scope
/charity_org:
get:
tags:
- charity_org
description: This call is used to search for supported charitable organizations. 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.
The call returns paginated search results containing the charitable organizations that match the specified criteria.
operationId: getCharityOrgs
parameters:
- name: limit
in: query
description: The number of items, from the result set, returned in a single page.
Valid Values: 1-100
Default: 20
required: false
schema:
type: string
- name: offset
in: query
description: The number of items that will be skipped in the result set. This is used with the limit field to control the pagination of the output.
For example, if the offset is set to 0
and the limit is set to 10
, the method will retrieve items 1 through 10 from the list of items returned. If the offset is set to 10
and the limit is set to 10
, the method will retrieve items 11 through 20 from the list of items returned.
Valid Values: 0-10,000
Default: 0
required: false
schema:
type: string
- name: q
in: query
description: A query string that matches the keywords in name, mission statement, or description.
required: false
schema:
type: string
- name: registration_ids
in: query
description: 'A comma-separated list of charitable organization registration IDs.
Note: Do not specify this parameter for query-based searches. Specify either the q or registration_ids parameter, but not both.
Maximum Limit: 20
'
required: false
schema:
type: string
- name: X-EBAY-C-MARKETPLACE-ID
in: header
description: A header used to specify the eBay marketplace ID.
Valid Values: EBAY_GB
and EBAY_US
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CharitySearchResponse'
'400':
description: Bad Request
x-response-codes:
errors:
'165001':
domain: API_CHARITY
category: REQUEST
description: Invalid, missing or unsupported marketplace. Please refer to documentation.
'165003':
domain: API_CHARITY
category: REQUEST
description: The specified limit is invalid. Maximum value supported is 100.
'165004':
domain: API_CHARITY
category: REQUEST
description: The specified offset is invalid.
'165005':
domain: API_CHARITY
category: REQUEST
description: Please specify registration_ids OR query text for the search.
'500':
description: Internal Server Error
x-response-codes:
errors:
'165000':
domain: API_CHARITY
category: APPLICATION
description: There was a problem with an eBay internal system or process. Contact eBay developer support for assistance.
security:
- api_auth:
- https://api.ebay.com/oauth/api_scope
components:
schemas:
Address:
type: object
properties:
city:
type: string
description: The city of the charitable organization.
stateOrProvince:
type: string
description: The state or province of the charitable organization.
postalCode:
type: string
description: The postal code of the charitable organization.
country:
type: string
description: The two-letter ISO 3166 standard of the country of the address. For implementation help, refer to eBay API documentation
description: The physical location of the item.
CharityOrg:
type: object
properties:
charityOrgId:
type: string
description: The ID of the charitable organization.
description:
type: string
description: The description of the charitable organization.
location:
description: The location details of the charitable organization.
$ref: '#/components/schemas/Location'
logoImage:
description: The logo of the charitable organization.
$ref: '#/components/schemas/Image'
missionStatement:
type: string
description: The mission statement of the charitable organization.
name:
type: string
description: The name of the charitable organization.
registrationId:
type: string
description: The registration ID for the charitable organization.
Note: For the US marketplace, this is the EIN.
website:
type: string
description: The link to the website for the charitable organization.
description: The full location, ID, logo and other details of the charity organization.
CharitySearchResponse:
type: object
properties:
charityOrgs:
type: array
description: The list of charitable organizations that match the search criteria.
items:
$ref: '#/components/schemas/CharityOrg'
href:
type: string
description: The relative path to the current set of results.
limit:
type: integer
description: The number of items, from the result set, returned in a single page.
Valid Values: 1-100
Default: 20
format: int32
next:
type: string
description: The relative path to the next set of results.
offset:
type: integer
description: The number of items that will be skipped in the result set. This is used with the limit field to control the pagination of the output.
For example, if the offset is set to 0
and the limit is set to 10
, the method will retrieve items 1 through 10 from the list of items returned. If the offset is set to 10
and the limit is set to 10
, the method will retrieve items 11 through 20 from the list of items returned.
Valid Values: 0-10,000
Default: 0
format: int32
prev:
type: string
description: The relative path to the previous set of results.
total:
type: integer
description: The total number of matches for the search criteria.
format: int32
description: A single set of search results, with information for accessing other sets.
Error:
type: object
properties:
category:
type: string
description: Identifies the type of erro.
domain:
type: string
description: Name for the primary system where the error occurred. This is relevant for application errors.
errorId:
type: integer
description: A unique number to identify the error.
format: int32
inputRefIds:
type: array
description: An array of request elements most closely associated to the error.
items:
type: string
longMessage:
type: string
description: A more detailed explanation of the error.
message:
type: string
description: Information on how to correct the problem, in the end user's terms and language where applicable.
outputRefIds:
type: array
description: An array of request elements most closely associated to the error.
items:
type: string
parameters:
type: array
description: An array of name/value pairs that describe details the error condition. These are useful when multiple errors are returned.
items:
$ref: '#/components/schemas/ErrorParameter'
subdomain:
type: string
description: 'Further helps indicate which subsystem the error is coming from. System subcategories include: Initialization, Serialization, Security, Monitoring, Rate Limiting, etc.'
description: This type defines the fields that can be returned in an error.
ErrorParameter:
type: object
properties:
name:
type: string
description: The object of the error.
value:
type: string
description: The value of the object.
GeoCoordinates:
type: object
properties:
latitude:
type: number
description: The latitude component of the geographic coordinate.
longitude:
type: number
description: The longitude component of the geographic coordinate.
description: Defines the format of a geographic coordinate.
Image:
type: object
properties:
height:
type: string
description: The height of the logo image.
imageUrl:
type: string
description: The URL to the logo image location.
width:
type: string
description: The width of the logo image.
description: The logo of the charitable organization.
Location:
type: object
properties:
address:
description: The address of the charitable organization.
$ref: '#/components/schemas/Address'
geoCoordinates:
description: The geo-coordinates of the charitable organization.
$ref: '#/components/schemas/GeoCoordinates'
securitySchemes:
api_auth:
type: oauth2
description: The security definitions for this API. Please check individual operations for applicable scopes.
flows:
clientCredentials:
tokenUrl: https://api.ebay.com/identity/v1/oauth2/token
scopes:
https://api.ebay.com/oauth/api_scope: View public data from eBay