Uploading Files for Mutations

Some of our mutations require merchants to upload files along with their calls to the GraphQL API. Since GraphQL does not natively support file uploads, this involves delivering a payload with a different Content-Type and an attached file. We partially implement the GraphQL Multipart Request Spec, but we only offer support for uploading a single file at a time. Currently, the only mutation that requires this is createDisputeFileEvidence. If you are uploading a file with this mutation, your mutation will look like this:

mutation CreateDisputeFileEvidence($input: CreateDisputeFileEvidenceInput!) {
  createDisputeFileEvidence(input: $input) {
    dispute {
      id
    }
    evidence {
      id
      category
      createdAt
      sentToProcessorAt
      url
    }
  }
}

Then you will need to tweak your Content-Type and attach a file along with that mutation when you actually make the request.

This mutation supports files of these types: PNG, JPG, JPEG, and PDF. Files uploaded with this mutation must be 1 MB or less.

A sample request might look like this:

curl https://payments.sandbox.braintree-api.com/graphql \
  -H "Braintree-Version: 2021-06-01" -H "Authorization: BASE64_ENCODED(YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY)" -H "Accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -F 'operations={ "query": "mutation CreateDisputeFileEvidence($input: CreateDisputeFileEvidenceInput!) { createDisputeFileEvidence(input: $input) { evidence { id url } } }", "variables": { "input": { "disputeId": "YOUR_DISPUTE_ID" }, "file": null } };type=application/json' \
  -F map='{ "file_to_upload": "variables.file" }' \
  -F 'file_to_upload=@YOUR_IMAGE.png;type=image/jpg'

The important things to notice here are:

1. The -H "Content-Type: multipart/form-data" header change, instead of application/json. This allows us to upload files to GraphQL.
2. The -F flag with an operations object. The operations name is required. This is where you will pass your GraphQL query and variables, as you would for any other GraphQL API operation. Note that you must specify a type of application/json.
3. The "file": null key/value pair somewhere in your operations JSON object. The path to this file key must be specified in the map (see below).
4. The -F flag with the location of the file to upload on your system, as well as the file type. The file type must be a valid MIME type.
5. The -F flag with a map object. The map name is required. This is what links the location of the file key in your operations JSON (at variables.file in this example) to the label (file_to_upload in this example) specifying where the file path and type are specified.

The Braintree-Version and Authorization headers are the same as a standard GraphQL request.

The response to this mutation will be structured identically to any other GraphQL API response.