Get Transaction

GET /v1/transactions/{transaction_id}

Path Parameters

Example Request

Using curl

curl "https://api.onetribe.com/v1/transactions/tx-789xyz" \
  -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
}

class TransactionError extends Error {
  constructor(
    message: string,
    public status: number,
    public code: string,
  ) {
    super(message)
    this.name = 'TransactionError'
  }
}

async function getTransaction(transactionId: string): Promise<Transaction> {
  const response = await fetch(
    `https://api.onetribe.com/v1/transactions/${transactionId}`,
    {
      headers: {
        Authorisation: 'API-Key YOUR_API_KEY_HERE',
      },
    },
  )

  if (!response.ok) {
    switch (response.status) {
      case 404:
        throw new TransactionError('Transaction not found', 404, 'NotFound')
      case 401:
        throw new TransactionError('Invalid API key', 401, 'Unauthorized')
      case 403:
        throw new TransactionError('Insufficient permissions', 403, 'Forbidden')
      default:
        throw new TransactionError(
          'An error occurred while fetching the transaction',
          response.status,
          'ServerError',
        )
    }
  }

  return response.json()
}

// Example usage
try {
  const transaction = await getTransaction('tx-789xyz')
  console.log('Transaction details:', transaction)
} catch (error) {
  if (error instanceof TransactionError) {
    console.error(`${error.code} (${error.status}): ${error.message}`)
  } else {
    console.error('Unexpected error:', error)
  }
}

Example Response

{
  "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"
}