Offset Orders

An Offset Order represents an order placed on Wren to remove a certain amount of carbon dioxide (or CO₂ equivalents) from the atmosphere using projects in a Portfolio. When you create an offset order, our system records the amount of CO₂ removed and pays the respective project partners for carbon credits at the end of each month.

POST /api/offset-orders — Create offset orders

Creates offset orders by allocating a given number of tons across the projects in a portfolio. Funds are distributed according to the portfolio's allocation percentages.

Authentication

Required. Use a team API token (recommended) or legacy personal API token via Basic auth or Bearer token. Account (password, Google, or Shopify) required for personal tokens. Test tokens (wren_test_…) return canned responses without DB writes, Stripe charges, or notifications — full validation still runs. See Test mode.

Headers

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

Request body

Attribute	Type	Description & Constraints
tons	number	Required. Amount of CO₂e to offset in tonnes.
portfolioId	number	Optional. Portfolio ID for allocation. Default: Wren Climate Fund.
note	string	Optional. Note attached to each order.
dryRun	boolean	Optional. If true, no charge is made; returns preview only.
sendReceiptEmail	boolean	Optional. If true, sends a receipt email when dryRun is false.
paymentMethod	string	Optional. "stripe" (default) or "credits". When "credits", deducts from your credit balance instead of charging Stripe. No $1 minimum when using credits.
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.

Minimum amount

• tons must be positive.
• When paymentMethod is "stripe" (default): total charge must be at least 100 USD cents ($1). Minimum tons depends on portfolio cost_per_ton.
• When paymentMethod is "credits": no minimum charge — any positive tons value is accepted, as long as you have sufficient credit balance.

Example request

Success response

HTTP 200

• id — Stripe charge ID, or null when dryRun=true
• amountCharged — In the user currency's smallest denomination (e.g. 5000 = $50.00)

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 tons, charge below minimum, or insufficient credit balance
• 403 — Missing/invalid auth or not an account user

---

GET /api/offset-orders — List your offset orders

Returns the authenticated user's offset orders with aggregate stats.

Authentication

Required. Use a team API token or legacy personal API token via Basic auth or Bearer token. Test tokens return a small canned sample list.

Request

No body. No query parameters.

Success response

HTTP 200

• stats.totalTons — Sum of certified and external-standard offset tons
• stats.rank / stats.percentile — User's global ranking (omitted when totalTons is 0)
• offsetOrders — Certified offset orders (snake_case fields)
• uncertifiedOffsetOrders — Offsets not meeting certified standards
• amount_paid_by_customer — USD cents. Typically integer-valued, but sub-cent fractional values can appear on rows from credit-funded sub-dollar orders, where a small charge is split across multiple projects.

Error responses

• 403 — Missing or invalid authentication

---

GET /api/offset-orders/public — List public offset orders

Returns a curated list of public offset orders for display (e.g. leaderboards, feeds). No authentication required. Data is cached and refreshed hourly.

Authentication

None required.

Request

No body. No query parameters.

Success response

HTTP 200

• Up to 30 orders, sorted by most recent
• Each row aggregates one user's charge per portfolio