eBay Marketplace Account Deletion/Closure Notifications WorkflowNotifications Workflow

eBay provides their users a way to request that their personal data be deleted from eBay's systems, as well as deleted from the systems of all eBay partners who store/display their personal data, including third-party developers integrated with eBay APIs via the eBay Developers Program.

To assist third-party developers in deleting customer data, eBay has created a push notification system that will notify all eBay Developers Program applications when an eBay user has requested that their personal data be deleted and their account closed. This document will discuss what third-party developers will need to do to receive, respond to, and validate these eBay marketplace account deletion/closure notifications.

Timelines for Subscribing to eBay Marketplace Account Deletion/Closure Notifications

All existing third-party developers integrated with eBay APIs via the eBay Developers Program are expected to subscribe to eBay marketplace account deletion/closure notifications by August 31, 2021. All new third-party developers coming to the platform are required to subscribe to eBay marketplace account deletion/closure notifications before they make their first call. Once the developer creates a keyset, it will initially be in the disabled state until the developer subscribes to eBay marketplace account deletion/closure notifications. The developer will be informed of the eBay marketplace account deletion/closure notifications requirement. Once the new developer's application is subscribed to eBay marketplace account deletion/closure notifications, the App ID is activated.

Note: Some developers might not be storing any data from eBay for various reasons. For such developers, we will working on a way to apply for exception via the Developer portal. More details about this will be added soon.

Subscribing to eBay Marketplace Account Deletion/Closure Notifications

All active eBay Developers Program applications are required to subsribe to eBay marketplace account deletion/closure notifications. Developers must follow the steps below to subscribe to these notifications for each of their applications associated with their developers' accounts: 

  1. Sign into your developer account.
  2. Go to the Application Keys page.
  3. Click on the Notifications link adjacent to your App ID. You will be taken to the Alerts and Notifications page shown below:

    Notification Page image
  4. On the Alerts and Notifications page, select the Marketplace Account Deletion radio button under the Event Notification Delivery Method section.
  5. Next, you will set an email address. The email address is required but will only be used to alert the developers when the specified Endpoint URL is not reachable. To input a value for this field, click the adjacent Edit button. Once you have set the value, click the Save button. 
  6. Then, you will set an Endpoint URL for receiving notifications. The Endpoint URL must be an 'https' address.To input a value for this field, click the adjacent Edit button. Once you have set the value, click the Save button. 
  7. Once you have set your email address and an Endpoint URL, you can send a test notification to this URL by clicking the Send Test Notification button.

Once the Endpoint URL has recieved the test notification successfully, your setup is complete.Your application should start receiving eBay marketplace account deletion/closure notifications from eBay immediately.

Receiving and Acknowledging eBay Marketplace Account Deletion/Closure Notifications

Once your application is enrolled for eBay marketplace account deletion/closure notifications, your callback URL will start receiving HTTP POST, JSON-based notifications for each eBay user that has requested that their personal data be deleted. A sample eBay marketplace account deletion/closure notification response is shown below:


{
    "metadata": {
        "topic": "MARKETPLACE_ACCOUNT_DELETION",
        "schemaVersion": "1.0",
        "deprecated": false
    },
    "notification": {
        "notificationId": "49feeaeb-4982-42d9-a377-9645b8479411_33f7e043-fed8-442b-9d44-791923bd9a6d","eventDate": "2021-03-19T20:43:59.462Z",
        "publishDate": "2021-03-19T20:43:59.679Z",
        "publishAttemptCount": 1,
        "data": {
            "username": "test_user",
            "userId": "ma8vp1jySJC",
            "eiasToken": "nY+sHZ2PrBmdj6wVnY+sEZ2PrA2dj6wJnY+gAZGEpwmdj6x9nY+seQ=="
        }
    }
}
                    

The fields in the notification response payload are briefly described in the table below:

Field Description
metadata.topic topic of the notification
metadata.schemaVersion schema version
metadata.deprecated boolean to indicate deprecation
notification.notificationId unique identifier of the notification
notification.eventDate timestamp indicating when eBay user made the data deletion request
notification.publishDate timestamp indicating when current notification was sent
notification.publishAttemptCount integer indicating how many times the notification has been sent to this specific callback URL
notification.data.username this string is the publicly known eBay user ID
notification.data.userId this string is the immutable identifier of the eBay user
notification.data.eiasToken this string is the eBay user's EIAS token; another identifier used for an eBay user

The callback URL should immediately acknowledge each eBay marketplace account deletion/closure notification with an HTTP status code indicating a successful response. 200 OK, 201 Created, 202 Accepted, and 204 No Content are all acceptable. For any callback URL that doesn't respond to an eBay marketplace account deletion/closure notification, eBay will resend the notification to the callback URL until it is acknowledged. After a 24-hour period of multiple, unacknowledged notifications from a callback URL, the callback URL is marked down, and eBay will send out an alert email to the developer about the callback URL being non-responsive. Upon receiving the email, the developer will have up to 30 days to resolve the problem with their callback URL acknowledging eBay marketplace account deletion/closure notifications. If the problem is not resolved within 30 days, the developer will be marked as non-compliant.  

Once developers begin receiving and acknowledging the receipt of eBay marketplace account deletion/closure notifications, they need to take the appropriate action to delete the user data, or in case developers plan to retain data, it is only retained to meet specific and demonstrable legal requirements (e.g. tax, collections, AML regulations). Deletion should be done in a manner such that even the highest system privilege cannot reverse the deletion.  

Verifying the Validity of an eBay Marketplace Account Deletion/Closure Notification

A callback URL should immediately acknowledge each eBay marketplace account deletion/closure notification with a 200 OK, 201 Created, 202 Accepted, or 204 No Content HTTP status code. After the acknowledgement of the eBay marketplace account deletion/closure notification, the developer should verify that the eBay marketplace account deletion/closure notification is actually coming from eBay. eBay has created the following two SDKs to verify the validity of each notification.

These SDKs do the following:

  1. Decode the signature header from the notification to retrieve the keyId
  2. Make a cache-enabled call to the Notification API to retrieve the public key
  3. Verify the signature against the notification payload
  4. If signature is verified, the payload is delegated to the processing logic for the topic and a Http status of 200 OK is returned, or If signature verification fails, a HTTP status 412 - Precondition Failed is returned.

More information can be found in the ReadMe files of the SDKs.

There is also a manual (non-SDK) process to verify that an eBay marketplace account deletion/closure notification is coming from eBay. The process is outline below:

  1. Use a Base64 decode function to decode the value retuned in the x-ebay-signature response header for the eBay marketplace account deletion/closure notification.
  2. This decoded value will be passed into the end of the getPublicKey URI of the Notification API.
  3. Go to the Notification API Overview page to see the rest of the verification process using that getPublicKey method.


asyncapi: 2.0.0
info:
  title: eBay Notifications
  version: 1.0.0
  description: This contract defines eBay notification for event subsciptions
channels:
  MARKETPLACE_ACCOUNT_DELETION:
    subscribe:
      message:
        $ref: '#/components/messages/message'
      bindings:
        http:
          type: request
          method: POST
          headers:
            type: object
            properties:
              Content-Type:
                type: string
                enum: ['application/json']
components:
  messages:
    message:
      headers:
        type: object
        properties:
          X-EBAY-SIGNATURE:
            description: ECC message signature
            type: string
      payload:
        type: object
        properties:
          metadata:
            $ref: '#/components/schemas/MetaData'
          notification:
            $ref: '#/components/schemas/Notification'
  schemas:
    MetaData:
      type: object
      properties:
        topic:
          type: string
          description: 'Topic subscribed to.'
        schemaVersion:
          type: string
          description: 'The schema for this topic.'
        deprecated:
          type: boolean
          description: 'If this is a deprecated schema or topic.'
          default: 'false'

    Notification:
      type: object
      properties:
        notificationId:
          type: string
          description: 'The notification Id.'
        eventDate:
          type: string
          description: 'The event date associated with this notification in UTC.'
        publishDate:
          type: string
          description: 'The message publish date in UTC.'
        publishAttemptCount:
          type: integer
          description: 'The number of attempts made to publish this message.'
        data:
         $ref: '#/components/schemas/MarketplaceAccountDeletionData'
    MarketplaceAccountDeletionData:
      type: object
      description: 'The Account Deletion payload.'
      properties:
        username:
          type: string
          description: 'The username for the user.'
        userId:
          type: string
          description: 'The immutable public userId for the user'
        eiasToken:
          type: string
          description: 'The legacy eiasToken specific to the user'

Frequently asked questions about eBay Marketplace Account Deletion/Closure Notifications

The FAQs in this section address some general questions about eBay marketplace account deletion/closure notifications.

Are developers required to subscribe to eBay marketplace account deletion/closure notifications?

Yes. Every eBay Developers Program application that is making API calls that use/store eBay user data must be subscribed to eBay marketplace account deletion/closure notifications. It is the responsibility of each developer to remove all user data associated with the eBay user specified in the eBay marketplace account deletion/closure notification.

How do I subscribe to eBay marketplace account deletion/closure notifications?

Go to the Alerts and Notifications page inside of your developer account. See the Subscribing to eBay Marketplace Account Deletion/Closure Notifications section in this document for more information.

How do I acknowledge eBay marketplace account deletion/closure notifications?

Set up a callback listener URL that will immediately reply to the HTTP POST notification with an HTTP status code indicating success. The following HTTP status codes are acceptable: 200 OK, 201 Created, 202 Accepted, or 204 No Content. The callback URL must use the 'https' protocol.

Why am I getting the same eBay marketplace account deletion/closure notification more than once?

eBay will resend any eBay marketplace account deletion/closure notification that is not acknowledged by the callback URL. If you are receiving eBay marketplace account deletion/closure notifications more than once, it is possible that your callback URL is not properly acknowledging the notifications.

I received an email that my callback URL was marked down by eBay. What do I do now?

Troubleshoot your callback URL to see why it is not properly acknowledging eBay marketplace account deletion/closure notifications. You can use the Send Test Notification tool on the Alerts and Notifications page to perform a test. Once you have discovered the issue, let eBay know and eBay will mark your callback URL as up, and will restart eBay marketplace account deletion/closure notifications being sent to that URL.

How do I verify that the eBay marketplace account deletion/closure notifications is actually coming from eBay?

eBay has created the following two SDKs to verify the validity of each notification.

Please see the Verifying the validity of an eBay Marketplace Account Deletion/Closure Notification section in this document for more information on how to do this.