Wren Tree Orders API

openapi: 3.1.0
info:
  title: Wren Credits Tree Orders API
  description: The Wren API is a JSON REST API that lets you offset carbon dioxide through Wren's portfolio of verified carbon sequestration projects. Create offset orders by tonnage, fund specific projects by dollar amount, plant trees, manage a prepaid credit balance, and list portfolios, purchases, and donations. Most endpoints require an API token (team live token, wren_test_ sandbox token, or legacy personal token) via HTTP Basic or Bearer auth.
  version: '2026-07-21'
  contact:
    name: Wren Support
    email: support@wren.co
    url: https://www.wren.co/faq
  termsOfService: https://www.wren.co/terms-of-use
servers:
- url: https://www.wren.co
  description: Production
security:
- basicAuth: []
- bearerAuth: []
tags:
- name: Tree Orders
  description: Create and list tree-planting orders
paths:
  /api/tree-orders:
    post:
      operationId: createTreeOrder
      tags:
      - Tree Orders
      summary: Create a tree order
      description: Creates a tree order by number of trees, charging via Stripe or credits. Tree orders are currently fulfilled through the WeForest provider.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TreeOrderRequest'
            examples:
              basic:
                value:
                  amountOfTrees: 10
                  note: Tree planting order
              credits:
                value:
                  amountOfTrees: 10
                  paymentMethod: credits
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TreeOrderRequest'
      responses:
        '200':
          description: Tree order created (or previewed when dryRun is true)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TreeOrderResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
    get:
      operationId: listTreeOrders
      tags:
      - Tree Orders
      summary: List your tree orders
      responses:
        '200':
          description: The user's tree orders
          content:
            application/json:
              schema:
                type: object
                properties:
                  treeOrders:
                    type: array
                    items:
                      $ref: '#/components/schemas/TreeOrder'
        '403':
          $ref: '#/components/responses/Forbidden'
  /api/tree-orders/preview:
    post:
      operationId: previewTreeOrder
      tags:
      - Tree Orders
      summary: Preview tree order pricing
      description: Returns pricing information for a tree order without placing it.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - amountOfTrees
              properties:
                amountOfTrees:
                  type: integer
                  minimum: 1
                  description: Number of trees to price.
            examples:
              basic:
                value:
                  amountOfTrees: 10
      responses:
        '200':
          description: Tree order pricing preview
          content:
            application/json:
              schema:
                type: object
                properties:
                  amountOfTrees:
                    type: integer
                  priceInUSD:
                    type: number
                  priceInUserCurrency:
                    type: number
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  schemas:
    TreeOrderResponse:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
          description: Order group ID (Stripe charge ID for Stripe payments, UUID for credits, null for dry runs).
        amountCharged:
          type: number
        currency:
          type: string
          description: The user's currency code. For credits, always USD.
        impact:
          type: object
          properties:
            trees:
              type: integer
        paymentMethod:
          type: string
        creditsRemaining:
          type: integer
        test:
          type: boolean
    TreeOrderRequest:
      type: object
      required:
      - amountOfTrees
      properties:
        amountOfTrees:
          type: integer
          minimum: 1
          description: Number of trees to plant.
        paymentMethod:
          type: string
          enum:
          - stripe
          - credits
          default: stripe
        note:
          type: string
        dryRun:
          type: boolean
        onBehalfOfName:
          type: string
          maxLength: 200
        onBehalfOfEmail:
          type: string
          maxLength: 320
    TreeOrder:
      type: object
      properties:
        id:
          type: string
        amountOfTrees:
          type: integer
        createdAt:
          type: string
          format: date-time
    Error:
      type: object
      properties:
        message:
          type: string
          description: Human-readable description of the validation or auth failure.
  responses:
    Forbidden:
      description: Missing or invalid authentication, or account not eligible for the operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Invalid payload, missing required fields, or validation failure.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: 'Recommended for curl: pass the API token as the username with an empty password (-u [api_token]:). Token types: team live token (UUID), team test token (wren_test_ prefix, sandbox), legacy personal token (UUID).'
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Authorization: Bearer [api_token] with the same token types as Basic auth.'
externalDocs:
  description: Wren API Documentation
  url: https://www.wren.co/docs/api
x-provenance:
  generated: '2026-07-21'
  method: derived
  source:
  - https://www.wren.co/docs/api
  - https://www.wren.co/docs/api/wren-api.postman_collection.json
  - https://www.wren.co/docs/api/offset-orders
  - https://www.wren.co/docs/api/project-orders
  - https://www.wren.co/docs/api/tree-orders
  - https://www.wren.co/docs/api/portfolios
  - https://www.wren.co/docs/api/purchases
  - https://www.wren.co/docs/api/project-donations
  - https://www.wren.co/docs/api/credits
  note: Wren publishes complete REST reference documentation and a Postman collection but no OpenAPI document. This spec was derived faithfully from the published docs and collection by the API Evangelist enrichment pipeline; it is not an official Wren artifact.