Managing documents

eBay allows sellers to upload documents and associate them with their listings. This helps sellers to 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:

Field	Description	Required?
documentType	Indicates the type of document. Set this field to one of the DocumentTypeEnum values.	Yes
languages	Indicates the language of the document. Set this field to one of the LanguageEnum values.	Yes

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.

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, as shown below:

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 be 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. For example: 

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

A successful uploadDocument method will return a 200 OK HTTP status code.

The seller can track the upload status of the document file upload, and get additional metadata on the uploaded document by using the getDocument method, which is described in the next section.

Retrieve document details

Sellers can use the getDocument method of the Media API to retrieve details on a specific document that has been uploaded with the Media API. The data that is returned in the response payload will vary 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, as shown below:

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.

Inventory API

When adding documents to listings using the Inventory API, use the regulatory.documents.documentId field of the createOffer method in Inventory API. An example documents container is shown below: 

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

The GetOffer method can be used by the seller to verify if the document was added to the listing. If the document was successfully added to the listing, the same regulatory.documents.documentId field will be returned in the response.

Trading API

The following Trading API calls also support adding a document to a listing.

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

For the Trading API calls above, use the Item.Documents.Document.DocumentID to field to add a document to a listing. An example Documents container is shown below:

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

A GetItem call can be used by the seller to verify if the document was added to the listing. If the document was successfully added to the listing, the same Item.Documents.Document.DocumentID field will be returned in the response. This field will only be returned if the seller of the listing is making the GetItem call.

Remove documents from listings

Once a document has been 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, the seller can pass in an empty documents array. This removes all documents from a listing.

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.

Sellers can then use the getOffer method to verify that a document was removed from a the listing. If a document was successful removed, the documentId field for the specified document will not be returned in the response.

Trading API

To remove all documents from the listing using the Revise or Relist Trading calls, the seller can include a DeletedField tag in the request and set its value to Item.Regulatory.Documents. So, it will look like the following 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 will be removed from the listing. Sellers can also 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, and omit the DocumentID of the document to be removed.

Similar to the Add use case, the seller could call GetItem to verify if the document(s) were removed from the listing. If a document was successfully removed, the Regulatory.Documents.Document.DocumentID field will not be returned at all in the GetItem response.