Download OpenAPI specification:Download
Use the Fulfillment API to complete the process of packaging, addressing, handling, and shipping each order on behalf of the seller, in accordance with the payment method and timing specified at checkout.
Use this call to retrieve the contents of an order based on its unique identifier, orderId. This value was returned in the getOrders call's orders.orderId field when you searched for orders by creation date, modification date, or fulfillment status. Include the optional fieldGroups query parameter set to TAX_BREAKDOWN to return a breakdown of the taxes and fees.
The returned Order object contains information you can use to create and process fulfillments, including:
| orderId required | string The unique identifier of the order. Order ID values are shown in My eBay/Seller Hub, and are also returned by the getOrders method in the orders.orderId field. |
| fieldGroups | string The response type associated with the order. The only presently supported value is |
{- "buyer": {
- "taxAddress": {
- "city": "string",
- "countryCode": "string",
- "postalCode": "string",
- "stateOrProvince": "string"
}, - "taxIdentifier": {
- "taxpayerId": "string",
- "taxIdentifierType": "string",
- "issuingCountry": "string"
}, - "username": "string"
}, - "buyerCheckoutNotes": "string",
- "cancelStatus": {
- "cancelledDate": "string",
- "cancelRequests": [
- {
- "cancelCompletedDate": "string",
- "cancelInitiator": "string",
- "cancelReason": "string",
- "cancelRequestedDate": "string",
- "cancelRequestId": "string",
- "cancelRequestState": "string"
}
], - "cancelState": "string"
}, - "creationDate": "string",
- "ebayCollectAndRemitTax": true,
- "fulfillmentHrefs": [
- "string"
], - "fulfillmentStartInstructions": [
- {
- "ebaySupportedFulfillment": true,
- "finalDestinationAddress": {
- "addressLine1": "string",
- "addressLine2": "string",
- "city": "string",
- "countryCode": "string",
- "county": "string",
- "postalCode": "string",
- "stateOrProvince": "string"
}, - "fulfillmentInstructionsType": "string",
- "maxEstimatedDeliveryDate": "string",
- "minEstimatedDeliveryDate": "string",
- "pickupStep": {
- "merchantLocationKey": "string"
}, - "shippingStep": {
- "shippingCarrierCode": "string",
- "shippingServiceCode": "string",
- "shipTo": {
- "companyName": "string",
- "contactAddress": {
- "addressLine1": "string",
- "addressLine2": "string",
- "city": "string",
- "countryCode": "string",
- "county": "string",
- "postalCode": "string",
- "stateOrProvince": "string"
}, - "email": "string",
- "fullName": "string",
- "primaryPhone": {
- "phoneNumber": "string"
}
}, - "shipToReferenceId": "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"
}, - "ebayReference": {
- "name": "string",
- "value": "string"
}, - "taxType": "string",
- "collectionMethod": "string"
}
], - "ebayCollectedCharges": {
- "ebayShipping": {
- "convertedFromCurrency": "string",
- "convertedFromValue": "string",
- "currency": "string",
- "value": "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"
}, - "variationAspects": [
- {
- "name": "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"
}, - "ebayShipping": {
- "shippingLabelProvidedBy": "string"
}, - "ebayVault": {
- "fulfillmentType": "string"
}, - "ebayInternationalShipping": {
- "returnsManagedBy": "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"
}
}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:
| fieldGroups | string The response type associated with the order. The only presently supported value is |
| filter | string 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.
GET https://api.ebay.com/sell/v1/order? 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 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. |
| offset | string 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 Default: 0 |
| orderIds | string 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. |
{- "href": "string",
- "limit": 0,
- "next": "string",
- "offset": 0,
- "orders": [
- {
- "buyer": {
- "taxAddress": {
- "city": "string",
- "countryCode": "string",
- "postalCode": "string",
- "stateOrProvince": "string"
}, - "taxIdentifier": {
- "taxpayerId": "string",
- "taxIdentifierType": "string",
- "issuingCountry": "string"
}, - "username": "string"
}, - "buyerCheckoutNotes": "string",
- "cancelStatus": {
- "cancelledDate": "string",
- "cancelRequests": [
- {
- "cancelCompletedDate": "string",
- "cancelInitiator": "string",
- "cancelReason": "string",
- "cancelRequestedDate": "string",
- "cancelRequestId": "string",
- "cancelRequestState": "string"
}
], - "cancelState": "string"
}, - "creationDate": "string",
- "ebayCollectAndRemitTax": true,
- "fulfillmentHrefs": [
- "string"
], - "fulfillmentStartInstructions": [
- {
- "ebaySupportedFulfillment": true,
- "finalDestinationAddress": {
- "addressLine1": "string",
- "addressLine2": "string",
- "city": "string",
- "countryCode": "string",
- "county": "string",
- "postalCode": "string",
- "stateOrProvince": "string"
}, - "fulfillmentInstructionsType": "string",
- "maxEstimatedDeliveryDate": "string",
- "minEstimatedDeliveryDate": "string",
- "pickupStep": {
- "merchantLocationKey": "string"
}, - "shippingStep": {
- "shippingCarrierCode": "string",
- "shippingServiceCode": "string",
- "shipTo": {
- "companyName": "string",
- "contactAddress": {
- "addressLine1": "string",
- "addressLine2": "string",
- "city": "string",
- "countryCode": "string",
- "county": "string",
- "postalCode": "string",
- "stateOrProvince": "string"
}, - "email": "string",
- "fullName": "string",
- "primaryPhone": {
- "phoneNumber": "string"
}
}, - "shipToReferenceId": "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"
}, - "ebayReference": {
- "name": "string",
- "value": "string"
}, - "taxType": "string",
- "collectionMethod": "string"
}
], - "ebayCollectedCharges": {
- "ebayShipping": {
- "convertedFromCurrency": "string",
- "convertedFromValue": "string",
- "currency": "string",
- "value": "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"
}, - "variationAspects": [
- {
- "name": "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": null
}
]
}
], - "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"
}, - "ebayShipping": {
- "shippingLabelProvidedBy": "string"
}, - "ebayVault": {
- "fulfillmentType": "string"
}, - "ebayInternationalShipping": {
- "returnsManagedBy": "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"
}
]
}Important! Due to EU & UK Payments regulatory requirements, an additional security verification via Digital Signatures is required for certain API calls that are made on behalf of EU/UK sellers, including issueRefund. Please refer to Digital Signatures for APIs to learn more on the impacted APIs and the process to create signatures to be included in the HTTP payload.
| order_id required | string The unique identifier of the order. Order IDs are returned in the getOrders method (and GetOrders call of Trading API). The issueRefund method supports the legacy API Order IDs and REST API order IDs. |
| X-EBAY-C-MARKETPLACE-ID | string This header identifies the seller's eBay marketplace. It is required for all marketplaces outside of the US. See HTTP request headers for the marketplace ID values. |
| reasonForRefund | string The enumeration value passed into this field indicates the reason for the refund. One of the defined enumeration values in the ReasonForRefundEnum type must be used. |
| comment | string This free-text field allows the seller to clarify why the refund is being issued to the buyer. |
Array of objects (RefundItem) The refundItems array is only required if the seller is issuing a refund for one or more individual order line items in a multiple line item order. Otherwise, the seller just uses the orderLevelRefundAmount container to specify the amount of the refund for the entire order. | |
object (SimpleAmount) This type defines the monetary value of the refund amount, and the currency used. |
{- "reasonForRefund": "string",
- "comment": "string",
- "refundItems": [
- {
- "refundAmount": {
- "currency": "string",
- "value": "string"
}, - "lineItemId": "string",
- "legacyReference": {
- "legacyItemId": "string",
- "legacyTransactionId": "string"
}
}
], - "orderLevelRefundAmount": {
- "currency": "string",
- "value": "string"
}
}Use this call to retrieve the contents of all fulfillments currently defined for a specified order based on the order's unique identifier, orderId. This value is returned in the getOrders call's members.orderId field when you search for orders by creation date or shipment status.
| orderId required | string The unique identifier of the order. Order ID values are shown in My eBay/Seller Hub, and are also returned by the getOrders method in the orders.orderId field. |
{- "fulfillments": [
- {
- "fulfillmentId": "string",
- "lineItems": [
- {
- "lineItemId": "string",
- "quantity": 0
}
], - "shipmentTrackingNumber": "string",
- "shippedDate": "string",
- "shippingCarrierCode": "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"
}
]
}When you group an order's line items into one or more packages, each package requires a corresponding plan for handling, addressing, and shipping; this is a shipping fulfillment. For each package, execute this call once to generate a shipping fulfillment associated with that package.
Note: A single line item in an order can consist of multiple units of a purchased item, and one unit can consist of multiple parts or components. Although these components might be provided by the manufacturer in separate packaging, the seller must include all components of a given line item in the same package.
Before using this call for a given package, you must determine which line items are in the package. If the package has been shipped, you should provide the date of shipment in the request. If not provided, it will default to the current date and time.
| orderId required | string The unique identifier of the order. Order ID values are shown in My eBay/Seller Hub, and are also returned by the getOrders method in the orders.orderId field. |
fulfillment payload
Array of objects (LineItemReference) This array contains a list of or more line items and the quantity that will be shipped in the same package. | |
| shippedDate | string This is the actual date and time that the fulfillment package was shipped. This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock. The seller should use the actual date/time that the package was shipped, but if this field is omitted, it will default to the current date/time. |
| shippingCarrierCode | string The unique identifier of the shipping carrier being used to ship the line item(s). Technically, the shippingCarrierCode and trackingNumber fields are optional, but generally these fields will be provided if the shipping carrier and tracking number are known. |
| trackingNumber | string The tracking number provided by the shipping carrier for this fulfillment. The seller should be careful that this tracking number is accurate since the buyer will use this tracking number to track shipment, and eBay has no way to verify the accuracy of this number. |
{- "lineItems": [
- {
- "lineItemId": "string",
- "quantity": 0
}
], - "shippedDate": "string",
- "shippingCarrierCode": "string",
- "trackingNumber": "string"
}{ }Use this call to retrieve the contents of a fulfillment based on its unique identifier, fulfillmentId (combined with the associated order's orderId). The fulfillmentId value was originally generated by the createShippingFulfillment call, and is returned by the getShippingFulfillments call in the members.fulfillmentId field.
| fulfillmentId required | string The unique identifier of the fulfillment. This eBay-generated value was created by the Create Shipping Fulfillment call, and returned by the getShippingFulfillments call in the fulfillments.fulfillmentId field; for example, |
| orderId required | string The unique identifier of the order. Order ID values are shown in My eBay/Seller Hub, and are also returned by the getOrders method in the orders.orderId field. |
{- "fulfillmentId": "string",
- "lineItems": [
- {
- "lineItemId": "string",
- "quantity": 0
}
], - "shipmentTrackingNumber": "string",
- "shippedDate": "string",
- "shippingCarrierCode": "string"
}