Skip to main content

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:

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

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

Got thoughts? Click the feedback button – your insights help us improve!