Inbound Notifications API | eBay Developers Program

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.

Input

Resource URI

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

URI parameters

This method has no URI parameters.

HTTP request headers

All requests made to eBay REST operations require you to provide the Authorization HTTP header for authentication authorization.

The table below shows the HTTP request headers that are either required, conditionally required, or strongly recommended for this method. Other standard HTTP request headers (not in this table) can also be used, but they are optional.

Header	Type	Description
Authorization	string	The merchant's eBay authorization token is passed in this header. The eBay authorization token value should be pre-fixed by `TOKEN`, so the complete value looks like: `TOKEN` <authorization token value> For information on these OAuth token values, see the Authorization Guide. Occurrence: Required
Content-Type	string	This header indicates the format of the request body provided by the client. This header value can be `application/json` or `application/xml`, based on the data format being used. JSON is the default format used for Inbound Notifications. Its value should be set to application/json. For more information, refer to HTTP request headers. Occurrence: Required
X-EBAY-EVENT-TYPE	string	The value passed in this header corresponds to the notification (event types) being passed to eBay. See Input events for details. The following values are available: `EBAY.ORDER.READY_FOR_PICKUP` Order Ready for Pickup Notification `EBAY.ORDER.PICKEDUP` Order Picked Up Notification `EBAY.ORDER.PICKUP_CANCELED` Order Pickup Canceled Notification `EBAY.ORDER.RETURNED` Order Returned Notification

Header

Type

Description

Authorization

string

The merchant's eBay authorization token is passed in this header. The eBay authorization token value should be pre-fixed by TOKEN, so the complete value looks like: TOKEN <authorization token value>

For information on these OAuth token values, see the Authorization Guide.

Occurrence: Required

Content-Type

string

This header indicates the format of the request body provided by the client. This header value can be application/json or application/xml, based on the data format being used. JSON is the default format used for Inbound Notifications. Its value should be set to application/json.

For more information, refer to HTTP request headers.

Occurrence: Required

X-EBAY-EVENT-TYPE

string

The value passed in this header corresponds to the notification (event types) being passed to eBay. See Input events for details. The following values are available:

EBAY.ORDER.READY_FOR_PICKUP Order Ready for Pickup Notification
EBAY.ORDER.PICKEDUP Order Picked Up Notification
EBAY.ORDER.PICKUP_CANCELED Order Pickup Canceled Notification
EBAY.ORDER.RETURNED Order Returned Notification

OAuth scope

See Specifying scopes when minting access tokens and OAuth access tokens for more information.

Input events

The same endpoint is used with different X-EBAY-EVENT-TYPE header tokens and payloads. Additional information about the four event types are shown below.

Order Ready for Pickup Notification

EBAY.ORDER.READY_FOR_PICKUP: this notification informs eBay that the in-store pickup item is ready for pickup. After receiving this notification, eBay updates the status of the order and notifies the buyer that the item is ready for pickup.

Input container/field	Type	Description
event.version	string	This is the version number of the Inbound Notifications API, such as `1.0`. Occurrence: Required
event.type	token	This is the same token value passed in the X-EBAY-EVENT-TYPE header, and in this case, set its value to: `EBAY.ORDER.READY_FOR_PICKUP` Occurrence: Required
event.notifierReferenceId	string	This is the merchant-defined identifier for the notification call. Each notification call identifier must be unique to the merchant. Occurrence: Required
event.payload.ebayOrderId	string	This is the eBay Order ID associated with the item that is being picked up. Important! The seller should not take any action until the buyer has paid. Occurrence: Required
event.payload.ebaySellerId	string	The eBay User ID of the seller. Occurrence: Optional
event.payload.notifierPickupNote	string	A comment about the status of the pickup. Occurrence: Optional
event.payload.notifierPickupId	string	This is the merchant-defined identifier for the item pickup. Occurrence: Optional

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"
     }
  }
}

Order Picked Up Notification

EBAY.ORDER.PICKEDUP: this notification informs eBay that the buyer has picked up the in-store pickup item. After receiving this notification, eBay updates the status of the order and the order is considered as complete.

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

Sample JSON Request

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

Order Pickup Canceled Notification

EBAY.ORDER.PICKUP_CANCELED: this notification informs eBay that the merchant has canceled the in-store pickup order. There are three possible reasons for a merchant canceling an in-store pickup order:

product is out of stock
buyer requested that merchant cancel order
buyer did not show up to pick up the item

After receiving this notification, eBay updates the status of the order, including the reason why the order pickup was canceled.

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

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"
    }
  }
}

Order Returned Notification

EBAY.ORDER.RETURNED: this notification informs eBay that the buyer has returned the item to the store for a refund or for store credit. After receiving this notification, eBay updates the status of the order, and returns the Refunds.Refund container in order management calls to give details on the refund transaction.

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

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 does not 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"
      }
      ]
    }
  }
}

Output

Response payload

The base response for an Inbound Notifications call includes two fields: ackValue and ackMessage. 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.

Response fields

Response Field	Description
ackValue	This field provides the overall outcome of the request. Two values are available: `SUCCESS` `FAIL`
ackMessage	This field provides the status of the request. Two values are available: `event received` `failed to receive message`

Response Field

Description

ackValue

This field provides the overall outcome of the request. Two values are available:

SUCCESS
FAIL

ackMessage

This field provides the status of the request. Two values are available:

event received
failed to receive message

HTTP status codes

This call can return one of the following HTTP status codes. For an overview of the status codes, see HTTP status codes in Using eBay RESTful APIs.

Status	Meaning
200	Success
400	Bad Request
401	Unauthorized

Error codes

For information on error codes and common errors, see Handling errors.

Sample

A successful call returns the HTTP status code 200.

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