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