Core Resources
Payment Methods
Products
Checkout
Payment Links
Billing
Connect
Fraud
Issuing
Terminal
Treasury
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Webhooks
Sign in →

Files

This object represents files hosted on Stripe’s servers. You can upload files with the create file request (for example, when uploading dispute evidence). Stripe also creates files independently (for example, the results of a Sigma scheduled query).

Related guide: File upload guide

Endpoints

The File object

Attributes

  • idstring

    Unique identifier for the object.

  • purposeenum

    The purpose of the uploaded file.

    Possible enum values
    account_requirement

    Additional documentation requirements that can be requested for an account.

    additional_verification

    Additional verification for custom accounts.

    business_icon

    A business icon.

    business_logo

    A business logo.

    customer_signature

    Customer signature image.

    dispute_evidence

    Evidence to submit with a dispute response.

    finance_report_run

    User-accessible copies of query results from the Reporting dataset.

    identity_document

    A document to verify the identity of an account owner during account provisioning.

    identity_document_downloadable

    Image of a document collected by Stripe Identity.

    pci_document

    A self-assessment PCI questionnaire.

    Show 4 more

  • typenullable string

    The returned file type (for example, csv, pdf, jpg, or png).

More attributes

  • objectstring

  • createdtimestamp

  • expires_atnullable timestamp

  • filenamenullable string

  • linksnullable object

  • sizeinteger

  • titlenullable string

  • urlnullable string

The File object
{
  "id": "file_1Mr4LDLkdIwHu7ixFCz0dZiH",
  "object": "file",
  "created": 1680116847,
  "expires_at": 1703444847,
  "filename": "file.png",
  "links": {
    "object": "list",
    "data": [],
    "has_more": false,
    "url": "/v1/file_links?file=file_1Mr4LDLkdIwHu7ixFCz0dZiH"
  },
  "purpose": "dispute_evidence",
  "size": 8429,
  "title": null,
  "type": "png",
  "url": "https://files.stripe.com/v1/files/file_1Mr4LDLkdIwHu7ixFCz0dZiH/contents"
}

Create a file

To upload a file to Stripe, you need to send a request of type multipart/form-data. Include the file you want to upload in the request, and the parameters for creating a file.

All of Stripe’s officially supported Client libraries support sending multipart/form-data.

Parameters

  • fileobjectRequired

    A file to upload. Make sure that the specifications follow RFC 2388, which defines file transfers for the multipart/form-data protocol.

  • purposeenumRequired

    The purpose of the uploaded file.

    Possible enum values
    account_requirement

    Additional documentation requirements that can be requested for an account.

    additional_verification

    Additional verification for custom accounts.

    business_icon

    A business icon.

    business_logo

    A business logo.

    customer_signature

    Customer signature image.

    dispute_evidence

    Evidence to submit with a dispute response.

    identity_document

    A document to verify the identity of an account owner during account provisioning.

    pci_document

    A self-assessment PCI questionnaire.

    tax_document_user_upload

    A user-uploaded tax document.

    terminal_reader_splashscreen

    Splashscreen to be displayed on Terminal readers.

More parameters

  • file_link_dataobject

Returns

Returns the file object.

POST /v1/files
curl https://files.stripe.com/v1/files \
  -u sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -F purpose=dispute_evidence \
  -F file="@/path/to/a/file.jpg"
Response
{
  "id": "file_1Mr4LDLkdIwHu7ixFCz0dZiH",
  "object": "file",
  "created": 1680116847,
  "expires_at": 1703444847,
  "filename": "file.png",
  "links": {
    "object": "list",
    "data": [],
    "has_more": false,
    "url": "/v1/file_links?file=file_1Mr4LDLkdIwHu7ixFCz0dZiH"
  },
  "purpose": "dispute_evidence",
  "size": 8429,
  "title": null,
  "type": "png",
  "url": "https://files.stripe.com/v1/files/file_1Mr4LDLkdIwHu7ixFCz0dZiH/contents"
}

Retrieve a file

Retrieves the details of an existing file object. After you supply a unique file ID, Stripe returns the corresponding file object. Learn how to access file contents.

Parameters

No parameters.

Returns

If the identifier you provide is valid, a file object returns. If not, Stripe raises an error.

GET /v1/files/:id
curl https://api.stripe.com/v1/files/@/path/to/a/file.png \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:"
Response
{
  "id": "file_1Mr4LDLkdIwHu7ixFCz0dZiH",
  "object": "file",
  "created": 1680116847,
  "expires_at": 1703444847,
  "filename": "file.png",
  "links": {
    "object": "list",
    "data": [],
    "has_more": false,
    "url": "/v1/file_links?file=file_1Mr4LDLkdIwHu7ixFCz0dZiH"
  },
  "purpose": "dispute_evidence",
  "size": 8429,
  "title": null,
  "type": "png",
  "url": "https://files.stripe.com/v1/files/file_1Mr4LDLkdIwHu7ixFCz0dZiH/contents"
}

List all files

Returns a list of the files that your account has access to. Stripe sorts and returns the files by their creation dates, placing the most recently created files at the top.

Parameters

  • purposestring

    Filter queries by the file purpose. If you don’t provide a purpose, the queries return unfiltered files.

More parameters

  • createdobject

  • ending_beforestring

  • limitinteger

  • starting_afterstring

Returns

A dictionary with a data property that contains an array of up to limit files, starting after the starting_after file. Each entry in the array is a separate file object. If there aren’t additional available files, the resulting array is empty.

GET /v1/files
curl -G https://api.stripe.com/v1/files \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
  -d limit=3
Response
{
  "object": "list",
  "url": "/v1/files",
  "has_more": false,
  "data": [
    {
      "id": "file_1Mr4LDLkdIwHu7ixFCz0dZiH",
      "object": "file",
      "created": 1680116847,
      "expires_at": 1703444847,
      "filename": "file.png",
      "links": {
        "object": "list",
        "data": [],
        "has_more": false,
        "url": "/v1/file_links?file=file_1Mr4LDLkdIwHu7ixFCz0dZiH"
      },
      "purpose": "dispute_evidence",
      "size": 8429,
      "title": null,
      "type": "png",
      "url": "https://files.stripe.com/v1/files/file_1Mr4LDLkdIwHu7ixFCz0dZiH/contents"
    }
    {...}
    {...}
  ],
}
Stripe Shell
Test mode

Welcome to the Stripe Shell!

Stripe Shell is a browser-based shell with the Stripe CLI pre-installed. Log in to your
Stripe account and press Control + Backtick (`) on your keyboard to start managing your Stripe
resources in test mode.

- View supported Stripe commands: 
- Find webhook events: 
- Listen for webhook events: 
- Call Stripe APIs: stripe [api resource] [operation] (e.g., )
The Stripe Shell is best experienced on desktop.
$