/order

Production

https://api.ebay.com{basePath}

GET

/order

Use this call to search for and retrieve one or more orders based on their creation date, last modification date, or fulfillment status using the filter parameter. You can alternatively specify a list of orders using the orderIds parameter. Include the optional fieldGroups query parameter set to TAX_BREAKDOWN to return a breakdown of the taxes and fees. The returned Order objects contain information you can use to create and process fulfillments, including: Information about the buyer and seller Information about the order's line items The plans for packaging, addressing and shipping the order The status of payment, packaging, addressing, and shipping the order A summary of monetary amounts specific to the order such as pricing, payments, and shipping costs A summary of applied taxes and fees, and optionally a breakdown of each Important: In this call, the cancelStatus.cancelRequests array is returned but is always empty. Use the getOrder call instead, which returns this array fully populated with information about any cancellation requests.

Request Example

Shell

JavaScript

Java

Swift

curl --location -g --request GET 'https://api.ebay.com{basePath}/order'

Response Example

200 - Example 1

{
    "href": "string",
    "limit": 0,
    "next": "string",
    "offset": 0,
    "orders": [
        {
            "buyer": {
                "taxAddress": {
                    "city": "string",
                    "countryCode": "string",
                    "postalCode": "string",
                    "stateOrProvince": "string"
                },
                "taxIdentifier": {
                    "issuingCountry": "string",
                    "taxIdentifierType": "string",
                    "taxpayerId": "string"
                },
                "username": "string"
            },
            "buyerCheckoutNotes": "string",
            "cancelStatus": {
                "cancelRequests": [
                    {
                        "cancelCompletedDate": "string",
                        "cancelInitiator": "string",
                        "cancelReason": "string",
                        "cancelRequestId": "string",
                        "cancelRequestState": "string",
                        "cancelRequestedDate": "string"
                    }
                ],
                "cancelState": "string",
                "cancelledDate": "string"
            },
            "creationDate": "string",
            "ebayCollectAndRemitTax": true,
            "fulfillmentHrefs": [
                "string"
            ],
            "fulfillmentStartInstructions": [
                {
                    "ebaySupportedFulfillment": true,
                    "finalDestinationAddress": {
                        "addressLine1": "string",
                        "addressLine2": "string",
                        "city": "string",
                        "country": "string",
                        "county": "string",
                        "postalCode": "string",
                        "stateOrProvince": "string"
                    },
                    "fulfillmentInstructionsType": "string",
                    "maxEstimatedDeliveryDate": "string",
                    "minEstimatedDeliveryDate": "string",
                    "pickupStep": {
                        "merchantLocationKey": "string"
                    },
                    "shippingStep": {
                        "shipTo": {
                            "companyName": "string",
                            "contactAddress": {
                                "addressLine1": "string",
                                "addressLine2": "string",
                                "city": "string",
                                "country": "string",
                                "county": "string",
                                "postalCode": "string",
                                "stateOrProvince": "string"
                            },
                            "email": "string",
                            "fullName": "string",
                            "primaryPhone": {
                                "phoneNumber": "string"
                            }
                        },
                        "shipToReferenceId": "string",
                        "shippingCarrierCode": "string",
                        "shippingServiceCode": "string"
                    }
                }
            ],
            "lastModifiedDate": "string",
            "legacyOrderId": "string",
            "lineItems": [
                {
                    "appliedPromotions": [
                        {
                            "description": "string",
                            "discountAmount": {
                                "convertedFromCurrency": "string",
                                "convertedFromValue": "string",
                                "currency": "string",
                                "value": "string"
                            },
                            "promotionId": "string"
                        }
                    ],
                    "deliveryCost": {
                        "importCharges": {
                            "convertedFromCurrency": "string",
                            "convertedFromValue": "string",
                            "currency": "string",
                            "value": "string"
                        },
                        "shippingCost": {
                            "convertedFromCurrency": "string",
                            "convertedFromValue": "string",
                            "currency": "string",
                            "value": "string"
                        },
                        "shippingIntermediationFee": {
                            "convertedFromCurrency": "string",
                            "convertedFromValue": "string",
                            "currency": "string",
                            "value": "string"
                        }
                    },
                    "discountedLineItemCost": {
                        "convertedFromCurrency": "string",
                        "convertedFromValue": "string",
                        "currency": "string",
                        "value": "string"
                    },
                    "ebayCollectAndRemitTaxes": [
                        {
                            "amount": {
                                "convertedFromCurrency": "string",
                                "convertedFromValue": "string",
                                "currency": "string",
                                "value": "string"
                            },
                            "collectionMethod": "string",
                            "ebayReference": {
                                "name": "string",
                                "value": "string"
                            },
                            "taxType": "string"
                        }
                    ],
                    "giftDetails": {
                        "message": "string",
                        "recipientEmail": "string",
                        "senderName": "string"
                    },
                    "itemLocation": {
                        "countryCode": "string",
                        "location": "string",
                        "postalCode": "string"
                    },
                    "legacyItemId": "string",
                    "legacyVariationId": "string",
                    "lineItemCost": {
                        "convertedFromCurrency": "string",
                        "convertedFromValue": "string",
                        "currency": "string",
                        "value": "string"
                    },
                    "lineItemFulfillmentInstructions": {
                        "guaranteedDelivery": true,
                        "maxEstimatedDeliveryDate": "string",
                        "minEstimatedDeliveryDate": "string",
                        "shipByDate": "string"
                    },
                    "lineItemFulfillmentStatus": "string",
                    "lineItemId": "string",
                    "listingMarketplaceId": "string",
                    "properties": {
                        "buyerProtection": true,
                        "fromBestOffer": true,
                        "soldViaAdCampaign": true
                    },
                    "purchaseMarketplaceId": "string",
                    "quantity": 0,
                    "refunds": [
                        {
                            "amount": {
                                "convertedFromCurrency": "string",
                                "convertedFromValue": "string",
                                "currency": "string",
                                "value": "string"
                            },
                            "refundDate": "string",
                            "refundId": "string",
                            "refundReferenceId": "string"
                        }
                    ],
                    "sku": "string",
                    "soldFormat": "string",
                    "taxes": [
                        {
                            "amount": {
                                "convertedFromCurrency": "string",
                                "convertedFromValue": "string",
                                "currency": "string",
                                "value": "string"
                            },
                            "taxType": "string"
                        }
                    ],
                    "title": "string",
                    "total": {
                        "convertedFromCurrency": "string",
                        "convertedFromValue": "string",
                        "currency": "string",
                        "value": "string"
                    }
                }
            ],
            "orderFulfillmentStatus": "string",
            "orderId": "string",
            "orderPaymentStatus": "string",
            "paymentSummary": {
                "payments": [
                    {
                        "amount": {
                            "convertedFromCurrency": "string",
                            "convertedFromValue": "string",
                            "currency": "string",
                            "value": "string"
                        },
                        "paymentDate": "string",
                        "paymentHolds": [
                            {
                                "expectedReleaseDate": "string",
                                "holdAmount": {
                                    "convertedFromCurrency": "string",
                                    "convertedFromValue": "string",
                                    "currency": "string",
                                    "value": "string"
                                },
                                "holdReason": "string",
                                "holdState": "string",
                                "releaseDate": "string",
                                "sellerActionsToRelease": [
                                    {
                                        "sellerActionToRelease": "string"
                                    }
                                ]
                            }
                        ],
                        "paymentMethod": "string",
                        "paymentReferenceId": "string",
                        "paymentStatus": "string"
                    }
                ],
                "refunds": [
                    {
                        "amount": {
                            "convertedFromCurrency": "string",
                            "convertedFromValue": "string",
                            "currency": "string",
                            "value": "string"
                        },
                        "refundDate": "string",
                        "refundId": "string",
                        "refundReferenceId": "string",
                        "refundStatus": "string"
                    }
                ],
                "totalDueSeller": {
                    "convertedFromCurrency": "string",
                    "convertedFromValue": "string",
                    "currency": "string",
                    "value": "string"
                }
            },
            "pricingSummary": {
                "adjustment": {
                    "convertedFromCurrency": "string",
                    "convertedFromValue": "string",
                    "currency": "string",
                    "value": "string"
                },
                "deliveryCost": {
                    "convertedFromCurrency": "string",
                    "convertedFromValue": "string",
                    "currency": "string",
                    "value": "string"
                },
                "deliveryDiscount": {
                    "convertedFromCurrency": "string",
                    "convertedFromValue": "string",
                    "currency": "string",
                    "value": "string"
                },
                "fee": {
                    "convertedFromCurrency": "string",
                    "convertedFromValue": "string",
                    "currency": "string",
                    "value": "string"
                },
                "priceDiscountSubtotal": {
                    "convertedFromCurrency": "string",
                    "convertedFromValue": "string",
                    "currency": "string",
                    "value": "string"
                },
                "priceSubtotal": {
                    "convertedFromCurrency": "string",
                    "convertedFromValue": "string",
                    "currency": "string",
                    "value": "string"
                },
                "tax": {
                    "convertedFromCurrency": "string",
                    "convertedFromValue": "string",
                    "currency": "string",
                    "value": "string"
                },
                "total": {
                    "convertedFromCurrency": "string",
                    "convertedFromValue": "string",
                    "currency": "string",
                    "value": "string"
                }
            },
            "program": {
                "authenticityVerification": {
                    "outcomeReason": "string",
                    "status": "string"
                },
                "fulfillmentProgram": {
                    "fulfilledBy": "string"
                }
            },
            "salesRecordReference": "string",
            "sellerId": "string",
            "totalFeeBasisAmount": {
                "convertedFromCurrency": "string",
                "convertedFromValue": "string",
                "currency": "string",
                "value": "string"
            },
            "totalMarketplaceFee": {
                "convertedFromCurrency": "string",
                "convertedFromValue": "string",
                "currency": "string",
                "value": "string"
            }
        }
    ],
    "prev": "string",
    "total": 0,
    "warnings": [
        {
            "category": "string",
            "domain": "string",
            "errorId": 0,
            "inputRefIds": [
                "string"
            ],
            "longMessage": "string",
            "message": "string",
            "outputRefIds": [
                "string"
            ],
            "parameters": [
                {
                    "name": "string",
                    "value": "string"
                }
            ],
            "subdomain": "string"
        }
    ]
}

Request

Query Params

fieldGroups

string

optional

The response type associated with the order. The only presently supported value is TAX_BREAKDOWN. This type returns a breakdown of tax and fee values associated with the order.

filter

string

optional

One or more comma-separated criteria for narrowing down the collection of orders returned by this call. These criteria correspond to specific fields in the response payload. Multiple filter criteria combine to further restrict the results. Note: Currently, filter returns data from only the last 90 days. If the orderIds parameter is included in the request, the filter parameter will be ignored. The available criteria are as follows: creationdate The time period during which qualifying orders were created (the orders.creationDate field). In the URI, this is expressed as a starting timestamp, with or without an ending timestamp (in brackets). The timestamps are in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock.For example: creationdate:[2016-02-21T08:25:43.511Z..] identifies orders created on or after the given timestamp. creationdate:[2016-02-21T08:25:43.511Z..2016-04-21T08:25:43.511Z] identifies orders created between the given timestamps, inclusive. lastmodifieddate The time period during which qualifying orders were last modified (the orders.modifiedDate field). In the URI, this is expressed as a starting timestamp, with or without an ending timestamp (in brackets). The timestamps are in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock.For example: lastmodifieddate:[2016-05-15T08:25:43.511Z..] identifies orders modified on or after the given timestamp. lastmodifieddate:[2016-05-15T08:25:43.511Z..2016-05-31T08:25:43.511Z] identifies orders modified between the given timestamps, inclusive. Note: If creationdate and lastmodifieddate are both included, only creationdate is used. orderfulfillmentstatus The degree to which qualifying orders have been shipped (the orders.orderFulfillmentStatus field). In the URI, this is expressed as one of the following value combinations: orderfulfillmentstatus:{NOT_STARTED|IN_PROGRESS} specifies orders for which no shipping fulfillments have been started, plus orders for which at least one shipping fulfillment has been started but not completed. orderfulfillmentstatus:{FULFILLED|IN_PROGRESS} specifies orders for which all shipping fulfillments have been completed, plus orders for which at least one shipping fulfillment has been started but not completed. Note: The values NOT_STARTED, IN_PROGRESS, and FULFILLED can be used in various combinations, but only the combinations shown here are currently supported. Here is an example of a getOrders call using all of these filters: GET https://api.ebay.com/sell/v1/order? filter=creationdate:%5B2016-03-21T08:25:43.511Z..2016-04-21T08:25:43.511Z%5D, lastmodifieddate:%5B2016-05-15T08:25:43.511Z..%5D, orderfulfillmentstatus:%7BNOT_STARTED%7CIN_PROGRESS%7D Note: This call requires that certain special characters in the URI query string be percent-encoded: [ = %5B ] = %5D { = %7B | = %7C } = %7D This query filter example uses these codes. For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/sell/fulfillment/types/api:FilterField

limit

string

optional

The number of orders to return per page of the result set. Use this parameter in conjunction with the offset parameter to control the pagination of the output. For example, if offset is set to 10 and limit is set to 10, the call retrieves orders 11 thru 20 from the result set. Note: This feature employs a zero-based list, where the first item in the list has an offset of 0. If the orderIds parameter is included in the request, this parameter will be ignored. Maximum: 1000 Default: 50

offset

string

optional

Specifies the number of orders to skip in the result set before returning the first order in the paginated response. Combine offset with the limit query parameter to control the items returned in the response. For example, if you supply an offset of 0 and a limit of 10, the first page of the response contains the first 10 items from the complete list of items retrieved by the call. If offset is 10 and limit is 20, the first page of the response contains items 11-30 from the complete result set. Default: 0

orderIds

string

optional

A comma-separated list of the unique identifiers of the orders to retrieve (maximum 50). If one or more order ID values are specified through the orderIds query parameter, all other query parameters will be ignored. Note: A new order ID format was introduced to all eBay APIs (legacy and REST) in June 2019. In REST APIs that return Order IDs, including the Fulfillment API, all order IDs are returned in the new format, but the getOrders method will accept both the legacy and new format order ID. The new format is a non-parsable string, globally unique across all eBay marketplaces, and consistent for both single line item and multiple line item orders. These order identifiers will be automatically generated after buyer payment, and unlike in the past, instead of just being known and exposed to the seller, these unique order identifiers will also be known and used/referenced by the buyer and eBay customer support.

Responses

🟢200Success

application/json

Body

This type contains the specifications for the collection of orders that match the search or filter criteria of a getOrders call. The collection is grouped into a result set, and based on the query parameters that are set (including the limit and offset parameters), the result set may included multiple pages, but only one page of the result set can be viewed at a time.

href

string

optional

The URI of the getOrders call request that produced the current page of the result set.

limit

integer <int32>

optional

The maximum number of orders returned per page of the result set. The limit value can be passed in as a query parameter, or if omitted, its value defaults to 50. Note: If this is the last or only page of the result set, the page may contain fewer orders than the limit value. To determine the number of pages in a result set, divide the total value (total number of orders matching input criteria) by this limit value, and then round up to the next integer. For example, if the total value was 120 (120 total orders) and the limit value was 50 (show 50 orders per page), the total number of pages in the result set is three, so the seller would have to make three separate getOrders calls to view all orders matching the input criteria. Default: 50

string

optional

The getOrders call URI to use if you wish to view the next page of the result set. For example, the following URI returns records 41 thru 50 from the collection of orders: path/order?limit=10&offset=40 This field is only returned if there is a next page of results to view based on the current input criteria.

offset

integer <int32>

optional

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 offset query parameter. Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of 0.

orders

array[object (Order) {20}]

optional

This array contains one or more orders that are part of the current result set, that is controlled by the input criteria. The details of each order include information about the buyer, order history, shipping fulfillments, line items, costs, payments, and order fulfillment status. By default, orders are returned according to creation date (oldest to newest), but the order will vary according to any filter that is set in request.

buyer

object (Buyer)

optional

This container consists of information about the order's buyer. At this time, only the buyer's eBay user ID is returned, but it's possible that more buyer information can be added to this container in the future.

buyerCheckoutNotes

string

optional

This field contains any comments that the buyer left for the seller about the order during checkout process. This field is only returned if a buyer left comments at checkout time.

cancelStatus

object (CancelStatus)

optional

This container consists of order cancellation information if a cancel request has been made. This container is always returned, and if no cancel request has been made, the cancelState field is returned with a value of NONE_REQUESTED, and an empty cancelRequests array is also returned.

creationDate

string

optional

The date and time that the order was created. This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock. Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z Example: 2015-08-04T19:09:02.768Z

ebayCollectAndRemitTax

boolean

optional

This field is only returned if true, and indicates that eBay will collect tax (US state-mandated sales tax, 'Goods and Services' tax in Australia or New Zealand, and VAT collected for UK and EU countries) for at least one line item in the order, and remit the tax to the taxing authority of the buyer's residence. If this field is returned, the seller should search for one or more ebayCollectAndRemitTaxes containers at the line item level to get more information about the type of tax and the amount.

fulfillmentHrefs

array[string]

optional

This array contains a list of one or more getShippingFulfillment call URIs that can be used to retrieve shipping fulfillments that have been set up for the order.

fulfillmentStartInstructions

array[object (FulfillmentStartInstruction) {7}]

optional

This container consists of a set of specifications for fulfilling the order, including the type of fulfillment, shipping carrier and service, shipping address, and estimated delivery window. These instructions are derived from the buyer's and seller's eBay account preferences, the listing parameters, and the buyer's checkout selections. The seller can use them as a starting point for packaging, addressing, and shipping the order. Note: Although this container is presented as an array, it currently returns only one set of fulfillment specifications. Additional array members will be supported in future functionality.

lastModifiedDate

string

optional

The date and time that the order was last modified. This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock. Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z Example: 2015-08-04T19:09:02.768Z

legacyOrderId

string

optional

The unique identifier of the order in legacy format, as traditionally used by the Trading API (and other legacy APIs). Both the orderId field and this field are always returned. Note: In June 2019, Order IDs in REST APIs transitioned to a new format. For the Trading and other legacy APIs, by using version control/compatibility level, users have the option of using the older legacy order ID format, or they can migrate to the new order ID format, which is the same order ID format being used by REST APIs. Although users of the Trading API (and other legacy APIs) can now transition to the new order ID format, this legacyOrderId field will still return order IDs in the old format to distinguish between the old and new order IDs.

lineItems

array[object (LineItem) {22}]

optional

This array contains the details for all line items that comprise the order.

orderFulfillmentStatus

string

optional

The degree to which fulfillment of the order is complete. See the OrderFulfillmentStatus type definition for more information about each possible fulfillment state. For implementation help, refer to eBay API documentation

orderId

string

optional

The unique identifier of the order. Both the legacyOrderId field (traditionally used by Trading and other legacy APIS) and this field are always returned. Note: In June 2019, Order IDs in REST APIs transitioned to a new format. For the Trading and other legacy APIs, by using version control/compatibility level, users have the option of using the older legacy order ID format, or they can migrate to the new order ID format, which is the same order ID format being used by REST APIs. The new format is a non-parsable string, globally unique across all eBay marketplaces, and consistent for both single line item and multiple line item orders. These order identifiers are automatically generated after buyer payment, and unlike in the past, instead of just being known and exposed to the seller, these unique order identifiers will also be known and used/referenced by the buyer and eBay customer support.

orderPaymentStatus

string

optional

The enumeration value returned in this field indicates the current payment status of an order, or in case of a refund request, the current status of the refund. See the OrderPaymentStatusEnum type definition for more information about each possible payment/refund state. For implementation help, refer to eBay API documentation

paymentSummary

object (PaymentSummary)

optional

This container consists of detailed payment information for the order, including buyer payment for the order, refund information (if applicable), and seller payment holds (if applicable).

pricingSummary

object (PricingSummary)

optional

This container consists of a summary of cumulative costs and charges for all line items of an order, including item price, price adjustments, sales taxes, delivery costs, and order discounts.

program

object (Program)

optional

This container is returned for orders that are eligible for eBay's Authenticity Guarantee service. The seller ships Authenticity Guarantee service items to the authentication partner instead of the buyer. The authenticator address is found in the fulfillmentStartInstructions.shippingStep.shipTo container. If the item is successfully authenticated, the authenticator will ship the item to the buyer.

salesRecordReference

string

optional

An eBay-generated identifier that is used to identify and manage orders through the Selling Manager and Selling Manager Pro tools. This order identifier can also be found on the Orders grid page and in the Sales Record pages in Seller Hub. A salesRecordReference number is only generated and returned at the order level, and not at the order line item level. In cases where the seller does not have a Selling Manager or Selling Manager Pro subscription nor access to Seller Hub, this field may not be returned.

sellerId

string

optional

The unique eBay user ID of the seller who sold the order.

totalFeeBasisAmount

object (Amount)

optional

This is the cumulative base amount used to calculate the final value fees for each order. The final value fees are deducted from the seller payout associated with the order. Final value fees are calculated as a percentage of order cost (item cost + shipping cost) and the percentage rate can vary by eBay category.

totalMarketplaceFee

object (Amount)

optional

This is the cumulative fees accrued for the order and deducted from the seller payout.

string

optional

The getOrders call URI for the previous result set. For example, the following URI returns orders 21 thru 30 from the collection of orders: path/order?limit=10&offset=20 This field is only returned if there is a previous page of results to view based on the current input criteria.

total

integer <int32>

optional

The total number of orders in the results set based on the current input criteria. Note: If no orders are found, this field is returned with a value of 0.

warnings

array[object (Error) {9}]

optional

This array is returned if one or more errors or warnings occur with the call request.