File basics

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.

Every File object contains a unique identifier, which you can use 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

In the request, file should adhere to the RFC 2388 specification, which defines file transfers for the multipart/form-data protocol.

The purpose parameter should describe the function of the file.

If you're providing Digital River with a customer's tax document, set purpose to tax_document_customer_upload. For details, refer to Collecting tax certificates on the Setting up tax exemptions page.

For some orders, Digital River generates a file whose purpose is customer_tax_invoice and/or customer_credit_memo. For details, refer to Accessing invoices and credit memos.

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.

Link expiration

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:

File

{
  "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

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 id to retrieve, search for, and delete files. You'll also need it to create a file link to share with customers.

Links

Files may contain an array of publicly accessible file links. If no links have been generated, however, then links[] does not exist.

Size and type

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

URL

The url allows you to download a file for internal use.

Using a file

Once a file is created, you can download it for internal use or create a publicly accessible link.

Downloading a file for internal use

You can use url to download a document for internal use. But to get the file's content, you must provide your secret (confidential) API key.

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."
        }
    ]
}

As a result, don't share url with your customers. Create a public link if you'd like to provide them access to a document.

Creating a publicly accessible link

To share files with customers, create a file link.