> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.tree-nation.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.tree-nation.com/_mcp/server.

# Tree-Nation API – Gifting Trees Integration Guide

> **Info**
>
> Building with an LLM or AI agent? Grab the full machine-readable docs at [llms-full.txt](https://docs.tree-nation.com/llms-full.txt).

## Table of Contents

* [Purpose](#purpose)
* [The Core Idea](#the-core-idea)
* [Planting Habit & Planting Actions](#planting-habit--planting-actions)
* [Species Package](#species-package)
* [How the Flow Works](#how-the-flow-works)
* [Example of the User Experience](#example-of-the-user-experience)
* [Tree Message Template](#tree-message-template)
* [API Setup & Testing](#api-setup--testing)
* [Payment Options](#payment-options)
* ["Your Forest" Section (advanced)](#your-forest-section-for-your-app-or-platform-advanced)
* [Why It Matters](#why-it-matters)
* [✅ Implementation Checklist](#%EF%B8%8F-implementation-checklist)

---

## Purpose

Gifting a tree through Tree-Nation lets you celebrate milestones, reward loyalty, and engage your users meaningfully.

By connecting your system to Tree-Nation's API, you can automatically plant trees in real time and let recipients collect them through a personalized digital experience.

---

## The Core Idea

The Tree-Nation API lets your platform **trigger the creation of a tree** based on specific user actions.

When your system calls the `POST /api/plant` endpoint:

1. A new tree is created in your company forest.
2. The API immediately returns a **unique tree URL**.
3. You can store this link in your database and share it with your user (e.g., in an email or app notification).

This process ensures each tree is uniquely traceable, allowing you to build features like "Your Forest" or automated gifting campaigns directly into your product.

---

## Planting Habit & Planting Actions

### Habit Used

[#Planting Habit – What is the reason to plant trees](#)

**What is a habit?**

A *Planting Habit* represents the "why you plant" — the shared purpose behind your initiative. It's the cultural anchor that gives meaning to your planting actions and connects your users to a global movement.

### Your Planting Actions

1. Plant a tree for
2. Plant a tree for

**What is a Planting Action?**

A *Planting Action* defines the "how" — the specific trigger that determines *when* a tree is planted.

---

## Species Package

When planting trees through Tree-Nation, your species selection method depends on how you use our platform, either through automated integrations or manual planting.

### Chosen Species Packages

* [ ] [Species Package 0.35](#)
* [ ] [Species Package 0.50](#)
* [ ] [Species Package 1.00](#)

|                    | **Diversity**     | **Happy Mix**    | **Best Price**   |
| ------------------ | ----------------- | ---------------- | ---------------- |
| **Price**          | 1.00 € per tree   | 0.50 € per tree  | 0.35 € per tree  |
| **Species**        | Up to 40 species  | Up to 20 species | Up to 10 species |
| **Countries**      | 10 countries      | 5 countries      | 2 countries      |
| **Avg CO2 offset** | 50 Kg             | 50 Kg            | 50 Kg            |
| **Focus Regions**  | Africa, Asia, USA | Africa           | Africa           |

---

## How the Flow Works

**Trigger → Tree is planted and visible in your corporate forest → Tree-gift sent to the recipient → Recipient clicks on tree-gift URL → Tree-gift is collected**

### Step-by-step overview:

1. **Trigger:** A user performs an action on your platform (e.g., purchase, milestone, referral).
2. **Create Tree:** Your system calls the `POST /api/plant` endpoint with the relevant data.
3. **Confirmation:** Tree-Nation creates the tree and returns a unique tree URL.
4. **Store:** You save this URL in your database, linked to the user's ID.
5. **Communicate:** You send the user an email with a personalized message and the tree-gift URL to collect their tree.
6. **Engage:** Optionally, display all the user's trees in a dedicated section of your app or website — *Your Forest*.

This ensures full traceability between your system, every tree planted, and the final user experience.

---

## Example of the User Experience

**Example email:**

> **Subject:** You've received a tree! 🌱
>
> **Message:** Hi Alex, you've been gifted a tree from OurCompany as a thank-you for your recent purchase.
>
> **CTA:** \[Collect your tree] → links to the collect page on Tree-Nation

**Delivery options:** Tree-Nation can also send this email directly to recipients on your behalf. If you prefer this option, please let us know, as the configuration process will differ slightly.

**Best practice:** For higher engagement, we recommend sending the *tree gift* email separately from your transactional or confirmation emails (such as purchase receipts). Because this message is emotional and unexpected, our data shows that sponsors who separate it achieve significantly better open and click-through rates.

Learn more about the [tree-gift experience](https://tree-nation.com) on Tree-Nation.

---

## Tree Message Template

Each gifted tree includes one image and one message displayed on the Tree-Nation collection page.

### [Planting Action](#)

**Recommended image**

*(To be defined)*

**Recommended message**

*Congratulations on XX. The start of a journey where every XX helps the planet grow greener.*

**Habit** #PlantingHabit

---

Please confirm if this message is suitable for your brand, or modify it as you wish. The image and message are stored directly in Tree-Nation's system — **you don't need to manage or update them through the API.**

---

## API Setup & Testing

This section explains how to connect and test your API integration before going live.

### Your test token

> **To be provided** once you fill in this form: [API Test Token Request](#)

### Your live token

> **To be provided**

---

Open our [API Documentation](#). In this example, we will be running it on Postman.

### Step 1: Test Environment

1. Open our API documentation (example: Postman collection).
2. In the *User API* folder, click on **POST /plant**.
3. Go to the **Authorization** tab, select *Bearer Token*, and enter your **test token**.
4. In the **Body** tab, you'll find an example payload to send with the `POST https://youcannevertestenough.tree-nation.com/api/plant` request.
5. Set the `internal_id` of the recipient if you want Tree-Nation to send the tree-gift email for you.
   * This `internal_id` allows to track and group multiple trees under one recipient, ensuring better traceability between systems.
6. Set the `quantity` (number of trees to gift).
7. Remove all other fields — your message, image, and species are already preconfigured in the tree template.
8. Execute the POST request.

You'll receive two links, the collect link and the tree certificate link, in the response. Use the **collect_url link**.

* **collect_url** — the recipient's tree link

**Example request body:**

```json
{
  "recipients": [
    {
      "name": "test user",
      "email": "test878349@test.com"
    }
  ],
  "quantity": 2
}
```

**Example response:**

```json
{
  "status": "ok",
  "trees": [
    {
      "id": 161,
      "token": "abcd1234",
      "collect_url": "https://youcannevertestenough.tree-nation.com/collect/abcd1234",
      "certificate_url": "https://youcannevertestenough.tree-nation.com/certificate/abcd1234"
    }
  ],
  "payment_id": 63
}
```

### Step 2: Live Environment

Once tested successfully, repeat the process using the live endpoint:

```
POST https://tree-nation.com/api/plant
```

---

### What to Save in Your Database

Create a dedicated table to store each tree's data, including: Tree URL, Tree quantity, Creation date, and Associated user ID.

This will allow you to:

* Provide a dedicated section for the trees, such as a *"Your Forest"* or *"Your Trees"* section later
* Assist users who haven't received their tree links
* Group and count trees per user

---

## Payment Options

Tree-Nation offers two simple payment methods to manage your planting credits:

### 1. Pay with Credit Card

1. [Credit your account](#) with the value you expect to spend in one month.
2. The system automatically recharges your credits when your balance reaches 10% of your last recharge.
3. Over time, the recharge value adapts so you typically receive one invoice per month.

This option ensures seamless planting and no service interruptions.

### 2. Pay via Bank Transfer

1. Tree-Nation opens a credit line for your company.
2. You receive one invoice at the end of each month for the total value of trees planted during that period.

This is ideal for companies preferring centralized monthly accounting.

---

## "Your Forest" Section for Your App or Platform (advanced)

We recommend creating a small space in your website or app menu — for example, *Your Forest* — where users can:

1. See how many trees they've received with a counter per user.
2. Access links to all their tree pages.
3. Celebrate their collective impact alongside your brand.

This turns one-off gifts into a long-term engagement feature that grows over time.

To avoid delaying your launch, we recommend implementing this in a **second phase** of the project.

---

## Why It Matters

1. **Traceability:** Every tree has a unique link that connects the gift to a real planting action.
2. **Engagement:** Recipients interact with your sustainability initiative, not just passively receive it.
3. **Scalability:** Once the API is set up, you can automate planting for any campaign or user flow.
4. **Transparency:** The "Your forest" page demonstrates ongoing impact in a measurable way.

---

## ✅ Implementation Checklist

Follow this checklist to make sure your integration is complete and ready to launch:

### Setup

* [ ] Create a [company test account](#) in our test environment
* [ ] Create your [company forest](#) on Tree-Nation
* [ ] Add your [billing information](#)
* [ ] Add a [payment method](#) (if paying by credit card)

### Integration & Testing

* [ ] Install the **API connection** in the test environment
* [ ] Verify that the API correctly creates a tree when your trigger event occurs. Ensure your logic filters out false positives (for example, failed payments, canceled orders, or test transactions).
* [ ] Once confirmed, request your **live API token**
* [ ] Install the **API connection** in the live environment
* [ ] Store all **tree collection URLs** in a table linked to your user database

### Communication & Launch

* [ ] Create a **"Collect your tree" email template** with your branding
* [ ] Go live — enable tree gifting for your users.