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.

Base URL

Authentication

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

• Basic auth (recommended for curl): -u [api_token]:
• Bearer token: Authorization: Bearer [api_token]

Wren supports three token types:

• Team live tokens (UUID format) — production traffic, billed against the team's credit balance.
• Team test tokens (wren_test_… format) — sandbox traffic. Returns realistic canned responses without real charges, real offsets, or notifications. Test-mode balance is fixed at $1,000.00 between requests. See Test Mode below.
• Personal user tokens (UUID format, legacy) — pre-existing per-user integrations. Continue to work indefinitely; new integrations should use team tokens.

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:

• GET /api/portfolios — List available portfolios
• GET /api/offset-orders/public — List public offset orders (for leaderboards, feeds)

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:

• amountCharged rounding uses Math.ceil (a fractional cent always rounds up — customers can't be undercharged).
• Stripe minimum charge of $0.50 is enforced. A paymentMethod: "stripe" request whose total cost falls below 50 cents returns the same 400 it would in live, with the same hint to send "paymentMethod": "credits" instead.
• Response shape diverges by paymentMethod to match live: credits responses include paymentMethod and creditsRemaining; stripe responses for offset and project orders omit both.

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

• Currency is always USD in test responses, regardless of the team owner's configured currency. Live responses reflect the user's currency and translate amountCharged to its lowest denomination. If you operate in a non-USD currency, parse currency defensively rather than hardcoding the USD assumption when you flip to live.

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

• 400 Bad Request — Invalid payload, missing required fields, or validation failure. Response body includes a message field.
• 403 Forbidden — Missing or invalid authentication, or account not eligible for the operation.

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

• Offset Orders — Create and list offset orders
• Project Orders — Fund a specific project
• Portfolios — List portfolios and their projects
• Purchases — List purchase summaries with certificate URLs
• Project Donations — List non-offsettable project funding
• Tree Orders — Create and list tree planting orders
• Credits — Manage your prepaid credit balance

Examples

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

• Web
• Node.js