{ "openapi": "3.1.0", "info": { "title": "Buy Offer API", "description": "Note: This is a \"Limited(Limited Release) API available only to select developers approved by business units. For information on how to obtain access to this API in production, see the Buy APIs Requirements.

The Buy Offer API enables Partners to place proxy bids for a buyer and retrieve the auctions where the buyer is bidding. By placing a proxy bid, the buyer is agreeing to purchase the item if they win the auction.", "contact": { "name": "eBay Inc," }, "license": { "name": "eBay API License Agreement", "url": "https://developer.ebay.com/join/api-license-agreement" }, "version": "v1_beta.0.1" }, "servers": [ { "url": "https://api.ebay.com{basePath}", "description": "Production", "variables": { "basePath": { "default": "/buy/offer/v1_beta" } } }, { "url": "https://api.sandbox.ebay.com{basePath}", "description": "sandbox server", "variables": { "basePath": { "default": "/buy/offer/v1_beta" } } } ], "security": [ {} ], "paths": { "/bidding/{item_id}": { "get": { "tags": [ "bidding" ], "description": "This method retrieves the bidding details that are specific to the buyer of the specified auction. This must be an auction where the buyer has already placed a bid.

To retrieve the bidding information you use a user access token and pass in the item ID of the auction. You can also retrieve general bidding details about the auction, such as minimum bid price and the count of unique bidders, using the Browse API getItems method.

Restrictions

For a list of supported sites and other restrictions, see Buy API Requirements.

", "operationId": "getBidding", "parameters": [ { "name": "X-EBAY-C-MARKETPLACE-ID", "in": "header", "description": "The ID of the eBay marketplace where the buyer is based. This value is case sensitive.

For example:
  X-EBAY-C-MARKETPLACE-ID = EBAY_US

For a list of supported sites see, Buy API Support by Marketplace.", "required": true, "schema": { "type": "string" }, "style": "simple", "explode": false }, { "name": "item_id", "in": "path", "description": "This path parameter specifies the unique eBay RESTful identifier of an item for which you want the buyer's bidding information.

This ID is returned by the Browse and Feed API methods.

RESTful Item ID example: v1|2**********2|0

For more information about item ID for RESTful APIs, see the Legacy API compatibility section of the Buy APIs Overview.

Restriction: The buyer must have placed a bid for this item. ", "required": true, "schema": { "type": "string" }, "style": "simple", "explode": false } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bidding" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-response-codes": { "errors": { "120015": { "domain": "API_OFFER", "category": "REQUEST", "description": "The X-EBAY-C-MARKETPLACE-ID header is missing. This is a required header." }, "120017": { "domain": "API_OFFER", "category": "REQUEST", "description": "The Marketplace {marketplaceId} is not supported. Supported values are {allowedMarketplaces}." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-response-codes": { "errors": { "120001": { "domain": "API_OFFER", "category": "REQUEST", "description": "The item ID {item_id} was not found. Check that this is an active auction item ID." }, "120033": { "domain": "API_OFFER", "category": "REQUEST", "description": "There is no bidding activity for this auction (item ID {item_id})." } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-response-codes": { "errors": { "120000": { "domain": "API_OFFER", "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/buy.offer.auction" ] } ] } }, "/bidding/{item_id}/place_proxy_bid": { "post": { "tags": [ "bidding" ], "description": "This method uses a user access token to place a proxy bid for the buyer on a specific auction item. The item must offer AUCTION as one of the buyingOptions.

To place a bid, you pass in the item ID of the auction as a URI parameter and the buyer's maximum bid amount (maxAmount ) in the payload. By placing a proxy bid, the buyer is agreeing to purchase the item if they win the auction.

After this bid is placed, if someone else outbids the buyer a bid, eBay automatically bids again for the buyer up to the amount of their maximum bid. When the bid exceeds the buyer's maximum bid, eBay will notify them that they have been outbid.

To find auctions, you can use the Browse API to search for items and use a filter to return only auction items. For example:

/buy/browse/v1/item_summary/search?q=iphone&filter=buyingOptions:{AUCTION}

Restrictions

For a list of supported sites and other restrictions, see Buy API Requirements.", "operationId": "placeProxyBid", "parameters": [ { "name": "X-EBAY-C-MARKETPLACE-ID", "in": "header", "description": "The ID of the eBay marketplace where the buyer is based. This value is case sensitive.

For example:
  X-EBAY-C-MARKETPLACE-ID = EBAY_US

For a list of supported sites see, Buy API Support by Marketplace.", "required": true, "schema": { "type": "string" }, "style": "simple", "explode": false }, { "name": "item_id", "in": "path", "description": "This path parameter specifies the unique eBay RESTful identifier of an item you want to bid on.

This ID is returned by the Browse and Feed Beta API methods.

RESTful Item ID Example: v1|2**********2|0

For more information about item ID for RESTful APIs, see the Legacy API compatibility section of the Buy APIs Overview.", "required": true, "schema": { "type": "string" }, "style": "simple", "explode": false }, { "name": "Content-Type", "in": "header", "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.

For more information, refer to HTTP request headers.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaceProxyBidRequest" } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaceProxyBidResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-response-codes": { "errors": { "120011": { "domain": "API_OFFER", "category": "REQUEST", "description": "The bid amount exceeds the limit." }, "120013": { "domain": "API_OFFER", "category": "REQUEST", "description": "The bid amount is missing or invalid." }, "120014": { "domain": "API_OFFER", "category": "REQUEST", "description": "The bid currency is invalid. Refer to the documentation for a list of currency codes." }, "120015": { "domain": "API_OFFER", "category": "REQUEST", "description": "The X-EBAY-C-MARKETPLACE-ID header is missing. This is a required header." }, "120016": { "domain": "API_OFFER", "category": "REQUEST", "description": "The maximum bid amount is missing." }, "120017": { "domain": "API_OFFER", "category": "REQUEST", "description": "The Marketplace {marketplaceId} is not supported. Supported values are {allowedMarketplaces}." } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-response-codes": { "errors": { "120001": { "domain": "API_OFFER", "category": "REQUEST", "description": "The item ID {item_id} was not found. Check that this is an active auction item ID." } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-response-codes": { "errors": { "120002": { "domain": "API_OFFER", "category": "BUSINESS", "description": "The auction was ended because the item was purchased with Buy It Now (fixed_price)." }, "120003": { "domain": "API_OFFER", "category": "BUSINESS", "description": "A seller cannot place a bid." }, "120004": { "domain": "API_OFFER", "category": "BUSINESS", "description": "You are not eligible to bid on this item." }, "120005": { "domain": "API_OFFER", "category": "BUSINESS", "description": "The bid price cannot be greater than the Buy It Now price." }, "120006": { "domain": "API_OFFER", "category": "BUSINESS", "description": "You are not eligible to bid on this item due to seller restrictions." }, "120007": { "domain": "API_OFFER", "category": "REQUEST", "description": "The bid amount is too high." }, "120008": { "domain": "API_OFFER", "category": "BUSINESS", "description": "The bid amount is too low." }, "120009": { "domain": "API_OFFER", "category": "BUSINESS", "description": "The bid currency needs to match the item price currency." }, "120010": { "domain": "API_OFFER", "category": "BUSINESS", "description": "You cannot lower your proxy bid." }, "120012": { "domain": "API_OFFER", "category": "BUSINESS", "description": "The auction has ended." }, "120018": { "domain": "API_OFFER", "category": "REQUEST", "description": "For this auction, the bid amount cannot have decimals." }, "120019": { "domain": "API_OFFER", "category": "BUSINESS", "description": "You must be pre-approval to bid on this auction." }, "120020": { "domain": "API_OFFER", "category": "BUSINESS", "description": "A user agreement acceptance is required for this auction." }, "120021": { "domain": "API_OFFER", "category": "BUSINESS", "description": "You are not authorized to bid on adult items. See the eBay help on adult items." }, "120022": { "domain": "API_OFFER", "category": "BUSINESS", "description": "A privacy user agreement is required for this auction." }, "120023": { "domain": "API_OFFER", "category": "BUSINESS", "description": "This is a business to business only auction." }, "120024": { "domain": "API_OFFER", "category": "BUSINESS", "description": "The item is currently unavailable." }, "120025": { "domain": "API_OFFER", "category": "BUSINESS", "description": "The bid was blocked because you have exceeded the item purchased limit." }, "120026": { "domain": "API_OFFER", "category": "BUSINESS", "description": "The bid was blocked due to a seller restriction based on your feedback score." }, "120027": { "domain": "API_OFFER", "category": "BUSINESS", "description": "The bid was blocked due to a seller restriction on the shipping location." }, "120028": { "domain": "API_OFFER", "category": "BUSINESS", "description": "The auction is restricted to users with a linked PayPal accounts." }, "120029": { "domain": "API_OFFER", "category": "BUSINESS", "description": "There has been a buyer policy violation." }, "120030": { "domain": "API_OFFER", "category": "BUSINESS", "description": "The bid was blocked due to unpaid items." }, "120031": { "domain": "API_OFFER", "category": "BUSINESS", "description": "This requires credit card verification." }, "120032": { "domain": "API_OFFER", "category": "REQUEST", "description": "This requires the user's consent for adult items." } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-response-codes": { "errors": { "120000": { "domain": "API_OFFER", "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/buy.offer.auction" ] } ] } } }, "components": { "schemas": { "Amount": { "type": "object", "required": [ "currency", "value" ], "properties": { "currency": { "description": "The three-letter ISO 4217 code representing the currency of the amount in the value field. ", "$ref": "#/components/schemas/CurrencyCodeEnum" }, "value": { "type": "string", "description": "The monetary amount." } }, "description": "The type that defines the fields for a monetary value and its currency." }, "AuctionStatusEnum": { "type": "object", "description": "An enumerated type for the values that represent the state of the auction. | - **ACTIVE**: Indicates the auction listing is active and buyers can bid on this item. - **ENDED**: Indicates the auction listing has ended.", "enum": [ "ACTIVE", "ENDED" ] }, "Bidding": { "type": "object", "requirement": [ "auctionEndDate", "auctionStatus", "bidCount", "currentPrice", "currentProxyBid", "highBidder", "itemId" ], "properties": { "auctionEndDate": { "type": "string", "description": "The date the auction will end.", "format": "date-time" }, "auctionStatus": { "description": "An enumeration value that represents the current state of the auction, such as ACTIVE or ENDED.

If this value is ENDED and the value of highBidder is true, this indicates the buyer has won the auction.", "$ref": "#/components/schemas/AuctionStatusEnum" }, "bidCount": { "type": "integer", "description": "The number of proxy bids that have been placed for the auction.", "format": "int32" }, "currentPrice": { "description": "The amount of the highest bid, which is the current price of the item.", "$ref": "#/components/schemas/Amount" }, "currentProxyBid": { "description": "The buyer's proxy bid, which is the maxAmount specified in the request. ", "$ref": "#/components/schemas/ProxyBid" }, "highBidder": { "type": "boolean", "description": "Indicates if the buyer is the highest bidder. " }, "itemId": { "type": "string", "description": "The eBay RESTful identifier of an item being bid on, which was submitted in the request." }, "reservePriceMet": { "type": "boolean", "description": "This indicates if the reserve price of the item has been met. A reserve price is set by the seller and is the minimum amount the seller is willing to sell the item for.

If the highest bid is not equal to or higher than the reserve price when the auction ends, the listing ends and the item is not sold.

Note: This is returned only for auctions that have a reserve price.

" }, "suggestedBidAmounts": { "type": "array", "description": "The suggested bid amount for the next bid. Note: These are generated suggestions and do not guarantee the buyer will win the bid. This means these suggestions do not take into account the max bid amount of other bidders. The buyer can be outbid even if they submit the highest suggested bid.", "items": { "$ref": "#/components/schemas/Amount" } } }, "description": "The type that defines the fields for the auction details." }, "CurrencyCodeEnum": { "type": "object", "description": "The three-letter ISO 4217 code representing a world currency. | - **AED**: United Arab Emirates dirham - **AFN**: Afghan afghani - **ALL**: Albanian lek - **AMD**: Armenian dram - **ANG**: Netherlands Antillean guilder - **AOA**: Angolan kwanza - **ARS**: Argentine peso - **AUD**: Australian dollar - **AWG**: Aruban florin - **AZN**: Azerbaijani manat - **BAM**: Bosnia and Herzegovina convertible mark - **BBD**: Barbados dollar - **BDT**: Bangladeshi taka - **BGN**: Bulgarian lev - **BHD**: Bahraini dinar - **BIF**: Burundian franc - **BMD**: Bermudian dollar - **BND**: Brunei dollar - **BOB**: Bolivian Boliviano - **BRL**: Brazilian real - **BSD**: Bahamian dollar - **BTN**: Bhutanese ngultrum - **BWP**: Botswana pula - **BYR**: Belarusian ruble - **BZD**: Belize dollar - **CAD**: Canadian dollar - **CDF**: Congolese franc - **CHF**: Swiss franc - **CLP**: Chilean peso - **CNY**: Chinese yuan renminbi - **COP**: Colombian peso - **CRC**: Costa Rican colon - **CUP**: Cuban peso - **CVE**: Cape Verde escudo - **CZK**: Czech koruna - **DJF**: Djiboutian franc - **DKK**: Danish krone - **DOP**: Dominican peso - **DZD**: Algerian dinar - **EGP**: Egyptian pound - **ERN**: Eritrean nakfa - **ETB**: Ethiopian birr - **EUR**: European Union euro - **FJD**: Fiji dollar - **FKP**: Falkland Islands pound - **GBP**: British pound sterling - **GEL**: Georgian lari - **GHS**: Ghanaian cedi - **GIP**: Gibraltar pound - **GMD**: Gambian dalasi - **GNF**: Guinean franc - **GTQ**: Guatemalan quetzal - **GYD**: Guyanese dollar - **HKD**: Hong Kong dollar - **HNL**: Honduran lempira - **HRK**: Croatian kuna - **HTG**: Haitian gourde - **HUF**: Hungarian forint - **IDR**: Indonesian rupiah - **ILS**: Israeli new shekel - **INR**: Indian rupee - **IQD**: Iraqi dinar - **IRR**: Iranian rial - **ISK**: Icelandic krona - **JMD**: Jamaican dollar - **JOD**: Jordanian dinar - **JPY**: Japanese yen - **KES**: Kenyan shilling - **KGS**: Kyrgyzstani som - **KHR**: Cambodian riel - **KMF**: Comoro franc - **KPW**: North Korean won - **KRW**: South Korean won - **KWD**: Kuwaiti dinar - **KYD**: Cayman Islands dollar - **KZT**: Kazakhstani tenge - **LAK**: Lao kip - **LBP**: Lebanese pound - **LKR**: Sri Lankan rupee - **LRD**: Liberian dollar - **LSL**: Lesotho loti - **LTL**: Lithuanian litas - **LYD**: Libyan dinar - **MAD**: Moroccan dirham - **MDL**: Moldovan leu - **MGA**: Malagasy ariary - **MKD**: Macedonian denar - **MMK**: Myanmar kyat - **MNT**: Mongolian tugrik - **MOP**: Macanese pataca - **MRO**: Mauritanian ouguiya - **MUR**: Mauritian rupee - **MVR**: Maldivian rufiyaa - **MWK**: Malawian kwacha - **MXN**: Mexican peso - **MYR**: Malaysian ringgit - **MZN**: Mozambican metical - **NAD**: Namibian dollar - **NGN**: Nigerian naira - **NIO**: Nicaraguan cordoba oro - **NOK**: Norwegian krone - **NPR**: Nepalese rupee - **NZD**: New Zealand dollar - **OMR**: Omani rial - **PAB**: Panamanian balboa - **PEN**: Peruvian sol - **PGK**: Papua New Guinean kina - **PHP**: Philippine peso - **PKR**: Pakistani rupee - **PLN**: Polish zloty - **PYG**: Paraguayan guarani - **QAR**: Qatari riyal - **RON**: Romanian leu - **RSD**: Serbian dinar - **RUB**: Russian ruble - **RWF**: Rwandan franc - **SAR**: Saudi riyal - **SBD**: Solomon Islands dollar - **SCR**: Seychelles rupee - **SDG**: Sudanese pound - **SEK**: Swedish krona - **SGD**: Singapore dollar - **SHP**: Saint Helena pound - **SLL**: Sierra Leonean leone - **SOS**: Somali shilling - **SRD**: Surinamese dollar - **STD**: Sao Tome and Principe dobra - **SYP**: Syrian pound - **SZL**: Swazi lilangeni - **THB**: Thai baht - **TJS**: Tajikistani somoni - **TMT**: Turkmenistani manat - **TND**: Tunisian dinar - **TOP**: Tongan pa'anga - **TRY**: Turkish lira - **TTD**: Trinidad and Tobago dollar - **TWD**: New Taiwan dollar - **TZS**: Tanzanian shilling - **UAH**: Ukrainian hryvnia - **UGX**: Ugandan shilling - **USD**: United States dollar - **UYU**: Uruguayan peso - **UZS**: Uzbekistani som - **VEF**: Venezuelan bolivar - **VND**: Vietnamese dong - **VUV**: Vanuatu vatu - **WST**: Samoan tala - **XAF**: CFA franc BEAC - **XCD**: East Caribbean dollar - **XOF**: CFA franc BCEAO - **XPF**: CFP franc - **YER**: Yemeni rial - **ZAR**: South African rand - **ZMW**: Zambian kwacha - **ZWL**: Zimbabwean dollar", "enum": [ "AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AUD", "AWG", "AZN", "BAM", "BBD", "BDT", "BGN", "BHD", "BIF", "BMD", "BND", "BOB", "BRL", "BSD", "BTN", "BWP", "BYR", "BZD", "CAD", "CDF", "CHF", "CLP", "CNY", "COP", "CRC", "CUP", "CVE", "CZK", "DJF", "DKK", "DOP", "DZD", "EGP", "ERN", "ETB", "EUR", "FJD", "FKP", "GBP", "GEL", "GHS", "GIP", "GMD", "GNF", "GTQ", "GYD", "HKD", "HNL", "HRK", "HTG", "HUF", "IDR", "ILS", "INR", "IQD", "IRR", "ISK", "JMD", "JOD", "JPY", "KES", "KGS", "KHR", "KMF", "KPW", "KRW", "KWD", "KYD", "KZT", "LAK", "LBP", "LKR", "LRD", "LSL", "LTL", "LYD", "MAD", "MDL", "MGA", "MKD", "MMK", "MNT", "MOP", "MRO", "MUR", "MVR", "MWK", "MXN", "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PEN", "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "RWF", "SAR", "SBD", "SCR", "SDG", "SEK", "SGD", "SHP", "SLL", "SOS", "SRD", "STD", "SYP", "SZL", "THB", "TJS", "TMT", "TND", "TOP", "TRY", "TTD", "TWD", "TZS", "UAH", "UGX", "USD", "UYU", "UZS", "VEF", "VND", "VUV", "WST", "XAF", "XCD", "XOF", "XPF", "YER", "ZAR", "ZMW", "ZWL" ] }, "Error": { "type": "object", "properties": { "category": { "type": "string", "description": "Identifies the type of error." }, "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.", "examples": [ "categoryId" ] }, "value": { "type": "string", "description": "The value of the object.", "examples": [ "1234" ] } }, "description": "Used to specify information relevant to the end user/client." }, "PlaceProxyBidRequest": { "type": "object", "required": [ "maxAmount" ], "properties": { "maxAmount": { "description": "The amount of the proxy bid to be placed. This is the maximum amount the buyer is willing to pay for the item.

Note: ", "$ref": "#/components/schemas/Amount" }, "userConsent": { "description": "Specifies whether the buyer wants to give their consent to bid on adult-only items. For a buyer to bid on an adult-only item, you must collect their consent using this field, and they must agree to the Terms of Use.

For more information about adult-only items on eBay, see Adult-Only items on eBay.

Default: false

", "$ref": "#/components/schemas/UserConsent" } }, "description": "The type that defines the fields for placing a proxy bid." }, "PlaceProxyBidResponse": { "type": "object", "properties": { "proxyBidId": { "type": "string", "description": "Identifier of the proxy bid created by the request. This indicates that the bid was placed and is not used for anything else." } }, "description": "The type that defines the fields for the place proxy bid response." }, "ProxyBid": { "type": "object", "required": [ "maxAmount", "proxyBidId" ], "properties": { "maxAmount": { "description": "The maximum amount the buyer is willing to pay for the item.", "$ref": "#/components/schemas/Amount" }, "proxyBidId": { "type": "string", "description": "Identifier of a specific proxy bid." } }, "description": "The type that defines the fields for the proxy bid information." }, "UserConsent": { "type": "object", "properties": { "adultOnlyItem": { "type": "boolean", "description": "The type that defines the fields for buyer consent to bid on adult-only items.

This field must be included in the placeProxyBid request and set to true if the buyer is bidding on an adult-only item.

For more information about adult-only items on eBay, see Adult-Only items on eBay." } }, "description": "The type that defines the fields for collecting the buyers consent." } }, "securitySchemes": { "api_auth": { "type": "oauth2", "description": "The security definitions for this API. Please check individual operations for applicable scopes.", "flows": { "authorizationCode": { "authorizationUrl": "https://auth.ebay.com/oauth2/authorize", "tokenUrl": "https://api.ebay.com/identity/v1/oauth2/token", "scopes": { "https://api.ebay.com/oauth/api_scope/buy.offer.auction": "View and manage bidding activities for auctions", "eBayUser": "eBay user access scope" } } } }, "bearerAuth": { "type": "http", "scheme": "bearer" } } } }