# Tree Orders

A **Tree Order** funds tree-planting projects by number of trees rather than dollar amount or tons of CO2. Tree orders are currently fulfilled through the WeForest provider.

## POST /api/tree-orders — Create a tree order

Creates a tree order, charging via Stripe or credits.

POST`/api/tree-orders`Copy Path

### Authentication

Required. Use a **team API token** (recommended) or legacy personal API token via Basic auth or Bearer token. Account required for personal tokens. **Test tokens** (`wren_test_…`) return canned responses without side effects — see [Test mode](https://www.wren.co/docs/api#test-mode).

### Headers

- `Content-Type: application/json` or `application/x-www-form-urlencoded`

### Request body

| Attribute           | Type     | Description & Constraints                                                                             |
|---------------------|----------|------------------------------------------------------------------------------------------------------|
| `amountOfTrees`     | integer  | **Required.** Number of trees to plant. Must be a positive integer.                                 |
| `paymentMethod`     | string   | Optional. `"stripe"` (default) or `"credits"`. When `"credits"`, deducts from your credit balance instead of charging Stripe. |
| `note`              | string   | Optional. Note for the order.                                                                         |
| `dryRun`           | boolean  | Optional. If true, no charge; returns preview only.                                                 |
| `onBehalfOfName`    | string  | Optional. Name of the end-customer this order is being placed for. Shown as the purchaser on the impact certificate. Max 200 characters. |
| `onBehalfOfEmail`   | string  | Optional. Email of the end-customer this order is being placed for. Stored alongside the order; not used for sending email. Max 320 characters. |

### Example request

### Success response

HTTP `200`

- `amountCharged` — In the user currency's smallest denomination (e.g. 5000 = $50.00 USD)
- `currency` — The user's currency code. For credits, always `"USD"`
- `id` — Order group ID (Stripe charge ID for Stripe payments, UUID for credits, `null` for dry runs)
- `impact.trees` — Number of trees in the order

When `paymentMethod` is `"credits"`, the response also includes:

- `paymentMethod` — `"credits"`
- `creditsRemaining` — Remaining credit balance in USD cents after the order

### Error responses

- **400** — Invalid payload, missing `amountOfTrees`, or invalid `paymentMethod`
- **403** — Missing/invalid auth or not an account user

* * *

## POST /api/tree-orders/preview — Preview tree order pricing

Returns pricing information for a tree order without placing it.

POST`/api/tree-orders/preview`Copy Path

### Authentication

Required. Use a team API token or legacy personal API token. Test tokens return a canned preview without DB lookups.

### Headers

- `Content-Type: application/json` or `application/x-www-form-urlencoded`

### Request body

| Attribute           | Type     | Description & Constraints                                                                             |
|---------------------|----------|------------------------------------------------------------------------------------------------------|
| `amountOfTrees`     | integer  | **Required.** Number of trees to price. Must be a positive integer.                                 |

### Example request

### Success response

HTTP `200`

- `amountOfTrees` — Number of trees requested
- `priceInUSD` — Total cost in USD
- `priceInUserCurrency` — Total cost converted to the user's local currency

### Error responses

- **400** — Missing or invalid `amountOfTrees`
- **403** — Missing or invalid authentication

* * *

## GET /api/tree-orders — List your tree orders

Returns the authenticated user's tree orders.

GET`/api/tree-orders`Copy Path

### Authentication

Required. Use a team API token or legacy personal API token. Test tokens return a canned sample list.

### Request

No body. No query parameters.

### Example request

### Success response

HTTP `200`

### Error responses

- **403** — Missing or invalid authentication