Skip to main content

​
Overview

Files can be used as product media (images) or downloadable benefits. Polar provides presigned URLs for secure direct upload to S3.

​
The File Object

​
id
string
required
Unique identifier
​
name
string
required
File name
​
path
string
required
File path in storage
​
mime_type
string
required
MIME type (e.g., image/png)
​
size
integer
required
File size in bytes
​
upload_completed_at
string
When upload was completed
​
service
enum
required
Storage service: product_media or downloadable
​
organization_id
string
required
Organization ID
​
created_at
string
required
Creation timestamp

​
List Files

cURL
curl -X GET "https://api.polar.sh/v1/files" \
  -H "Authorization: Bearer polar_pat_..."

​
Query Parameters

​
organization_id
string
Filter by organization
​
ids
array
Filter by file IDs

​
Create File Upload

cURL
curl -X POST "https://api.polar.sh/v1/files" \
  -H "Authorization: Bearer polar_pat_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "product-image.png",
    "mime_type": "image/png",
    "size": 524288,
    "service": "product_media",
    "organization_id": "org_123"
  }'
Initiates a file upload and returns a presigned URL.

​
Request Body

​
name
string
required
File name
​
mime_type
string
required
MIME type
​
size
integer
required
File size in bytes
​
service
enum
required
File type: product_media or downloadable
​
organization_id
string
Organization ID (required unless using org token)

​
Response

​
id
string
File ID
​
upload_url
string
Presigned S3 URL for upload
​
upload_headers
object
Required headers for upload

​
Complete File Upload

cURL
curl -X POST "https://api.polar.sh/v1/files/{id}/uploaded" \
  -H "Authorization: Bearer polar_pat_..." \
  -H "Content-Type: application/json" \
  -d '{}'
Marks the file upload as complete after uploading to S3.

​
Path Parameters

​
id
string
required
File ID

​
Update File

cURL
curl -X PATCH "https://api.polar.sh/v1/files/{id}" \
  -H "Authorization: Bearer polar_pat_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "updated-name.png"
  }'

​
Path Parameters

​
id
string
required
File ID

​
Request Body

​
name
string
Update file name

​
Delete File

cURL
curl -X DELETE "https://api.polar.sh/v1/files/{id}" \
  -H "Authorization: Bearer polar_pat_..."

​
Path Parameters

​
id
string
required
File ID

​
Upload Flow

The complete upload process:
  1. Create file upload - Get presigned URL
  2. Upload to S3 - Use presigned URL
  3. Mark complete - Notify Polar upload finished

​
Example

# 1. Create file upload
RESPONSE=$(curl -X POST "https://api.polar.sh/v1/files" \
  -H "Authorization: Bearer polar_pat_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "hero.png",
    "mime_type": "image/png",
    "size": 524288,
    "service": "product_media",
    "organization_id": "org_123"
  }')

FILE_ID=$(echo $RESPONSE | jq -r '.id')
UPLOAD_URL=$(echo $RESPONSE | jq -r '.upload_url')

# 2. Upload file to S3
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: image/png" \
  --data-binary "@hero.png"

# 3. Mark upload complete
curl -X POST "https://api.polar.sh/v1/files/$FILE_ID/uploaded" \
  -H "Authorization: Bearer polar_pat_..." \
  -H "Content-Type: application/json" \
  -d '{}'

​
Python Example

import requests

client = requests.Session()
client.headers['Authorization'] = 'Bearer polar_pat_...'

# 1. Create upload
response = client.post('https://api.polar.sh/v1/files', json={
    'name': 'hero.png',
    'mime_type': 'image/png',
    'size': 524288,
    'service': 'product_media',
    'organization_id': 'org_123'
})
data = response.json()

# 2. Upload to S3
with open('hero.png', 'rb') as f:
    requests.put(
        data['upload_url'],
        data=f,
        headers={'Content-Type': 'image/png'}
    )

# 3. Mark complete
client.post(f"https://api.polar.sh/v1/files/{data['id']}/uploaded")

Build docs developers (and LLMs) love

Get started for freeTalk to us