POST/post_order/document
This method uploads a document for post‑order processes (for example, a seller providing a return shipping label).
Supported file types include .PDF, .JPEG/.JPG, .BMP, .GIF and .PNG, with a maximum file size of 5 MB (5,242,880 bytes).
Note: This method is currently restricted and requires a special OAuth scope not available to all users.
Note: Animated and multi-page PNG files are not currently supported. For multi-page content, use PDF. The maximum number of pages allowed varies by the documentUsageType.
Send a multipart/form‑data request with:
- file: the document file (
key: file) - documentUsageType: for example,
RETURN_SHIPPING_LABEL - entityType: for example,
RETURNS - entityId: the unique identifier for the post-order entity
A successful call returns the HTTP Status Code 201 Created with the document ID in the Location header (no response body is returned). The document’s initial state is SUBMITTED. When its identifier is associated with a post-order entity through an eBay GraphQL mutation, the state changes to PUBLISHED.
Note: A post-order entity is part of eBay's order management for activities after purchase (such as returns).
Important!
- Capture and retain the documentId in the response’s Location header. It is required to use the other post_order methods and to associate the document with a post-order entity.
- All documents (published or submitted) expire and become inaccessible after their expiration date.
- All POST methods in the Media API, including this method, are subject to short-duration, user-level rate limits: 50 requests per 5 seconds.
Input
Resource URI
This method is supported in Sandbox environment. To access the endpoint, just replace the apiz.ebay.com root URI with apiz.sandbox.ebay.com
URI parameters
This method has no URI parameters.
HTTP request headers
All requests made to eBay REST operations require you to provide the Authorization HTTP header for authentication authorization.
The table below shows additional HTTP request headers that are either required, conditionally required, or strongly recommended for this method. Other standard HTTP request headers- opens rest request components page (not in this table) can also be used, but they are optional.
| Header | Type | Description |
|---|---|---|
| Content-Type | string | This header indicates the format of the request body provided by the client. Its value should be set to multipart/form-data. For more information, refer to HTTP request headers. Occurrence: Required |
OAuth scope
This request requires an access token created with the authorization code grant flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application):
https://api.ebay.com/oauth/api_scope/commerce.post_order.document
See OAuth access tokens for more information.
Request payload
This call does not use a JSON request payload, but uploads files using multipart form data with information about the form data in the key-value pairs. For example:
file: @"/C:/Users/.../your_shipping_label.png" documentUsageType: "RETURN_SHIPPING_LABEL" entityType: "RETURNS" entityId: "1****-***2"
This call has no payload.
Request fields
This call has no field definitions.
Output
HTTP response headers
See HTTP response headers for details.
| Header | Meaning |
|---|---|
| Location | The location response header contains the URI of the newly created document ID in the format: https://apiz.ebay.com/commerce/media/v1_beta/post_order/document/{documentId}Clients can extract the documentId from this URI to perform subsequent operations such as downloadDocument or removeDocument (using this resource), or to associate this document with a post-order entity (such as through an eBay GraphQL mutation). |
Response payload
This call has no payload.
Response fields
This call has no field definitions.
HTTP status codes
This call can return one of the following HTTP status codes. For an overview of the status codes, see HTTP status codes in Using eBay RESTful APIs.
| Status | Meaning |
|---|---|
| 201 | Created |
| 400 | Bad Request |
| 401 | Unauthorized |
| 404 | Not Found |
| 500 | Internal Server Error |
Error codes
For more on errors, plus the codes of other common errors, see Handling errors.
| Code | Domain | Category | Meaning |
|---|---|---|---|
| 190000 | API_MEDIA | APPLICATION | There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. |
| 190013 | API_MEDIA | REQUEST | Unauthorized access. |
| 190300 | API_MEDIA | REQUEST | Invalid or unknown post-order entity identifier supplied in the request. |
| 190303 | API_MEDIA | REQUEST | Invalid post-order entity type supplied in the request. |
| 190304 | API_MEDIA | REQUEST | Invalid document usage type supplied in the request. |
| 190305 | API_MEDIA | REQUEST | The post-order entity type is missing from the request. |
| 190306 | API_MEDIA | REQUEST | The post-order entity identifier is missing from the request. |
| 190307 | API_MEDIA | REQUEST | The document usage type is missing from the request. |
| 190309 | API_MEDIA | REQUEST | The uploaded file format is not supported. Supported formats are: jpeg, png, bmp, gif, jpg, and pdf. |
| 190310 | API_MEDIA | REQUEST | The uploaded PDF exceeds the maximum allowed number of pages. |
| 190311 | API_MEDIA | REQUEST | The post-order entity state does not allow new documents for the specified usage type. |
| 190312 | API_MEDIA | REQUEST | The maximum number of documents for the specified post-order entity has been reached. |
| 190313 | API_MEDIA | REQUEST | The uploaded file could not be processed. Please upload a valid file. |
| 190314 | API_MEDIA | REQUEST | The uploaded file exceeds the maximum allowed size of 5 MB. |
| 190315 | API_MEDIA | REQUEST | The file is missing from the request. Please upload a valid file. |
Warnings
This call has no warnings.
Samples
New to making API calls? Please see Making a Call.
Note: Identifiers, such as order IDs or user IDs, and personal data in these samples might be anonymized or may no longer be active on eBay. If necessary, substitute current, relevant eBay data in your requests.
Sample 1: Upload a post-order document
This sample uploads a document.
Input
Although there is no JSON request payload, information about the form data is sent as key-value pairs.
POSThttps://apiz.ebay.com/commerce/media/v1_beta/post_order/document
Output
If the call is successful, an HTTP status of 201 Created will be returned with the document ID URI returned in the Location header.