Tree-Nation API – Gifting Trees Integration Guide

Table of Contents

• Purpose
• The Core Idea
• Planting Habit & Planting Actions
• Species Package
• How the Flow Works
• Example of the User Experience
• Tree Message Template
• API Setup & Testing
• Payment Options
• “Your Forest” Section (advanced)
• Why It Matters
• ✅ 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

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 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:

1
{
2
  "recipients": [
3
    {
4
      "name": "test user",
5
      "email": "test878349@test.com"
6
    }
7
  ],
8
  "quantity": 2
9
}

Example response:

1
{
2
  "status": "ok",
3
  "trees": [
4
    {
5
      "id": 161,
6
      "token": "abcd1234",
7
      "collect_url": "https://youcannevertestenough.tree-nation.com/collect/abcd1234",
8
      "certificate_url": "https://youcannevertestenough.tree-nation.com/certificate/abcd1234"
9
    }
10
  ],
11
  "payment_id": 63
12
}

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.