Wren API Documentation | Wren

Wren API Documentation

The Wren API is a JSON REST API that lets you offset carbon dioxide through our portfolio of verified carbon sequestration projects. Some endpoints require authorization; others are available for public use.

To obtain an API token, visit wren.co/wren-api and sign up for an API team. Your team gets a shared live API token for production use, a test token (wren_test_…) for sandbox integration, and a credit balance billed in USD. Both tokens are revealed on your team's API & Credits settings page. New to the API? Start with the 5-minute Quickstart.

Base URL

Production

https://www.wren.co

Local

http://localhost:3001

Authentication

Most endpoints require authentication via your API token. You can supply it in either format:

Wren supports three token types:

Write endpoints (creating offset orders, project orders) require an account with a payment method on file or a credit balance. Read endpoints (listing your orders, purchases) require a valid API token.

Endpoints that do not require auth:

Test mode

Authenticate any write endpoint with a wren_test_… token to integrate against Wren risk-free. The full request validation runs (a malformed test request gets the same 400 a malformed live request would), but no Stripe charge fires, no DB write happens, and no email/Slack/Customer.io notifications go out. Responses include "test": true and use prefixed fake IDs (test_oo_…, test_po_…, test_to_…) for traceability in your logs.

Test mode is stateless by design — each request resets to a $1,000.00 canned balance. To simulate real balance changes over time, use your live token against a low-funded team.

Fidelity callouts — test mode mirrors live behavior, including:

Known fidelity gaps (parser-affecting; will be closed in a follow-up):

Quickstart

The most common use of our API is to offset a specific amount of carbon dioxide using a portfolio of projects:

curl https://www.wren.co/api/offset-orders \
  -u [api_token]: \
  -H "Content-Type: application/json" \
  -d '{"tons": 0.45, "portfolioId": 12}'

Response:

{
  "amountCharged": 1040,
  "currency": "USD",
  "tons": 0.45,
  "id": "ch_12345",
  "portfolio": { ... }
}

amountCharged is in the smallest currency unit (e.g. 1040 = $10.40 USD).

Endpoints

Method Path Auth Description
POST /api/offset-orders Required Create offset orders by tons (portfolio allocation)
POST /api/project-orders Required Fund a specific project by dollar amount
GET /api/offset-orders Required List your offset orders
GET /api/offset-orders/public None List public offset orders (cached)
GET /api/portfolios Optional List available portfolios and projects
GET /api/purchases Required List your purchase summaries
GET /api/project-donations Required List your project donations
POST /api/tree-orders Required Create a tree order by number of trees
POST /api/tree-orders/preview Required Preview tree order pricing
GET /api/tree-orders Required List your tree orders
POST /api/credits/top-up Required Add credits to your balance
GET /api/credits/balance Required Get your current credit balance
GET /api/credits/ledger Required List your credit transactions

Error handling

Postman Collection

Download our Postman collection to quickly test all API endpoints. To use it:

  1. Import the JSON file into Postman
  2. Go to the collection's Variables tab and set api_token to your token from Settings > API Token
  3. Start sending requests — all example payloads are pre-filled

Resources

Examples

We provide simple code examples to help you integrate with the Wren API: