Links

Files

Learn about the files resource
The Files resource represents a customer-related document that is hosted on Digital River's servers. You can use the Files API to upload, retrieve, search for, download, and delete files.
In certain business use cases, you may need to upload a customer's tax documents. As an example, your integration might handle purchases from US-based business customers who use tax certificates. By specifying a file and its purpose and then submitting a POST/files request, you can perform this document upload.
Other files, such as tax invoices and credit memos, are generated by Digital River. You can listen for webhook events that inform you when these types of files are created.
Once created, every File object contains a unique identifier. You can use this identifier to download a file for internal use or create a publicly-accessible link to a document.

Creating a file

To upload a customer's tax documents to our servers, define a file and then submit a create file request.

Defining a file

When defining a file, you're only required to designate a file and its purpose. Providing a name and title, along with specifying a link expiration time, are optional values.

File and purpose

The file you upload should adhere to the RFC 2388 specification. This specification defines file transfers for the multipart/form-data protocol.
The purpose parameter describes the function of the file. Use the tax_document_customer_upload value when providing Digital River a customer's tax document. This is typically used for tax certificates. The supported file formats are CSV, JPG, PDF, PNG and the maximum upload size is 10 MB.
For some orders, Digital River generates a customer_tax_invoice and customer_credit_memo that you can retrieve in PDF format.

Name and title

In the request, you have the option of sending a fileName that is suitable for saving to a filesystem as well as a user-friendly title for the document.
If you provide a linkExpiresTime, make sure the value adheres to the date and time format used in the Digital River APIs.

Submitting a create file request

In your POST/files requests, set the Content-Type header to multipart/form-data:
POST/files
curl https://api.digitalriver.com/files \
-u <API_key>: \
-d file="@/path/file.jpg" \
-d purpose="tax_document_customer_upload" \
-d fileName="file.png" \
-d title="My 2019 Tax Certificate."
A 201 Created response returns a File object:
JSON
{
"id": "file_09e2464f-9b4f-482b-ae89-732183c705be",
"createdTime": "2018-04-25T20:36:00Z",
"fileName": "file.png",
"purpose": "tax_document_customer_upload",
"title": "My 2019 Tax Certificate.",
"size": 72334,
"type": "png",
"url": "https://files.digitalriver.com/files/file_17a0cab7-1ff7-478e-99f9-d4e753dec24d/contents",
"liveMode": false
}

The File object

Once created, every File object contains a unique identifier that can be used to retrieve, search for and delete a file. The object also contains a non-publicly accessible URL.
File
{
"id": "62e30acb-1c24-40fc-8a98-db8e3d479c78",
"createdTime": "2021-05-24T09:10:49Z",
"fileName": "GCINIE6426071CGB20190000000000284082939532120039586.pdf",
"links": [
{
"id": "7e20a925-32b1-434b-b704-366b19b8afd2",
"createdTime": "2021-05-24T22:11:54Z",
"expired": false,
"expiresTime": "2021-05-26T13:47:13Z",
"liveMode": false,
"url": "https://files-test.digitalriver.com/links/7e20a925-32b1-434b-b704-366b19b8afd2"
}
],
"purpose": "customer_invoice",
"title": "customer invoice",
"size": 35776,
"type": "pdf",
"url": "https://api.digitalriver.com/files/62e30acb-1c24-40fc-8a98-db8e3d479c78/content",
"liveMode": false
}

Unique identifier

You can use a File object's unique identifier to retrieve, search for, and delete files. You'll also need it to create a file link that can be shared with customers.
The object may contain an array of publicly-accessible File Links. If no links have been generated, however, then the links array is not returned.

Size and type

A file's size is represented in bytes and its type signifies a format (e.g. pdf, jpg, or png)

URL

Using a file

Downloading a file for internal use

You can use a File's url to download a document for internal use. To access a document through the url, you must use your secret (confidential) API key. Since customers won't be able to download the file, you should not share a url with them. If you'd like to provide customers access to a document, create a public link to the file.
A request sent with the wrong key returns a 401 Unauthorized response status code.
GET /files/{fileId}/content
{
"type": "unauthorized",
"errors": [
{
"message": "An authorization error has occurred."
}
]
}
To share files with customers, create a file link. These publicly accessible links are especially useful for orders that contain Digital River generated tax invoices and credit memos.
Last modified 1mo ago