# 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](https://www.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](https://www.wren.co/settings/team/api). New to the API? Start with the [5-minute Quickstart](https://www.wren.co/docs/api/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:

- **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](https://www.wren.co/docs/api#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:

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

Response:

```json
{
  "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](https://www.wren.co/docs/wren-api.postman_collection.json) to quickly test all API endpoints. To use it:

1. Import the JSON file into [Postman](https://www.postman.com/)
2. Go to the collection's **Variables** tab and set `api_token` to your token from [Settings > API Token](https://www.wren.co/settings/api)
3. Start sending requests — all example payloads are pre-filled

## Resources

- [Offset Orders](https://www.wren.co/docs/api/offset-orders) — Create and list offset orders
- [Project Orders](https://www.wren.co/docs/api/project-orders) — Fund a specific project
- [Portfolios](https://www.wren.co/docs/api/portfolios) — List portfolios and their projects
- [Purchases](https://www.wren.co/docs/api/purchases) — List purchase summaries with certificate URLs
- [Project Donations](https://www.wren.co/docs/api/project-donations) — List non-offsettable project funding
- [Tree Orders](https://www.wren.co/docs/api/tree-orders) — Create and list tree planting orders
- [Credits](https://www.wren.co/docs/api/credits) — Manage your prepaid credit balance

## Examples

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

- [Web](https://github.com/taylorlapeyre/wren-api-tutorial)
- [Node.js](https://github.com/bstanfield/wren-api-tutorial)