Create Transaction | One Tribe Docs

POST /v1/transactions

Description

Creates a new transaction record for a carbon offset purchase or sale.

Request Body

Field	Type	Required	Description
`project_id`	string	Yes	Unique identifier for the carbon offset project
`transaction_type`	string	Yes	Type of transaction (currently only `purchase`)
`quantity`	integer	Yes	Number of carbon offsets (in tonnes)
`description`	string	No	Additional context or notes about the transaction
`metadata`	object	No	Optional unstructured JSON for custom data

Example Request

Using curl

curl "https://api.onetribe.com/v1/transactions" \
  -X POST \
  -H "Authorisation: API-Key YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "abc123",
    "transaction_type": "purchase",
    "quantity": 100,
    "description": "Monthly offset purchase",
    "metadata": {
      "customer_id": "cust_12345",
      "order_reference": "ord_6789",
      "department": "retail"
    }
  }'

Using TypeScript

interface CreateTransactionRequest {
  project_id: string
  transaction_type: 'purchase'
  quantity: number
  description?: string
  metadata?: Record<string, unknown>
}

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
}

async function createTransaction(
  data: CreateTransactionRequest,
): Promise<Transaction> {
  const response = await fetch('https://api.onetribe.com/v1/transactions', {
    method: 'POST',
    headers: {
      Authorisation: 'API-Key YOUR_API_KEY_HERE',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(data),
  })

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

  return response.json()
}

// Example usage
const transaction = await createTransaction({
  project_id: 'abc123',
  transaction_type: 'purchase',
  quantity: 100,
  description: 'Monthly offset purchase',
  metadata: {
    customer_id: 'cust_12345',
    order_reference: 'ord_6789',
    department: 'retail',
  },
})

Example Response

{
  "transaction_id": "tx-789xyz",
  "project_id": "abc123",
  "transaction_type": "purchase",
  "quantity": 100,
  "status": "ordered",
  "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"
}