List Transactions | One Tribe Docs

GET /v1/transactions

Query Parameters

Parameter	Type	Description	Default
`page`	integer	The page number for pagination	1
`limit`	integer	The number of items per page	10
`sort`	string	Field to sort by (e.g. `-createdAt` for descending order)	-
`filter[project_id]`	string	Filter by specific project ID	-
`filter[transaction_type]`	string	Filter by transaction type (currently only `purchase`)	-
`filter[status]`	string	Filter by transaction status	-

Example Request

Using curl

curl "https://api.onetribe.com/v1/transactions?page=1&limit=10&sort=-createdAt" \
  -H "Authorisation: API-Key YOUR_API_KEY_HERE"

Using TypeScript

interface Transaction {
  transaction_id: string
  project_id: string
  transaction_type: 'purchase'
  quantity: number
  status: 'ordered' | 'accepted' | 'retired' | 'completed' // Read-only, managed by One Tribe
  description?: string
  metadata?: Record<string, unknown>
  createdAt: string
  updatedAt: string
}

interface TransactionListResponse {
  data: Transaction[]
  meta: {
    page: number
    limit: number
    total: number
  }
}

async function listTransactions(params: {
  page?: number
  limit?: number
  sort?: string
  filter?: {
    project_id?: string
    transaction_type?: 'purchase'
    status?: 'ordered' | 'accepted' | 'retired' | 'completed'
  }
}): Promise<TransactionListResponse> {
  const searchParams = new URLSearchParams()

  if (params.page) searchParams.append('page', params.page.toString())
  if (params.limit) searchParams.append('limit', params.limit.toString())
  if (params.sort) searchParams.append('sort', params.sort)

  // Add any filters
  if (params.filter) {
    Object.entries(params.filter).forEach(([key, value]) => {
      if (value) searchParams.append(`filter[${key}]`, value)
    })
  }

  const response = await fetch(
    `https://api.onetribe.com/v1/transactions?${searchParams.toString()}`,
    {
      headers: {
        Authorisation: 'API-Key YOUR_API_KEY_HERE',
      },
    },
  )

  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`)
  }

  return response.json()
}

// Example usage
const transactions = await listTransactions({
  page: 1,
  limit: 10,
  sort: '-createdAt',
  filter: {
    transaction_type: 'purchase',
    status: 'completed',
  },
})

Example Response

{
  "data": [
    {
      "transaction_id": "tx-789xyz",
      "project_id": "abc123",
      "transaction_type": "purchase",
      "quantity": 100,
      "status": "completed",
      "description": "Monthly offset purchase",
      "metadata": {
        "customer_id": "cust_12345",
        "order_reference": "ord_6789",
        "department": "retail"
      },
      "createdAt": "2025-02-24T12:34:56Z",
      "updatedAt": "2025-02-24T12:34:56Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 1
  }
}