openapi: 3.0.0
info:
title: eBay Account Advertising_eligibility Order_task API
description: The <b>Account API</b> gives sellers the ability to configure their eBay seller accounts, including the seller's policies (eBay business policies and seller-defined custom policies), opt in and out of eBay seller programs, configure sales tax tables, and get account information. <br><br>For details on the availability of the methods in this API, see <a href="/api-docs/sell/account/overview.html#requirements">Account API requirements and restrictions</a>.
contact:
name: eBay Inc,
license:
name: eBay API License Agreement
url: https://go.developer.ebay.com/api-license-agreement
version: v1.9.2
servers:
- url: https://api.ebay.com{basePath}
description: Production
variables:
basePath:
default: /sell/account/v1
tags:
- name: Order_task
paths:
/order_task:
get:
tags:
- Order_task
description: This method returns the details and status for an array of order tasks based on a specified <strong>feed_type</strong> or <strong>schedule_id</strong>. Specifying both <strong>feed_type</strong> and <strong>schedule_id</strong> results in an error. Since schedules are based on feed types, you can specify a schedule (<strong>schedule_id</strong>) that returns the needed <strong>feed_type</strong>.<br /><br />If specifying the <strong>feed_type</strong>, limit which order tasks are returned by specifying filters such as the creation date range or period of time using <strong>look_back_days</strong>. <br /><br />If specifying a <strong>schedule_id</strong>, the schedule template (that the <strong>schedule_id</strong> is based on) determines which order tasks are returned (see <strong>schedule_id</strong> for additional information). Each <strong>schedule_id</strong> applies to one <strong>feed_type</strong>.
operationId: getOrderTasks
parameters:
- name: date_range
in: query
description: 'The order tasks creation date range. This range is used to filter the results. The filtered results are filtered to include only tasks with a creation date that is equal to this date or is within specified range. Only orders less than 90 days old can be retrieved. Do not use with the <strong>look_back_days</strong> parameter. <br /><br /><b>Format: </b>UTC <br /><br /> <b> For example: </b> <br /><br />Tasks within a range <br /> <code>yyyy-MM-ddThh:mm:ss.SSSZ..yyyy-MM-ddThh:mm:ss.SSSZ </code> <br /><br /> Tasks created on September 8, 2019<br /> <code>2019-09-08T00:00:00.000Z..2019-09-09T00:00:00.000Z</code><br />'
required: false
schema:
type: string
- name: feed_type
in: query
description: The feed type associated with the order tasks being retrieved. The only presently supported value is <code>LMS_ORDER_REPORT</code><br><br>See <a href="/api-docs/sell/static/feed/lms-feeds-quick-reference.html#merchant-data-reports-download-feed-types">Report download feed types</a> for more information.<br><br><span class="tablenote"><b>Note:</b> Do not use with the <strong>schedule_id</strong> parameter. Since schedules are based on feed types, you can specify a schedule (<strong>schedule_id</strong>) that returns the needed <strong>feed_type</strong>.</span>
required: false
schema:
type: string
- name: limit
in: query
description: The maximum number of order tasks that can be returned on each page of the paginated response. Use this parameter in conjunction with the <strong>offset</strong> parameter to control the pagination of the output. <p> <span class="tablenote"><strong>Note:</strong> This feature employs a zero-based list, where the first item in the list has an offset of <code>0</code>.</span></p><p>For example, if <strong>offset</strong> is set to 10 and <strong>limit</strong> is set to 10, the call retrieves order tasks 11 thru 20 from the result set.</p><p>If this parameter is omitted, the default value is used.</p><p><b>Default:</b> 10 <p><b>Maximum:</b> 500</p>
required: false
schema:
type: string
- name: look_back_days
in: query
description: 'The number of previous days in which to search for tasks. Do not use with the <strong>date_range</strong> parameter. If both <strong>date_range</strong> and <strong>look_back_days</strong> are omitted, this parameter''s default value is used. <br /><br /><b>Default: </b> 7 <br /><br /><b>Range: </b> 1-90 (inclusive) '
required: false
schema:
type: string
- name: offset
in: query
description: 'The number of order tasks to skip in the result set before returning the first order in the paginated response. <p>Combine <strong>offset</strong> with the <strong>limit</strong> query parameter to control the items returned in the response. For example, if you supply an <strong>offset</strong> of <code>0</code> and a <strong>limit</strong> of <code>10</code>, the first page of the response contains the first 10 items from the complete list of items retrieved by the call. If <strong>offset</strong> is <code>10</code> and <strong>limit</strong> is <code>20</code>, the first page of the response contains items 11-30 from the complete result set. If this query parameter is not set, the default value is used and the first page of records is returned.<br /><br /><b>Default: </b>0'
required: false
schema:
type: string
- name: schedule_id
in: query
description: The schedule ID associated with the order tasks being retrieved. A schedule periodically generates a report, and these schedules can be created with the <a href="/api-docs/sell/feed/resources/schedule/methods/createSchedule">createSchedule</a> method.<br><br><span class="tablenote"><b>Note:</b> Do not use with the <strong>feed_type</strong> parameter. Since schedules are based on feed types, you can specify a schedule (<strong>schedule_id</strong>) that returns the needed <strong>feed_type</strong>.</span><br>Use the <a href="/api-docs/sell/feed/resources/schedule/methods/getSchedules">getSchedules</a> method to retrieve schedule IDs.
required: false
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/OrderTaskCollection'
'400':
description: Bad Request
x-response-codes:
errors:
'160004':
domain: API_FEED
category: REQUEST
description: You must submit either a 'feed_type' or 'schedule_id'.
'160005':
domain: API_FEED
category: REQUEST
description: Both 'feed_type' and 'schedule_id' were provided. Please remove one of them.
'160006':
domain: API_FEED
category: REQUEST
description: The 'feed_type' {feedTypeValue} is invalid.
'160007':
domain: API_FEED
category: REQUEST
description: The 'schedule_id' {scheduleID} is invalid.
'160008':
domain: API_FEED
category: REQUEST
description: Both 'look_back_days' and 'date_range' were provided. Please remove one of them.
'160009':
domain: API_FEED
category: REQUEST
description: The format of the 'date_range' is invalid. The format for a date range is yyyy-MM-ddThh:mm:ss.SSSZ..yyyy-MM-ddThh:mm:ss.SSSZ.
'160010':
domain: API_FEED
category: REQUEST
description: The 'date_range' must be less than or equal to 90 days.
'160011':
domain: API_FEED
category: REQUEST
description: The 'look_back_days' value must be greater than zero and less than or equal to 90.
'160012':
domain: API_FEED
category: REQUEST
description: The 'limit' value must be greater than zero and less than or equal to 500.
'160013':
domain: API_FEED
category: REQUEST
description: The 'offset' value cannot be less than zero.
'160029':
domain: API_FEED
category: REQUEST
description: The 'offset' value must be a multiple of the 'limit' value.
'403':
description: Forbidden
x-response-codes:
errors:
'160002':
domain: API_FEED
category: REQUEST
description: The authentication scope {scope} is incorrect for 'feed_type' {feedType}. Refer to documentation for details about the scopes.
'500':
description: Internal Server Error
x-response-codes:
errors:
'160001':
domain: API_FEED
category: APPLICATION
description: There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance.
security:
- api_auth:
- https://api.ebay.com/oauth/api_scope/sell.fulfillment
post:
tags:
- Order_task
description: 'This method creates an order download task with filter criteria for the order report. When using this method, specify the <b> feedType</b>, <b> schemaVersion</b>, and <b> filterCriteria</b> for the report. The method returns the <b> location</b> response header containing the getOrderTask call URI to retrieve the order task you just created. The URL includes the eBay-assigned task ID, which you can use to reference the order task. <br /><br />To retrieve the status of the task, use the <b>getOrderTask</b> method to retrieve a single task ID or the <b>getOrderTasks</b> method to retrieve multiple order task IDs.<p> <span class="tablenote"><strong>Note:</strong> The scope depends on the feed type. An error message results when an unsupported scope or feed type is specified.</span></p><p>The following list contains this method''s authorization scope and its corresponding feed type:<ul><li>https://api.ebay.com/oauth/api_scope/sell.fulfillment: LMS_ORDER_REPORT</li></ul> </p><p>For details about how this method is used, see <a href="/api-docs/sell/static/feed/general-feed-tasks.html" target="_blank">General feed types</a> in the Selling Integration Guide. <p> <span class="tablenote"><strong>Note:</strong> At this time, the <strong>createOrderTask</strong> method only supports order creation date filters and not modified order date filters. Do not include the <strong>modifiedDateRange</strong> filter in your request payload.</span></p>'
operationId: createOrderTask
parameters:
- name: Content-Type
in: header
description: This header indicates the format of the request body provided by the client. Its value should be set to <b>application/json</b>. <br><br> For more information, refer to <a href="/api-docs/static/rest-request-components.html#HTTP" target="_blank ">HTTP request headers</a>.
required: true
schema:
type: string
requestBody:
description: description not needed
content:
application/json:
schema:
description: description not needed
$ref: '#/components/schemas/CreateOrderTaskRequest'
required: true
responses:
'202':
description: Accepted
'400':
description: Bad Request
x-response-codes:
errors:
'160017':
domain: API_FEED
category: REQUEST
description: The 'feedType' is missing or invalid.
'160018':
domain: API_FEED
category: REQUEST
description: The 'schemaVersion' is invalid.
'160019':
domain: API_FEED
category: REQUEST
description: The 'filterCriteria' is invalid. {additionalInfo}
'160027':
domain: API_FEED
category: REQUEST
description: The X-EBAY-C-MARKETPLACE-ID header is missing or invalid.
'160030':
domain: API_FEED
category: REQUEST
description: This resource is not applicable for the feed type {feedTypeValue}. For more information, see the documentation for this API.
'403':
description: Forbidden
x-response-codes:
errors:
'160002':
domain: API_FEED
category: REQUEST
description: The authentication scope {scope} is incorrect for 'feed_type' {feedType}. Refer to documentation for details about the scopes.
'160022':
domain: API_FEED
category: REQUEST
description: You are not allowed to access this resource. Contact eBay Developer Technical Support for assistance.
'409':
description: Conflict
x-response-codes:
errors:
'160024':
domain: API_FEED
category: BUSINESS
description: You have reached the maximum number of feed tasks that can be queued or processed concurrently. Wait for current tasks to complete before adding tasks. For more information, see the documentation for this API.
'160025':
domain: API_FEED
category: BUSINESS
description: You have exceeded the maximum number of records or tasks that can be created or processed in the period (hourly or daily). Wait until the present period ends before trying again. Please reference the API documentation for more information.
'500':
description: Internal Server Error
x-response-codes:
errors:
'160001':
domain: API_FEED
category: APPLICATION
description: There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance.
security:
- api_auth:
- https://api.ebay.com/oauth/api_scope/sell.fulfillment
/order_task/{task_id}:
get:
tags:
- Order_task
description: This method retrieves the task details and status of the specified task. The input is <strong>task_id</strong>. <p>For details about how this method is used, see <a href="/api-docs/sell/static/orders/generating-and-retrieving-order-reports.html">Working with Order Feeds</a> in the Selling Integration Guide. </p>
operationId: getOrderTask
parameters:
- name: task_id
in: path
description: This path parameter is the unique identifier of the order task being retrieved.<br><br>Use the <a href="/api-docs/sell/feed/resources/order_task/methods/getOrderTasks">getOrderTasks</a> method to retrieve order task IDs.
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/OrderTask'
'400':
description: Bad Request
'403':
description: Forbidden
x-response-codes:
errors:
'160002':
domain: API_FEED
category: REQUEST
description: The authentication scope {scope} is incorrect for 'feed_type' {feedType}. Refer to documentation for details about the scopes.
'404':
description: Not Found
x-response-codes:
errors:
'160003':
domain: API_FEED
category: REQUEST
description: Task {taskID} does not exist.
'500':
description: Internal Server Error
x-response-codes:
errors:
'160001':
domain: API_FEED
category: APPLICATION
description: There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance.
security:
- api_auth:
- https://api.ebay.com/oauth/api_scope/sell.fulfillment
components:
schemas:
UploadSummary:
type: object
properties:
failureCount:
type: integer
description: The number of records, such as the number of listings created or the number of pictures uploaded to a listing, that failed to process during the upload feed. Check the response file and correct any issues mentioned. If the feed fails before processing, no response file is provided. In this case check the REST output response.
format: int32
successCount:
type: integer
description: The number of records that were successfully processed during the upload feed.
format: int32
description: This container provides summary information on an upload feed (not applicable for download feed types).
OrderTask:
type: object
properties:
completionDate:
type: string
description: The timestamp when the task went into the <code>COMPLETED</code> or <code>COMPLETED_WITH_ERROR</code> state. This state means that eBay has compiled the report for the seller based on the seller’s filter criteria, and the seller can run a <strong>getResultFile</strong> call to download the report.
creationDate:
type: string
description: The date the task was created.
detailHref:
type: string
description: The path to the call URI used to retrieve the task.
feedType:
type: string
description: The feed type associated with the task.
filterCriteria:
description: A container that returns the filter criteria used.
$ref: '#/components/schemas/OrderFilterCriteria'
schemaVersion:
type: string
description: The schema version number associated with the create task.
status:
type: string
description: The enumeration value that indicates the state of the task that was submitted in the request. See <strong>FeedStatusEnum</strong> for information. <p>The values <code>COMPLETED </code>and<code> COMPLETED_WITH_ERROR</code> indicate the Order Report file is ready to download.</p> For implementation help, refer to <a href='https://developer.ebay.com/api-docs/sell/feed/types/api:FeedStatusEnum'>eBay API documentation</a>
taskId:
type: string
description: The ID of the task that was submitted in the request.
uploadSummary:
description: This container provides summary information on an upload feed (not applicable for download feed types).
$ref: '#/components/schemas/UploadSummary'
description: The type that defines the fields for the <b> getOrderTask</b> response.
OrderTaskCollection:
type: object
properties:
href:
type: string
description: The path to the call URI that produced the current page of results.
limit:
type: integer
description: The value of the <strong>limit</strong> parameter submitted in the request, which is the maximum number of order tasks to return per page, from the result set. A result set is the complete set of tasks returned by the method. <p> <span class="tablenote"><strong>Note:</strong> Though this parameter is not required to be submitted in the request, the parameter defaults to <code>10</code> if omitted.</span></p><p> <span class="tablenote"><strong>Note:</strong> If this is the last or only page of the result set, the page may contain fewer tasks than the <strong>limit</strong> value. To determine the number of pages in a result set, divide the total value (total number of tasks matching input criteria) by this limit value, and then round up to the next integer. For example, if the <strong>total</strong> value was <code>120</code> (120 total tasks) and the <strong>limit</strong> value was <code>50</code> (show 50 tasks per page), the total number of pages in the result set is three, so the seller would have to make three separate <strong>getOrderTasks</strong> calls to view all tasks matching the input criteria.</span></p>
format: int32
next:
type: string
description: The path to the call URI for the next page of results. This value is returned if there is an additional page of results to return from the result set.
offset:
type: integer
description: 'The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the <b>offset</b> query parameter. <p class="tablenote"><strong>Note: </strong>The items in a paginated result set use a zero-based list where the first item in the list has an offset of <code>0</code>.</p>'
format: int32
prev:
type: string
description: The path to the call URI for the previous page of results. This is returned if there is a previous page of results from the result set.
tasks:
type: array
description: An array of the order tasks on this page. The tasks are sorted by creation date. An empty array is returned if the filter criteria excludes all tasks.
items:
$ref: '#/components/schemas/OrderTask'
total:
type: integer
description: The total number of order tasks that match the input criteria.
format: int32
description: The type that defines the fields for a paginated result set of orders. The response consists of 0 or more sequenced <em> pages</em> where each page has 0 or more items.
CreateOrderTaskRequest:
type: object
properties:
feedType:
type: string
description: The feed type associated with the task. The only presently supported value is <code>LMS_ORDER_REPORT</code>.<br><br>See <a href="/api-docs/sell/static/feed/lms-feeds-quick-reference.html#merchant-data-reports-download-feed-types" target="_blank">Report download feed types</a> for more information.
filterCriteria:
description: The container for the filter fields. This container is used to set the filter criteria for the order report. A seller can set date range filters and/or can retrieve orders in a specific state.
$ref: '#/components/schemas/OrderFilterCriteria'
schemaVersion:
type: string
description: 'The schema version of the LMS OrderReport. For the <code>LMS_ORDER_REPORT</code> feed type, see the <a href="/devzone/merchant-data/CallRef/OrderReport.html#OrderReport">OrderReport</a> reference page to see the present schema version. The <b> schemaVersion</b> value is the version number shown at the top of the <b> OrderReport</b> page. <br /><br /><b>Restriction: </b> This value must be 1113 or higher. The OrderReport schema version is updated about every two weeks. All version numbers are odd numbers (even numbers are skipped). For example, the next release version after ''1113'' is ''1115''.'
description: The type that defines the fields for the <b> createOrderTask</b> request.
DateRange:
type: object
properties:
from:
type: string
description: 'The beginning date in the range. If the parent type is included, both the <strong>from</strong> and/or the <strong>to</strong> fields become conditionally required.<br /><br /><b>Format: </b>UTC <code>yyyy-MM-ddThh:mm:ss.SSSZ </code> <br /><br /> <b> For example: </b> Tasks within a range <br /> <code>yyyy-MM-ddThh:mm:ss.SSSZ..yyyy-MM-ddThh:mm:ss.SSSZ </code> <br /><br /> Tasks created on March 31, 2021 <br /><code>2021-03-31T00:00:00.000Z..2021-03-31T00:00:00.000Z</code> '
to:
type: string
description: 'The end date for the date range, which is inclusive. If the parent type is included, both the <strong>from</strong> and/or the <strong>to</strong> fields become conditionally required. <br /><br /> <b> For example: </b> <br /><br />Tasks within a range <br /> <code>yyyy-MM-ddThh:mm:ss.SSSZ..yyyy-MM-ddThh:mm:ss.SSSZ </code> <br /><br /> Tasks created on March 31, 2021 <br /> <code>2021-03-31T00:00:00.000Z..2021-03-31T00:00:00.000Z</code> '
description: The type that defines the fields for a date range.
OrderFilterCriteria:
type: object
properties:
creationDateRange:
description: The creation date range of the orders you want returned. Set the date range so it contains less than 10 days (maximum). If you do not specify a <strong>DateRange</strong>, results from the last 10 days will be returned by default.
$ref: '#/components/schemas/DateRange'
modifiedDateRange:
description: The modified date range of the orders you want returned. <p> <span class="tablenote"><strong>Note:</strong> This container is for future use. At this time, the <strong>createOrderTask</strong> method only supports order creation date filters and not modified order date filters.</span></p>
$ref: '#/components/schemas/DateRange'
orderStatus:
type: string
description: The order status of the orders returned. If the filter is omitted from createOrderTask call, orders that are in both <code>ACTIVE </code>and<code> COMPLETED</code> states are returned. For implementation help, refer to <a href='https://developer.ebay.com/api-docs/sell/feed/types/api:OrderStatusEnum'>eBay API documentation</a>
description: The type that defines the fields for the order filters.
securitySchemes:
api_auth:
type: oauth2
description: The security definitions for this API. Please check individual operations for applicable scopes.
flows:
authorizationCode:
authorizationUrl: https://auth.ebay.com/oauth2/authorize
tokenUrl: https://api.ebay.com/identity/v1/oauth2/token
scopes:
https://api.ebay.com/oauth/api_scope/sell.account.readonly: View your account settings
https://api.ebay.com/oauth/api_scope/sell.account: View and manage your account settings