Managing documents

eBay allows sellers to upload documents and associate them with their listings. This helps sellers comply with product safety and compliance regulations like the General Product Safety Regulations (GPSR).

This capability is contained in the Media API, which has methods to create, upload, and retrieve the document. To add document links to listings, use the regulatory.documents.documentId field of the createOffer method in the Inventory API, or the Add/Revise/Relist calls of the Trading API with the Regulatory.Documents.Document.DocumentID field (for example, in the AddFixedPriceItem call you would use the DocumentID field).

Create a document resource

Create the document resource using the createDocument method. The request payload of the createDocument method has the following fields:

If a createDocument method is successful, a 201 Created HTTP status code is returned along with a newly-created document ID value documentId field of the response payload. For convenience, newly-created document ID value is also returned in the in the location response header.

Store this document ID value, as it will be needed for the uploadDocument method, the getDocument method, and will also be used when it's time to upload the inventory item using the createOffer method in Inventory API or the Add/Revise/Relist calls of the Trading API in the Regulatory.Documents.Document.DocumentID field (for example, in the AddFixedPriceItem call you would use the DocumentID field).

Upload the document file

Upload the document using the uploadDocument method. The document ID returned in the createDocument method is passed in as part of the URI:

POST https://api.ebay.com/commerce/media/v1/document/{document_id}/upload

The uploadDocument method has no request payload, but you upload a file to the endpoint. To accommodate the upload of this file , the Content-Type request header is required with its value set to "multipart/form-data". This method does not use a JSON payload, but uploads the file as form-data. Only the file parameter is required. The maximum allowed document upload size is 10 MB (10485760 bytes). For example: 

file: @"/C:/Users/.../drone_user_warranty.pdf"

A successful uploadDocument method returns a 200 OK HTTP status code. Track the upload status of the document file upload and get additional metadata on the uploaded document using the getDocument method.

Download a document from a URL

Download documents from a URL using the createDocumentFromUrl method. With this method, you do not have to create a document resource using the createDocument method, nor upload the document using uploadDocument. Instead, the document is downloaded directly from the URL provided in the documentUrl field and added to the user's account. The maximum allowed size for a document to download is 10 MB (10485760 bytes), and must be a .pdf, .png, .jpg, or .jpeg file.

A successful createDocumentFromUrl method returns a 201 Created HTTP status code and the document is added to the user's account. Track the status of the document and get additional metadata on the document using the getDocument method described in the next section.

Retrieve document details

Use the getDocument method of the Media API to retrieve details on a specific document uploaded with the Media API. The data that returned in the response payload varies based on the processing status. There is no request payload for the getDocument method, but the document ID of the document must be passed into the call URI:

GET https://api.ebay.com/commerce/media/v1/document/{document_id}

Add documents to listings

Add a document created with the Media API to an eBay listing using the Inventory API or the Add/Revise/Relist calls of the Trading API. Unlike the Media API, which uploads one document per call, both the Inventory API and Trading API let you attach multiple documents to the listing being created or updated. A document must have the ACCEPTED status to be added to a listing. Use the getDocument method of the Media API to retrieve the status of the document. See DocumentStatusEnum for supported values.

Inventory API

When adding documents to listings using the Inventory API, use the regulatory.documents.documentId field of the createOffer method in Inventory API. Here is a sample documents container: 

"regulatory": {
  ...		
  "documents": [ 
    {		
      "documentId": "a********9"	
    }				
  ]		
  ...			
}																		

Use the getOffer method to verify if the document was added to the listing. If the add was successful, the same regulatory.documents.documentId field is returned in the response.

Trading API

These Trading API calls also support adding documents to a listing:

• AddFixedPriceItem
• AddItem
• AddItems
• RelistFixedPriceItem
• RelistItem
• ReviseFixedPriceItem
• ReviseItem
• VerifyAddItem
• VerifyAddFixedPriceItem
• VerifyRelistItem

Use the Sell Feed APIto add document links to listings in bulk as an LMS Feed. Use the Inventory upload feed type associated with the applicable Trading API call.

For the Trading API calls above, use the Item.Documents.Document.DocumentID field to add a document to a listing. Here is a sample Documents container:

<Regulatory> 
  ...				
  <Documents>				
    <Document>	
      <DocumentID>a********9</DocumentID>
    </Document>	
  </Documents>
  ...				
</Regulatory>												

Use a GetItem call to verify if the document was added to the listing. If the add was successful, the same Item.Documents.Document.DocumentID field is returned in the response. This field is only returned if the you are making the GetItem call.

Remove documents from listings

Once a document is added to a listing, it can be removed through either the updateOffer method of the Inventory API or the Revise or Relist calls of the Trading API.

Inventory API

To remove all documents from a listing using the updateOffer method, pass in an empty documents array.

To remove a specific document from a listing using the updateOffer method, pass in the documents array and omit the documentId of the document to be removed.

Use the getOffer method to verify that a document was removed from the listing. If the removal was successful, the documentId field for the specified document is not returned in the response.

Trading API

To remove all documents from the listing using the Revise or Relist Trading calls, include a DeletedField tag in the request and set its value to Item.Regulatory.Documents. It looks like this in a ReviseItem request payload:

<?xml version="1.0" encoding="utf-8"?>
  <ReviseItemRequest xmlns="urn:ebay:apis:eBLBaseComponents">
    <DeletedField>Item.Regulatory.Documents</DeletedField>
    ...
  </ReviseItemRequest>

If the Revise call is successful, all documents are removed from the listing. Alternatively, pass in an empty Documents container to remove all documents associated with a listing.

To remove a specific document from a listing using the Revise or Relist calls, pass in the Documents container again but omit the DocumentID of the document to be removed.

Similar to the Add use case, call GetItem to verify if the document(s) were removed from the listing. If the removal was successful, the Regulatory.Documents.Document.DocumentID field is not returned in the GetItem response.