Files

A File is an entity that can store a physical file and some metadata. It also provides an easy access to its size, mime-type, user-defined tags and description thus allowing easy sorting and searching among stored files. There are several methods of file uploading available: multipart/form-data encoded form, RAW POST (by sending file contents as POST body), fetching from URL (by providing the file URL via 'url' param) Attachment is an entity that is used to link a File to one or multiple objects like Customer, Dispute, Payment, Transaction, Order, Plan, Product, Invoice, Note. That allows to quickly find and use files related to those specific entities.

Retrieve a list of Attachments

Retrieve a list of attachments. You may sort by the id, name, relatedId, relatedType, fileId, createdTime, and updatedTime.

SecuritySecretApiKey or JWT
Request
query Parameters
limit
integer [ 0 .. 1000 ]

The collection items limit.

offset
integer >= 0

The collection items offset.

filter
string

The collection items filter requires a special format. Use "," for multiple allowed values. Use ";" for multiple fields. See the filter guide for more options and examples about this format.

q
string

The partial search of the text fields.

expand
string

Expand a response to get a full related object included inside of the _embedded path in the response. It accepts a comma-separated list of objects to expand. See the expand guide for more info.

fields
string

Limit the returned fields to the list specified, separated by comma. Note that id is always returned.

sort
Array of strings

The collection items sort field and order (prefix with "-" for descending sort).

Responses
200

A list of Attachments was retrieved successfully.

Response Headers
Pagination-Total
integer

Total items count.

Pagination-Limit
integer

Items per page limit.

Pagination-Offset
integer

Pagination offset.

Response Schema: application/json
Array
fileId
required
string

Linked File object id.

relatedId
required
string

Linked object Id.

relatedType
required
string

Linked object type.

Enum: "customer" "customer-timeline-comment" "customer-edd-timeline-comment" "dispute" "gateway-timeline-comment" "invoice" "invoice-timeline-comment" "order-timeline-comment" "organization" "payment" … 5 more
id
string <= 50 characters

The resource ID. Defaults to UUID v4.

name
string

The Original Attachment name.

description
string

The Attachment description.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

Array of SelfLink (object) or FileLink (object) or AttachmentResourceLink (object) >= 3 items

The links related to resource.

Array (>= 3 items)
Any of:
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

Array of FileEmbed (object) non-empty

Any embedded objects available that are requested by the expand querystring parameter.

Array (non-empty)
Any of:

File object.

object (File)
401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

get/attachments
Request samples
$attachments = $client->attachments()->search([
    'filter' => 'relatedType:customer',
]);
Response samples
application/json
[
  • {
    }
]

Create an Attachment

Create an Attachment.

SecuritySecretApiKey or JWT
Request
Request Body schema: application/json

Attachment resource.

fileId
required
string

Linked File object id.

relatedId
required
string

Linked object Id.

relatedType
required
string

Linked object type.

Enum: "customer" "customer-timeline-comment" "customer-edd-timeline-comment" "dispute" "gateway-timeline-comment" "invoice" "invoice-timeline-comment" "order-timeline-comment" "organization" "payment" … 5 more
name
string

The Original Attachment name.

description
string

The Attachment description.

Responses
201

Attachment was created.

Response Schema: application/json
fileId
required
string

Linked File object id.

relatedId
required
string

Linked object Id.

relatedType
required
string

Linked object type.

Enum: "customer" "customer-timeline-comment" "customer-edd-timeline-comment" "dispute" "gateway-timeline-comment" "invoice" "invoice-timeline-comment" "order-timeline-comment" "organization" "payment" … 5 more
id
string <= 50 characters

The resource ID. Defaults to UUID v4.

name
string

The Original Attachment name.

description
string

The Attachment description.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

Array of SelfLink (object) or FileLink (object) or AttachmentResourceLink (object) >= 3 items

The links related to resource.

Array (>= 3 items)
Any of:
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

Array of FileEmbed (object) non-empty

Any embedded objects available that are requested by the expand querystring parameter.

Array (non-empty)
Any of:

File object.

object (File)
401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

409

Conflict.

422

Invalid data was sent.

post/attachments
Request samples
application/json
{
  • "fileId": "string",
  • "relatedType": "customer",
  • "relatedId": "string",
  • "name": "string",
  • "description": "string"
}
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "fileId": "string",
  • "relatedType": "customer",
  • "relatedId": "string",
  • "name": "string",
  • "description": "string",
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "_links": [
    ],
  • "_embedded": [
    ]
}

Retrieve an Attachment

Retrieve a Attachment with specified identifier string.

SecuritySecretApiKey or JWT
Request
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

Responses
200

Attachment was retrieved successfully.

Response Schema: application/json
fileId
required
string

Linked File object id.

relatedId
required
string

Linked object Id.

relatedType
required
string

Linked object type.

Enum: "customer" "customer-timeline-comment" "customer-edd-timeline-comment" "dispute" "gateway-timeline-comment" "invoice" "invoice-timeline-comment" "order-timeline-comment" "organization" "payment" … 5 more
id
string <= 50 characters

The resource ID. Defaults to UUID v4.

name
string

The Original Attachment name.

description
string

The Attachment description.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

Array of SelfLink (object) or FileLink (object) or AttachmentResourceLink (object) >= 3 items

The links related to resource.

Array (>= 3 items)
Any of:
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

Array of FileEmbed (object) non-empty

Any embedded objects available that are requested by the expand querystring parameter.

Array (non-empty)
Any of:

File object.

object (File)
401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

404

Resource was not found.

get/attachments/{id}
Request samples
$attachment = $client->attachments()->load('attachmentId');
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "fileId": "string",
  • "relatedType": "customer",
  • "relatedId": "string",
  • "name": "string",
  • "description": "string",
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "_links": [
    ],
  • "_embedded": [
    ]
}

Update the Attachment with predefined ID

Update the Attachment with predefined ID.

SecuritySecretApiKey or JWT
Request
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

Request Body schema: application/json

Attachment resource.

fileId
required
string

Linked File object id.

relatedId
required
string

Linked object Id.

relatedType
required
string

Linked object type.

Enum: "customer" "customer-timeline-comment" "customer-edd-timeline-comment" "dispute" "gateway-timeline-comment" "invoice" "invoice-timeline-comment" "order-timeline-comment" "organization" "payment" … 5 more
name
string

The Original Attachment name.

description
string

The Attachment description.

Responses
200

Attachment was updated.

Response Schema: application/json
fileId
required
string

Linked File object id.

relatedId
required
string

Linked object Id.

relatedType
required
string

Linked object type.

Enum: "customer" "customer-timeline-comment" "customer-edd-timeline-comment" "dispute" "gateway-timeline-comment" "invoice" "invoice-timeline-comment" "order-timeline-comment" "organization" "payment" … 5 more
id
string <= 50 characters

The resource ID. Defaults to UUID v4.

name
string

The Original Attachment name.

description
string

The Attachment description.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

Array of SelfLink (object) or FileLink (object) or AttachmentResourceLink (object) >= 3 items

The links related to resource.

Array (>= 3 items)
Any of:
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

Array of FileEmbed (object) non-empty

Any embedded objects available that are requested by the expand querystring parameter.

Array (non-empty)
Any of:

File object.

object (File)
201

Attachment was created.

Response Schema: application/json
fileId
required
string

Linked File object id.

relatedId
required
string

Linked object Id.

relatedType
required
string

Linked object type.

Enum: "customer" "customer-timeline-comment" "customer-edd-timeline-comment" "dispute" "gateway-timeline-comment" "invoice" "invoice-timeline-comment" "order-timeline-comment" "organization" "payment" … 5 more
id
string <= 50 characters

The resource ID. Defaults to UUID v4.

name
string

The Original Attachment name.

description
string

The Attachment description.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

Array of SelfLink (object) or FileLink (object) or AttachmentResourceLink (object) >= 3 items

The links related to resource.

Array (>= 3 items)
Any of:
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

Array of FileEmbed (object) non-empty

Any embedded objects available that are requested by the expand querystring parameter.

Array (non-empty)
Any of:

File object.

object (File)
401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

404

Resource was not found.

409

Conflict.

422

Invalid data was sent.

put/attachments/{id}
Request samples
application/json
{
  • "fileId": "string",
  • "relatedType": "customer",
  • "relatedId": "string",
  • "name": "string",
  • "description": "string"
}
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "fileId": "string",
  • "relatedType": "customer",
  • "relatedId": "string",
  • "name": "string",
  • "description": "string",
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "_links": [
    ],
  • "_embedded": [
    ]
}

Delete an Attachment

Delete the Attachment with predefined identifier string.

SecuritySecretApiKey or JWT
Request
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

Responses
204

Attachment was deleted.

401

Unauthorized access, invalid credentials were used.

404

Resource was not found.

delete/attachments/{id}
Request samples
$client->attachments()->delete('attachmentId');
Response samples
application/json
{
  • "status": 401,
  • "title": "string",
  • "detail": "string",
  • "instance": "string"
}

Retrieve a list of files

Retrieve a list of files.

SecuritySecretApiKey or JWT
Request
query Parameters
limit
integer [ 0 .. 1000 ]

The collection items limit.

offset
integer >= 0

The collection items offset.

filter
string

The collection items filter requires a special format. Use "," for multiple allowed values. Use ";" for multiple fields. See the filter guide for more options and examples about this format.

q
string

The partial search of the text fields.

expand
string

Expand a response to get a full related object included inside of the _embedded path in the response. It accepts a comma-separated list of objects to expand. See the expand guide for more info.

fields
string

Limit the returned fields to the list specified, separated by comma. Note that id is always returned.

sort
Array of strings

The collection items sort field and order (prefix with "-" for descending sort).

Responses
200

A list of Files was retrieved successfully.

Response Headers
Pagination-Total
integer

Total items count.

Pagination-Limit
integer

Items per page limit.

Pagination-Offset
integer

Pagination offset.

Response Schema: application/json
Array
id
string <= 50 characters

The resource ID. Defaults to UUID v4.

name
string

Original File name.

extension
string

The File extension.

description
string

The File description.

sourceType
string or null

The File source type.

Enum: "upload" "camera"
tags
Array of strings

The tags list.

mime
string

The mime type.

Enum: "image/png" "image/jpeg" "image/gif" "application/pdf" "audio/mpeg"
size
integer

The File size in bytes.

width
integer

Image width, applicable to images only.

height
integer

Image height, applicable to images only.

sha1
string

Hash sum of the file.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

isPublic
boolean

Is the file available publicly (without authentication). If true, the permalink in the _links section contains the public URL.

Array of SelfLink (object) or FileDownloadLink (object) or SignedLinkLink (object) or PermalinkLink (object) >= 3 items

The links related to resource.

Array (>= 3 items)
Any of:
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

get/files
Request samples
$files = $client->files()->search([
    'filter' => 'name:TestFile',
]);
Response samples
application/json
[
  • {
    }
]

Create a file

Additionally, a file can be sent with:.

  • multipart/form-data POST request: in this case all property names are the same as the JSON ones (file is an uploaded file)
  • file body request: the file body is sent as the request body, with the appropriate Content-Type. No additional properties can be set along the request data

The following file types only are allowed:

  • jpg
  • png
  • gif
  • pdf
  • mp3

If using a Publishable Api Key, only private files can be created. The files can later on be modified or used using a secret API key.

SecuritySecretApiKey or JWT or PublishableApiKey
Request
Request Body schema: application/json
One of:
file
required
string

The file in base64 encoded format.

isPublic
boolean

The File visibility. If public a permalink is provided.

name
string

The file name used for downloading.

description
string

The file description.

sourceType
string or null

The File source type.

Enum: "upload" "camera"
tags
Array of strings

The tags list.

Responses
201

File was created.

Response Schema: application/json
id
string <= 50 characters

The resource ID. Defaults to UUID v4.

name
string

Original File name.

extension
string

The File extension.

description
string

The File description.

sourceType
string or null

The File source type.

Enum: "upload" "camera"
tags
Array of strings

The tags list.

mime
string

The mime type.

Enum: "image/png" "image/jpeg" "image/gif" "application/pdf" "audio/mpeg"
size
integer

The File size in bytes.

width
integer

Image width, applicable to images only.

height
integer

Image height, applicable to images only.

sha1
string

Hash sum of the file.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

isPublic
boolean

Is the file available publicly (without authentication). If true, the permalink in the _links section contains the public URL.

Array of SelfLink (object) or FileDownloadLink (object) or SignedLinkLink (object) or PermalinkLink (object) >= 3 items

The links related to resource.

Array (>= 3 items)
Any of:
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

422

Invalid data was sent.

post/files
Request samples
application/json
{
  • "file": "R0lGODlhAQABAIAAAAUEBAAAACwAAAAAAQABAAACAkQBADs=",
  • "isPublic": false,
  • "name": "logo.png",
  • "description": "My file description",
  • "sourceType": "upload",
  • "tags": [
    ]
}
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "name": "string",
  • "extension": "string",
  • "description": "string",
  • "sourceType": "upload",
  • "tags": [
    ],
  • "mime": "image/png",
  • "size": 0,
  • "width": 0,
  • "height": 0,
  • "sha1": "string",
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "isPublic": true,
  • "_links": [
    ]
}

Retrieve a File Record

Retrieve a File with specified identifier string.

SecuritySecretApiKey or JWT
Request
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

Responses
200

File was retrieved successfully.

Response Schema: application/json
id
string <= 50 characters

The resource ID. Defaults to UUID v4.

name
string

Original File name.

extension
string

The File extension.

description
string

The File description.

sourceType
string or null

The File source type.

Enum: "upload" "camera"
tags
Array of strings

The tags list.

mime
string

The mime type.

Enum: "image/png" "image/jpeg" "image/gif" "application/pdf" "audio/mpeg"
size
integer

The File size in bytes.

width
integer

Image width, applicable to images only.

height
integer

Image height, applicable to images only.

sha1
string

Hash sum of the file.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

isPublic
boolean

Is the file available publicly (without authentication). If true, the permalink in the _links section contains the public URL.

Array of SelfLink (object) or FileDownloadLink (object) or SignedLinkLink (object) or PermalinkLink (object) >= 3 items

The links related to resource.

Array (>= 3 items)
Any of:
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

404

Resource was not found.

get/files/{id}
Request samples
$file = $client->files()->load('fileId');
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "name": "string",
  • "extension": "string",
  • "description": "string",
  • "sourceType": "upload",
  • "tags": [
    ],
  • "mime": "image/png",
  • "size": 0,
  • "width": 0,
  • "height": 0,
  • "sha1": "string",
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "isPublic": true,
  • "_links": [
    ]
}

Update the File with predefined ID

Update the File with predefined ID. Note that file can be uploaded with POST. only.

SecuritySecretApiKey or JWT
Request
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

Request Body schema: application/json

File resource.

name
string

Original File name.

extension
string

The File extension.

description
string

The File description.

sourceType
string or null

The File source type.

Enum: "upload" "camera"
tags
Array of strings

The tags list.

isPublic
boolean

Is the file available publicly (without authentication). If true, the permalink in the _links section contains the public URL.

Responses
200

File was updated.

Response Schema: application/json
id
string <= 50 characters

The resource ID. Defaults to UUID v4.

name
string

Original File name.

extension
string

The File extension.

description
string

The File description.

sourceType
string or null

The File source type.

Enum: "upload" "camera"
tags
Array of strings

The tags list.

mime
string

The mime type.

Enum: "image/png" "image/jpeg" "image/gif" "application/pdf" "audio/mpeg"
size
integer

The File size in bytes.

width
integer

Image width, applicable to images only.

height
integer

Image height, applicable to images only.

sha1
string

Hash sum of the file.

createdTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

updatedTime
string <date-time>

Read-only timestamp, automatically assigned on back-end.

isPublic
boolean

Is the file available publicly (without authentication). If true, the permalink in the _links section contains the public URL.

Array of SelfLink (object) or FileDownloadLink (object) or SignedLinkLink (object) or PermalinkLink (object) >= 3 items

The links related to resource.

Array (>= 3 items)
Any of:
rel
required
string

The link type.

Value: "self"
href
required
string

The link URL.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

404

Resource was not found.

422

Invalid data was sent.

put/files/{id}
Request samples
application/json
{
  • "name": "string",
  • "extension": "string",
  • "description": "string",
  • "sourceType": "upload",
  • "tags": [
    ],
  • "isPublic": true
}
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "name": "string",
  • "extension": "string",
  • "description": "string",
  • "sourceType": "upload",
  • "tags": [
    ],
  • "mime": "image/png",
  • "size": 0,
  • "width": 0,
  • "height": 0,
  • "sha1": "string",
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "isPublic": true,
  • "_links": [
    ]
}

Delete a File

Delete the File with predefined identifier string.

SecuritySecretApiKey or JWT
Request
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

Responses
204

File was deleted.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

404

Resource was not found.

delete/files/{id}
Request samples
$client->files()->delete('fileId');
Response samples
application/json
{
  • "status": 401,
  • "title": "string",
  • "detail": "string",
  • "instance": "string"
}

Download a file

Download a file.

SecuritySecretApiKey or JWT
Request
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

query Parameters
imageSize
string^[1-9]{1}[0-9]{1,3}x[1-9]{1}[0-9]{1,3}$

Resize image to specified size. Supports any sizes from 10x10 to 2000x2000 (format {width}x{height}). The image will be returned in the original size if the value is invalid. This parameter will be ignored for non-image files.

Example: imageSize=700x700
Responses
200

The file was retrieved successfully.

Response Headers
Content-Length
integer

The number of bytes in the file.

Content-Type
string

The MIME type of the file.

Response Schema: application/json
string
302

Resource was moved.

401

Unauthorized access, invalid credentials were used.

403

Access forbidden.

404

Resource was not found.

get/files/{id}/download
Request samples
const file = await api.files.download({id: 'my-file-id'});

// access the file ArrayBuffer to view the content 
console.log(file.data);
Response samples
application/json
"string"