API Reference

Apps do not call raw Commercit HTTP endpoints directly. They use the SDK.

import { api, cache, docs, http, kv, objects, secrets } from '@commercit/app-sdk'

This page documents the current app-facing API surface exposed through the SDK.

Core Platform API

Products

const products = await api.products.list({
  limit: 20,
  offset: 0,
  status: 'active',
})

const product = await api.products.get('prod_123')

Current methods:

api.products.list(params?: {
  limit?: number
  offset?: number
  status?: string
})

api.products.get(id: string)

Orders

const orders = await api.orders.list({
  limit: 20,
  offset: 0,
  status: 'fulfilled',
  since: '2026-03-01T00:00:00Z',
})

const order = await api.orders.get('ord_123')

Current methods:

api.orders.list(params?: {
  limit?: number
  offset?: number
  status?: string
  since?: string
})

api.orders.get(id: string)

Shop

const shop = await api.shop.info()

Current method:

api.shop.info()

Managed Storage APIs

KV

await kv.set('last-sync-at', new Date().toISOString(), 300)
const lastSyncAt = await kv.get<string>('last-sync-at')
const keys = await kv.list('reviews:', 50)
await kv.delete('last-sync-at')

Current methods:

kv.get<T = unknown>(key: string): Promise<T | null>
kv.set(key: string, value: unknown, ttl?: number): Promise<void>
kv.delete(key: string): Promise<void>
kv.list(prefix?: string, limit?: number): Promise<string[]>

Documents

const created = await docs.create('reviews', {
  product_id: 'prod_123',
  rating: 5,
})

const found = await docs.get('reviews', created.id)

const items = await docs.query('reviews', {
  filter: { product_id: 'prod_123' },
  sort: { created_at: 'desc' },
  limit: 20,
})

const updated = await docs.update('reviews', created.id, { featured: true })
await docs.delete('reviews', created.id)
const count = await docs.count('reviews', { product_id: 'prod_123' })

Current methods:

docs.create(namespace: string, data: Record<string, unknown>)
docs.get(namespace: string, id: string)
docs.query(
  namespace: string,
  opts?: {
    filter?: Record<string, unknown>
    sort?: Record<string, string>
    limit?: number
  }
)
docs.update(namespace: string, id: string, patch: Record<string, unknown>)
docs.delete(namespace: string, id: string): Promise<void>
docs.count(namespace: string, filter?: Record<string, unknown>): Promise<number>

Objects

const uploadUrl = await objects.getUploadUrl('ugc/review-123.jpg', 'image/jpeg')
const downloadUrl = await objects.getDownloadUrl('ugc/review-123.jpg')
const list = await objects.list('ugc/', 50)
await objects.delete('ugc/review-123.jpg')

Current methods:

objects.getUploadUrl(key: string, contentType: string): Promise<string>
objects.getDownloadUrl(key: string): Promise<string>
objects.delete(key: string): Promise<void>
objects.list(prefix?: string, limit?: number): Promise<Array<{
  key: string
  content_type: string
  size_bytes: number
}>>

Cache API

Use cache invalidation after an action, event handler, or job changes data that backs a registered data source.

await cache.invalidate('reviews-list')

Current method:

cache.invalidate(dataSourceSlug: string): Promise<void>

Secrets API

Secrets must be declared in commercit.json.

const apiKey = await secrets.get('REVIEWS_API_KEY')

Current method:

secrets.get(key: string): Promise<string | null>

HTTP Helper

Use http for outbound calls to declared domains.

import { http } from '@commercit/app-sdk'

const response = await http.post('https://api.reviews.example/v1/reviews', {
  json: { product_id: 'prod_123' },
  timeout: 5000,
})

Current methods:

http.get(url, opts?)
http.post(url, opts?)
http.put(url, opts?)
http.delete(url, opts?)

Each returns:

{
  status: number
  data: unknown
  ok: boolean
}

Access Model

This API surface is intentionally constrained:

• no direct core database access
• no raw theme file access
• no other apps’ storage
• no arbitrary checkout UI execution

To expose your own app functionality to the customizer and AI, do not invent extra APIs first. Prefer:

• section for ready-made UI
• data_source for read-oriented composable data
• action for write-oriented composable mutations

See Customizer + AI Compatibility.