eBay Trading API Call Reference Version 821 Support     Knowledge Base     Forums     All Tutorials     All Code Samples Users Guide Call Reference Making an API Call Tutorials Release Notes

Call Index Field Index Enumeration Index Type Index Deprecated Objects Errors by Number Input Output Detail Controls Samples Change History Top Errors for GetNotificationsUsage User Notes

GetNotificationsUsage

GetNotificationsUsage retrieves information about platform notifications sent to a given application. Use GetNotificationsUsage to confirm you are being sent all the platform notifications to which you have subscribed or to troubleshoot problems with notification delivery.

Before using this call, please review the topic Working with Platform Notifications to understand the requirements and limitations of the Platform Notifications feature.

The following information is included in the response:

• Start of time period—the beginning of the time period for which notification information is being retrieved.
• End of time period—the end of the time period for which notification information being retrieved.
• Notification details—information about individual notifications triggered by events associated with the specified item. You must specify ItemID to get this information. Notification details include:
• Delivery URL
• Reference identifier for the notification
• Scheduled expiration time for the notification
• Type of notification
• Number of times eBay has attempted to deliver a notification after initially failing
• Delivery status
• Time for the next scheduled delivery attempt
• Error message for the notification
• Communication history—if a significant number of notification deliveries fail, the application will be automatically marked as down, and eBay will stop sending notifications subscribed to by the application. When an application is marked as down, eBay will ping the application periodically to check if communication has been restored. When communication is restored, eBay will mark the application as up.
• Summary notification statistics—for the given time period, the following statistics are provided:
• Number of notifications that were delivered successfully
• Number of new notifications that were queued
• Number of pending notifications remain in the queue
• Number of scheduled notifications that expired
• Number of notification deliveries that failed

In the request, you can use StartTime and EndTime to specify a time period for which to retrieve notification activity. StartTime can be set to any time up to 72 hours prior to the time you make the call, and EndTime can be set to any time later than the StartTime, up to the time the call is make. By default, StartTime is set to 24 hours prior to making the call, and EndTime is set to the time of the call. Therefore, if StartTime and EndTime are not specified, GetNotificationsUsage retrieves notification usage information for the 24 hours prior to making the call.

The use of GetNotificationsUsage is limited to 50 calls per application, per hour.

Working with the Response

GetNotificationsUsage can be used with or without specifying ItemID. When ItemID is specified, and notifications were triggered during the given time period for events associated with the item, the response includes a NotificationDetailsArray containing details the individual notifications. This information may help you troubleshoot problems with your notification preferences.

The call response always includes MarkUpMarkDownHistory and NotificationStatistics. MarkUpMarkDownHistory contains a list of any mark-up or mark-down events that occurred during the given time period for your application. If eBay does not receive the required response when it sends a notification (HTTP status 200 OK), eBay assumes the notification delivery failed. If a significant number of notification deliveries fail, the application will be automatically marked as down, and eBay will stop sending notifications subscribed to by the application. If your application stays marked down for an extended period, or if eBay has manually marked the application as down, contact Developer Support to have your application status marked up.

NotificationStatistics lists summary quantities for notification status types. This information gives you a quick overview of notification usage for your application.

Managing the Volume of the Response

There is currently no limit on the amount of notification usage information returned. You can reduce the time period for the call to limit the size of the response.

GetNotificationsUsage does not support multiple detail levels. It is not necessary to specify a detail level for this call.

GetNotificationsUsage does not require or support pagination.

GetNotificationsUsage does not provide data filters for reducing the volume of the response.

GetNotificationsUsage use for a given application is limited to 50 calls per hour. Take care in specifying the ItemID and date/time range to ensure you get the data you are interested in.

Testing GetNotificationsUsage

The Sandbox supports the Platform Notifications feature. Before testing this call, please review the topic Working with Platform Notifications to understand the requirements and limitations of the Platform Notifications feature.

Use SetNotificationPreferences to subscribe to specific platform notifications for your application, such as Outbid or Feedback. In the Sandbox, create sample users and listings. Have one or more users place bids or send feedback, or perform other tasks that should trigger the notifications to which your application is subscribed. Use GetNotificationsUsage to confirm the notification usage for your application. Specify ItemID to get details for individual notifications.

Related Information

See Working with Platform Notifications.

Back to top

GetNotificationsUsage Input

The box below lists all fields that could be included in the call request. To learn more about an individual field or its type, click its name in the box (or scroll down to find it in the table below the box).

See also Samples.

See also the Deprecated Objects link above. Fields presented in this color are deprecated, and fields presented in this color are (or soon will be) non-operational.

The XML prototype does not include requester credentials. This is a documentation limitation only (see Standard Requester Credentials for Making Calls).

<?xml version="1.0" encoding="utf-8"?>
<GetNotificationsUsageRequest xmlns="urn:ebay:apis:eBLBaseComponents">
  <!-- Call-specific Input Fields -->
  <EndTime> dateTime </EndTime>
  <ItemID> ItemIDType (string) </ItemID>
  <StartTime> dateTime </StartTime>
  <!-- Standard Input Fields -->
  <ErrorLanguage> string </ErrorLanguage>
  <MessageID> string </MessageID>
  <Version> string </Version>
  <WarningLevel> WarningLevelCodeType </WarningLevel>
</GetNotificationsUsageRequest>

Back to top

GetNotificationsUsage Output

The box below lists all fields that might be returned in the response. To learn more about an individual field or its type, click its name in the box (or scroll down to find it in the table below the box).

See also Samples.

See also the Deprecated Objects link above. Fields presented in this color are deprecated, and fields presented in this color are not returned (or soon will not be returned) or are not operational (or soon will be non-operational).

<?xml version="1.0" encoding="utf-8"?>
<GetNotificationsUsageResponse xmlns="urn:ebay:apis:eBLBaseComponents">
  <!-- Call-specific Output Fields -->
  <EndTime> dateTime </EndTime>
  <MarkUpMarkDownHistory> MarkUpMarkDownHistoryType
    <MarkUpMarkDownEvent> MarkUpMarkDownEventType
      <Reason> string </Reason>
      <Time> dateTime </Time>
      <Type> MarkUpMarkDownEventTypeCodeType </Type>
    </MarkUpMarkDownEvent>
    <!-- ... more MarkUpMarkDownEvent nodes allowed here ... -->
  </MarkUpMarkDownHistory>
  <NotificationDetailsArray> NotificationDetailsArrayType
    <NotificationDetails> NotificationDetailsType
      <DeliveryStatus> NotificationEventStateCodeType </DeliveryStatus>
      <DeliveryTime> dateTime </DeliveryTime>
      <DeliveryURL> anyURI </DeliveryURL>
      <DeliveryURLName> string </DeliveryURLName>
      <ErrorMessage> string </ErrorMessage>
      <ExpirationTime> dateTime </ExpirationTime>
      <NextRetryTime> dateTime </NextRetryTime>
      <Retries> int </Retries>
      <Type> NotificationEventTypeCodeType </Type>
    </NotificationDetails>
    <!-- ... more NotificationDetails nodes allowed here ... -->
  </NotificationDetailsArray>
  <NotificationStatistics> NotificationStatisticsType
    <DeliveredCount> int </DeliveredCount>
    <ErrorCount> int </ErrorCount>
    <ExpiredCount> int </ExpiredCount>
    <QueuedNewCount> int </QueuedNewCount>
    <QueuedPendingCount> int </QueuedPendingCount>
  </NotificationStatistics>
  <StartTime> dateTime </StartTime>
  <!-- Standard Output Fields -->
  <Ack> AckCodeType </Ack>
  <Build> string </Build>
  <CorrelationID> string </CorrelationID>
  <Errors> ErrorType
    <ErrorClassification> ErrorClassificationCodeType </ErrorClassification>
    <ErrorCode> token </ErrorCode>
    <ErrorParameters ParamID="string"> ErrorParameterType
      <Value> string </Value>
    </ErrorParameters>
    <!-- ... more ErrorParameters nodes allowed here ... -->
    <LongMessage> string </LongMessage>
    <SeverityCode> SeverityCodeType </SeverityCode>
    <ShortMessage> string </ShortMessage>
  </Errors>
  <!-- ... more Errors nodes allowed here ... -->
  <HardExpirationWarning> string </HardExpirationWarning>
  <Timestamp> dateTime </Timestamp>
  <Version> string </Version>
</GetNotificationsUsageResponse>

Back to top

GetNotificationsUsage Detail Controls

Detail Control: DetailLevel

This call does not support varying Detail Levels. You do not need to pass DetailLevel in the request.

Back to top

GetNotificationsUsage Samples

An inline sample will be added in a future release. Please refer to the Samples section of the eBay Web Services Guide chapter for GetNotificationsUsage.

Back to top

GetNotificationsUsage Change History

Back to top

User-Contributed Notes

Copyright © 2005–2013 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.