In-Store Pickup Overview

Note: The In-Store Pickup feature is currently only available in the Sandbox environment. In-Store Pickup is scheduled to become available to large retail merchants beginning later in Q3 2013. Until the feature is wired on in the Production environment, sellers/developers who are eligible for the In-Store Pickup feature can start listing In-Store Pickup items and testing the feature in the Sandbox environment.

In-Store Pickup allows large merchants to sell products through eBay fixed-price listings, and have buyers pick up their items in physical stores. This new capability allows merchants and buyers to save on shipping costs and enables buyers to get their items a lot faster than traditional shipping options.

The following are the three merchant-facing APIs that enable In-Store Pickup:

Using the Inventory Management API

The Inventory Management API allows large merchants to add and manage stores and product inventory. By associating physical stores to their account and adding product inventory to these stores, large merchants are able to offer the In-Store Pickup option to buyers for these products. It is a REST-based API with four HTTP POST operations. Data is pushed out through an XML-based payload.

Merchants use the AddInventoryLocation call to add/associate a physical store to their account. Once one or more stores are associated to their accounts, merchants then use the AddInventory call to add products and/or manage product inventory and availability for one or more stores. Merchants use the DeleteInventoryLocation call to remove stores from their account, and the DeleteInventory call to remove a specific product from one or more stores. The four calls of the Inventory Management API are discussed further in the next four sections.

Using the AddInventoryLocation Call

The AddInventoryLocation call is used to create a new location (or update the data of an existing location) where buyers can pick up their items. The seller's eBay authorization token is a required HTTPS header.

Through the call payload, the merchant passes in the location's unique identifier, store name, store address, geographical coordinates, store phone number, and business hours. The merchant can optionally use the call to post item pickup instructions, the store's URL, special holiday hours, and location type (for example, 'store', 'warehouse', etc.).

For more information on the input fields for this call, see the AddInventoryLocation Call Reference.

Setting the Location ID of the Store

The merchant must define a LocationID value to act as an unique identifier for each store. The LocationID value is used in all four Inventory Management calls to identify the store to perform a task upon (update/remove store or add/update/remove inventory from that store). Once established for a store, the LocationID value cannot be changed.

Setting Business Hours for a Store

When creating a store with the AddInventoryLocation call, the merchant is required to provide business hours for each day of the week that the store is open. These business hours (in local time) are set up through the Hours container in the call. For each day of the week that the store is open and available for item pickups, the merchant must include a Day container in the call request and pass in those business hours through the Interval container. The day of the week is identified by passing an enumeration value that represents the day of the week through the DayOfWeek field.

Setting Special Hours for a Store

The SpecialHours container in the AddInventoryLocation call is used by the merchant to set special business hours for the store. A merchant would use this container to specify shorter or longer business hours for a specific date, or to provide specific dates when the store is closed. A specific example when a merchant might use the SpecialHours container to specify longer than normal hours is "Black Friday" (the day after Thanksgiving in the US when many stores have longer than normal business hours).

Whether the merchant is providing special hours or providing a day in which the store is closed, the specific date is identified through a separate SpecialHours.Day container. In the SpecialHours.Day container, the specific date is identified through the Date field, and the business hours for that day are provided through the Interval container. If the merchant is providing a date in which the store is closed, only the Day.Date value would be specified, and the Interval container would be omitted, since there are no business hours that day.

Updating a Store's Information

In addition to using an AddInventoryLocation call to create new store, merchants can also use this call to update information for an existing store. For example, the merchant might want to change the standard business hours, provide an updated phone number or Web site URL, or provide a specific date when the store will be closed. When updating an existing store with an AddInventoryLocation call, please note that all required fields must still be passed in, even if those values have not changed. The merchant should also be careful to use the correct LocationID value for the store.

Using the AddInventory Call

The AddInventory call is used by merchants to create and manage their inventory for a specific product (identified by SKU) at one or more existing locations. The seller's eBay authorization token is a required HTTPS header.

Whether adding a new product or updating an existing product, the merchant provides the availability status for each location specified in the request. Optionally, the merchant can also provide the quantity of the product available in each store. In the HTTPS POST request, the merchant passes in the product identifier (SKU value), and availability status and quantity available for the product at each location.

For more information on the input fields for this call, see the AddInventory Call Reference.

Adding a New Product to Stores

Merchants can use the AddInventory call to add new products to one or more stores. The SKU value of the product is required. A separate AddInventory call is required to add each new product. A Location container is required for each store in which the product will be added, and each store is identified by a LocationID value. In addition to the LocationID value, the only other required field in the Location container is the Availability field. In the Availability field, the merchant expresses whether the product is 'IN_STOCK' or 'OUT_OF_STOCK'. If 'IN_STOCK' is used, the optional Quantity value should be set to an positive integer value greater than '0'. If 'OUT_OF_STOCK' is used, the Quantity field (if included) should be set to '0'.

The FulfillmentTime field is not required, but it is a good idea for the merchant to include this field and set its value if the store needs extra time to prepare the product for pickup. For more information on how to specify a fulfillment time for a product, see the AddInventory Call Reference.

Updating a Product

Merchants can also use the AddInventory call to update the availability and quantity of an existing product in one or more stores. The SKU value of the product to update is required. A Location container is required for each store in which the product's availability, quantity, and/or fulfillment time will be updated, and each store is identified by a LocationID value. In addition to the LocationID value, the only other required field in the Location container is the Availability field. In the Availability field, the merchant expresses whether the product is 'IN_STOCK' or 'OUT_OF_STOCK'. If 'IN_STOCK' is used, the Quantity value must be a positive integer value greater than '0'. If 'OUT_OF_STOCK' is used, the Quantity field (if included) should be set to '0'.

The FulfillmentTime is not required, but it is a good idea for the merchant to include this field and set its value if the store needs extra time to prepare the product for pickup. For more information on how to specify a fulfillment time for a product, see the AddInventory Call Reference.

Using the DeleteInventoryLocation Call

The DeleteInventoryLocation call is used by merchants to delete an existing retail location. It is recommended that the retail location being deleted should have no inventory associated with it. The seller's eBay authorization token is a required HTTPS header.

The merchant simply passes in the LocationID value for the store to unassociate that store from their account.

For more information on the input fields for this call, see the DeleteInventoryLocation Call Reference.

Using the DeleteInventory Call

The DeleteInventory call is used by merchants to unassociate a product SKU with one store, multiple stores, or all stores associated with their account. The seller's eBay authorization token is a required HTTPS header.

In the HTTPS POST request, the merchant passes in the product SKU to remove, and then passes in the LocationID value for one or more stores. Or, to remove the product SKU from all stores, the merchant would pass in a Confirm boolean instead of LocationIDvalues.

For more information on the input fields for this call, see the DeleteInventory Call Reference.

Enabling In-Store Pickup Items Through the Trading API

Large merchants who are eligible to use the In-Store Pickup feature, can use Trading API's Add/Revise/Relist calls to enable fixed-price items with the "In-Store Pickup" option. This new feature applies to the following Trading API listing calls:

To enable the "In-Store Pickup" option on a multi-quantity, fixed-price listing, the merchant must perform the following actions in an Add/Revise/Relist Trading API call:

When a merchant is successful at listing an item with the In-Store Pickup feature enabled, prospective buyers will see the "Available for In-Store Pickup" option on the listing, along with information on the closest store that has the item.

Retrieving In-Store Pickup Orders and Items Through the Trading API

Trading API's order management calls (GetOrders, GetItemTransactions, GetOrderTransactions, and GetSellerTransactions) will return the PickupDetails and PickupMethodSelected containers for all "In-Store Pickup" orders. For GetOrders and GetOrderTransactions, these containers are returned at the order level, and for GetItemTransactions and GetSellerTransactions, these containers are returned at the order line item level. The PickupDetails container will consist of the following information:

The PickupDetails container will contain one or more In-Store Pickup options. Currently, the two supported PickupMethod values are 'InStorePickup' and 'ShipToStore' (UK only). Below is an example of what the PickupDetails.PickupOptions container will look like:

<PickupOptions>
  <PickupMethod>InStorePickup</PickupMethod>
  <PickupPriority>1</PickupPriority>
</PickupOptions>

The PickupMethodSelected container will contain the following values:

For more information on the PickupDetails and PickupMethodSelected fields, see the GetOrders Call Reference document.

If the buyer elects to return the item to the store, the MonetaryDetails.Refunds.Refund container returned in order management calls will contain information about this refund. For this information to be returned, the merchant has to send the Order Return notification to eBay through the Inbound Notifications API.

For more information on the relevant fields of the Refund container, see the GetOrders Call Reference document.

Overview of Inbound Notifications API

The Inbound Notifications API allows merchants to post In-Store Pickup event messages to the eBay system. These notifications are pushed out through a REST-based API call. Once the eBay system receives an event message through the Inbound Notifications API, eBay will make all necessary updates, including updating In-Store Pickup order status, resolving open business activities, and pushing out additional notifications to the merchant and buyer.

Base URL and Required Headers for Inbound Notifications Call

The base URL for an Inbound Notifications request is shown below for Sandbox and Production environment:

Sandbox Environment

http://eventbridge.sandbox.ebay.com/eventbridge/InboundEvent/publish/

Production Environment

https://svcs.ebay.com/eventbridge/InboundEvent/publish

For each Inbound Notification API call, the following three HTTP headers are required:

Base Response for Inbound Notifications Call

The base response for an Inbound Notifications call is very simple, and only includes two fields: ackValue ('SUCCESS' or 'FAIL') and ackMessage ('event received' or 'failed to receive message'). Although merchants can pass in meaningful data in the call payload, the response does not acknowledge that the data in this payload was processed and/or understood.

Inbound Notification Event Types

The four Inbound Notification event types are shown below:

Details on making each notification call is covered in the subsequent sections.

Order Ready for Pickup Notification

Merchants notify eBay that an In-Store Pickup item is ready for pickup by passing in the 'EBAY.ORDER.READY_FOR_PICKUP' event type through an Inbound Notifications call. In addition to the Authorization and Content-Type headers, the merchant passes in 'EBAY.ORDER.READY_FOR_PICKUP' as the value in the X-EBAY-EVENT-TYPE header.

The request parameters associated with the 'EBAY.ORDER.READY_FOR_PICKUP' notification are shown below:

Parameter Type Occurrence Description
event.version string Required This is the version number of the Inbound Notifications API, such as '1.0'.
event.type token Required This is the same token value passed in the X-EBAY-EVENT-TYPE header, and in this case, its value is 'EBAY.ORDER.READY_FOR_PICKUP'.
event.notifierReferenceId string Required This is the merchant-defined identifier for the notification call. Each notification call identifier must be unique to the merchant.
event.payload.ebayOrderId string Required This is the eBay Order ID or the eBay Order Line Item ID associated with the item that is being picked up.
event.payload.ebaySellerId string Optional The eBay User ID of the seller.
event.payload.notifierPickupNote string Optional A comment about the status of the pickup.
event.payload.notifierPickupId string Optional This is the merchant-defined identifier for the item pickup.


Sample JSON Request

{
  "event":{
     "version":"1.0",
     "type":"EBAY.ORDER.READY_FOR_PICKUP",
     "notifierReferenceId”:”S********1",
     "payload":{
        "ebayOrderId":"2********0",
		"notifierPickupNote":"ready",
		"notifierPickupId":"1********1"
	 }
}

Sample JSON Response

{
   "ack":{
      "ackValue":"SUCCESS",
		  "ackMessage":"event received"
	  }
}

Order Picked Up Notification

Merchants notify eBay that an In-Store Pickup item has been picked up by the buyer by passing in the 'EBAY.ORDER.PICKEDUP' event type through an Inbound Notifications call. In addition to the Authorization and Content-Type headers, the merchant passes in 'EBAY.ORDER.PICKEDUP' as the value in the X-EBAY-EVENT-TYPE header.

The request parameters associated with the 'EBAY.ORDER.PICKEDUP' notification are shown below:

Parameter Type Occurrence Description
event.version string Required This is the version number of the Inbound Notifications API, such as '1.0'.
event.type token Required This is the same token value passed in the X-EBAY-EVENT-TYPE header, and in this case, its value is 'EBAY.ORDER.PICKEDUP'.
event.notifierReferenceId string Required This is the merchant-defined identifier for the notification call. Each notification call identifier must be unique to the merchant.
event.payload.ebayOrderId string Required This is the eBay Order ID or the eBay Order Line Item ID associated with the item that was picked up.
event.payload.ebaySellerId string Optional The eBay User ID of the seller.


Sample JSON Request

{
  "event":{
     "version":"1.0",
     "type":"EBAY.ORDER.PICKEDUP",
     "notifierReferenceId”:”S********1",
      "payload":{
         "ebayOrderId”:”2********0",
      }
	 }
}

Sample JSON Response

{
   "ack":{
      "ackValue":"SUCCESS",
		  "ackMessage":"event received"
	  }
}

Order Pickup Canceled Notification

Merchants notify eBay that an In-Store Pickup order has been canceled by passing in the 'EBAY.ORDER.PICKUP_CANCELED' event type through an Inbound Notifications call. In addition to the Authorization and Content-Type headers, the merchant passes in 'EBAY.ORDER.PICKUP_CANCELED' as the value in the X-EBAY-EVENT-TYPE header.

The request parameters associated with the 'EBAY.ORDER.PICKUP_CANCELED' notification are shown below:

Parameter Type Occurrence Description
event.version string Required This is the version number of the Inbound Notifications API, such as '1.0'.
event.type token Required This is the same token value passed in the X-EBAY-EVENT-TYPE header, and in this case, its value is 'EBAY.ORDER.PICKUP_CANCELED'.
event.notifierReferenceId string Required This is the merchant-defined identifier for the notification call. Each notification call identifier must be unique to the merchant.
event.payload.ebayOrderId string Required This is the eBay Order ID or the eBay Order Line Item ID associated with the order that is being canceled.
event.payload.ebaySellerId string Optional The eBay User ID of the seller.
event.payload.notifierCancelType enumeration Required This field gives the reason for order cancellation. The possible values inlude 'OUT_OF_STOCK', 'BUYER_NO_SHOW', or 'BUYER_REFUSED'.
event.payload.notifierPickupNote string Optional A comment about the order cancellation..
event.payload.notifierPickupId string Optional This is the merchant-defined identifier for the item pickup.
event.payload.notifierRefundType enumeration Required This field states the system used for the refund. 'EBAY' is currently the only valid value, since the only supported payment method for In-Store Pickup items is PayPal.


Sample JSON Request

{
  "event":{
     "version":"1.0",
     "type":"EBAY.ORDER.PICKUP_CANCELED",
     "notifierReferenceId”:”S********1",
     "payload":{
        "ebayOrderId”:”2********0",
		"notifierCancelType":"OUT_OF_STOCK",
		"notifierPickupNote":"sorry, no stock",
		"notifierPickupId":"1********1",
		"notifierRefundType":"EBAY"
	 }
}

Sample JSON Response

{
   "ack":{
      "ackValue":"SUCCESS",
		  "ackMessage":"event received"
	  }
}

Order Returned Notification

Merchants notify eBay that an In-Store Pickup order has been returned by passing in the 'EBAY.ORDER.RETURNED' event type through an Inbound Notifications call. In addition to the Authorization and Content-Type headers, the merchant passes in 'EBAY.ORDER.RETURNED' as the value in the X-EBAY-EVENT-TYPE header.

The request parameters associated with the 'EBAY.ORDER.RETURNED' notification are shown below:

Parameter Type Occurrence Description
event.version string Required This is the version number of the Inbound Notifications API, such as '1.0'.
event.type token Required This is the same token value passed in the X-EBAY-EVENT-TYPE header, and in this case, its value is 'EBAY.ORDER.RETURNED'.
event.notifierReferenceId string Required This is the merchant-defined identifier for the notification call. Each notification call identifier must be unique to the merchant.
event.payload.ebayOrderId string Required This is the eBay Order ID or the eBay Order Line Item ID associated with the order that is being canceled.
event.payload.ebaySellerId string Optional The eBay User ID of the seller.
event.payload.notifierTotalRefundAmount numeric Required The total amount being refunded to the buyer for the order, which may consist of one or more line items.
event.payload.notifierTotalRefundCurrency string Required The 3-digit code representing the currency used in the refund for the order. See the ISO 4217 Currency Codes site for a full list of currency values.
event.payload.notifierRefundType enumeration Required This field states the type of refund received by the buyer. Valid values are 'STORE_CREDIT', which indicates that the buyer received store credit equaling the amount of the returned item, or 'EBAY', which indicates that the refund to the buyer was handled through PayPal.
event.payload.notifierRefundNote string Optional This field is used to add a note about the refund.
event.payload.notifierRefundId string Optional The merchant-defined unique identifier for the order refund.
event.payload.refundLineItems string Required This is the container holding one or more line items that are being returned. Each line item in this list will be a part of the order specified in the event.payload.ebayOrderId field.
event.payload.refundLineItems.eBayItemId string Required This is the eBay Item ID of the line item being returned.
event.payload.refundLineItems.eBayTransactionId string Required This is the eBay Transaction ID of the line item being returned.
event.payload.refundLineItems.notifierRefundQuantity integer Required This is the quantity purchased of the line item being returned.
event.payload.refundLineItems.notifierRefundCurrency string Required The 3-digit code representing the currency used in the refund for the line item. See the ISO 4217 Currency Codes site for a full list of currency values.
event.payload.refundLineItems.notifierRefundAmount numeric Required The amount being refunded to the buyer for the line item.


Sample JSON Request

{
   "event":{
      "version":"1.0",
      "type":"EBAY.ORDER.RETURNED",
      "notifierReferenceId":"S********1",
      "payload":{
         "ebayOrderId":"2********0",
         "notifierTotalRefundAmount":"100.00",
         "notifierTotalRefundCurrency":"USD",
         "notifierRefundNote":"buyer doesn’t like it",
         "notifierRefundId":"1********1",
         "notifierRefundType":"STORE_CREDIT",
         "refundLineItems":[
            {
               "eBayItemId":"1********1",
               "eBayTransactionId":"2********1",
               "notifierRefundQuantity":"1",
               "notifierRefundAmount":"50.00",
               "notifierRefundCurrency":"USD"
            },
            {
               "eBayItemId":"1********2",
               "eBayTransactionId":"2********2",
               "notifierRefundQuantity":"1",
               "notifierRefundAmount":"50.00",
               "notifierRefundCurrency":"USD"
            }
         ]
     }
   }
}

Sample JSON Response

{
   "ack":{
      "ackValue":"SUCCESS",
		  "ackMessage":"event received"
	  }
}

Back to top

User-Contributed Notes

Share tips or code samples related to this call or topic. Questions or observations are welcome, too.

eBay employees moderate these notes to ensure they are pertinent to the document and relevant to the community. Your submission will show up for all developers when it is activated by the moderator.

   
 
 
 




Copyright © 2009–2021 eBay, Inc. All rights reserved. This documentation and the API may only be used in accordance with the eBay Developers Program and API License Agreement.