{
"swagger": "2.0",
"info": {
"description": "The Charity API allows third-party developers to search for and access details on supported charitable organizations.",
"version": "v1.2.1",
"title": "Charity API",
"contact": {
"name": "eBay Inc,"
},
"license": {
"name": "eBay API License Agreement",
"url": "https://go.developer.ebay.com/api-license-agreement"
}
},
"host": "api.ebay.com",
"basePath": "/commerce/charity/v1",
"schemes": [
"https"
],
"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",
"produces": [
"application/json"
],
"parameters": [
{
"name": "charity_org_id",
"in": "path",
"description": "The unique ID of the charitable organization.",
"required": true,
"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,
"type": "string"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/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": [
{
"Client Credentials": [
"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",
"produces": [
"application/json"
],
"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,
"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,
"type": "string"
},
{
"name": "q",
"in": "query",
"description": "A query string that matches the keywords in name, mission statement, or description.",
"required": false,
"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,
"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,
"type": "string"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/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": [
{
"Client Credentials": [
"https://api.ebay.com/oauth/api_scope"
]
}
]
}
}
},
"securityDefinitions": {
"Client Credentials": {
"description": "The security definitions for this API. Please check individual operations for applicable scopes.",
"type": "oauth2",
"tokenUrl": "https://api.ebay.com/identity/v1/oauth2/token",
"flow": "application",
"scopes": {
"https://api.ebay.com/oauth/api_scope": "View public data from eBay"
}
}
},
"definitions": {
"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": {
"$ref": "#/definitions/Location"
},
"logoImage": {
"$ref": "#/definitions/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": "#/definitions/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
"
},
"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
"
},
"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."
}
},
"description": "A single set of search results, with information for accessing other sets."
},
"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": {
"$ref": "#/definitions/Address"
},
"geoCoordinates": {
"$ref": "#/definitions/GeoCoordinates"
}
}
}
}
}