api-specs/commerce_charity_v1_oas3.yaml
---
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.0"
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.<br /><br /><b>Valid\
\ Values:</b> <code>EBAY_GB</code> and <code>EBAY_US</code>"
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."
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."
404:
description: "Not found"
x-response-codes:
errors:
165002:
domain: "API_CHARITY"
category: "REQUEST"
description: "Charity Org Id is invalid or missing."
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.<br /><br />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.<br /><br /><b>Valid Values:</b> <code>1-100</code><br /><br /><b>Default:</b>\
\ <code>20</code>"
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 <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>"
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.<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>"
required: false
schema:
type: "string"
- name: "X-EBAY-C-MARKETPLACE-ID"
in: "header"
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>"
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:
165003:
domain: "API_CHARITY"
category: "REQUEST"
description: "The specified limit is invalid. Maximum value supported\
\ is 100."
165001:
domain: "API_CHARITY"
category: "REQUEST"
description: "Invalid, missing or unsupported marketplace. Please\
\ refer to documentation."
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"
/charity_org/get_charity_org_by_legacy_id:
get:
tags:
- "charity_org"
description: "<span class=\"tablenote\"><b>Note: </b>The <a href=\"https://developer.ebay.com/api-docs/commerce/charity/resources/charity_org/methods/getCharityOrgByLegacyId\"\
>getCharityOrgByLegacyId</a> method requires a PayPal Giving Fund ID to retrieve\
\ an eBay charitable organizaiton, and eBay will no longer support these IDs\
\ beginning on January 16, 2023. The alternative to this method is the <a\
\ href=\"https://developer.ebay.com/api-docs/commerce/charity/resources/charity_org/methods/getCharityOrg\"\
>getCharityOrg</a> method, and this method requires the eBay-generated ID\
\ for a charitable organization.</span><br /><br />This call 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.<br /><br />The call returns the full details\
\ for the charitable organization that matches the specified ID."
operationId: "getCharityOrgByLegacyId"
parameters:
- name: "X-EBAY-C-MARKETPLACE-ID"
in: "header"
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>"
required: true
schema:
type: "string"
- name: "legacy_charity_org_id"
in: "query"
description: "The legacy ID of the charitable organization.<br /><br /><span\
\ class=\"tablenote\"><b>Note: </b>The legacy charity ID is the identifier\
\ assigned to an organization upon registration with the PayPal Giving Fund\
\ (PPGF). It has also been referred to as the external ID/charity number.</span>"
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."
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."
404:
description: "Not found"
x-response-codes:
errors:
165006:
domain: "API_CHARITY"
category: "REQUEST"
description: "LegacyId is invalid or missing."
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 <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>"
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.<br /><br\
\ /><span class=\"tablenote\"><span style=\"color:#004680\"><strong>Note:</strong></span>\
\ For the US marketplace, this is the EIN.</span>"
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.<br /><br /><b>Valid Values:</b> <code>1-100</code><br /><br /><b>Default:</b>\
\ <code>20</code>"
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 <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"
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"