Plant trees | Tree-Nation API Documentation

Plants trees on behalf of the authenticated API user.

Selection logic:

If planter_id is given, the template for that planter is used; falls back to the catch-all template (planter_id = 0) if no specific one exists.
If recipients is given, quantity trees are planted per recipient.
If species_id is given, it overrides the template’s default species.

Idempotency: supply order_id to prevent duplicate processing.

Plants trees on behalf of the authenticated API user. **Selection logic**: - If `planter_id` is given, the template for that planter is used; falls back to the catch-all template (`planter_id = 0`) if no specific one exists. - If `recipients` is given, `quantity` trees are planted per recipient. - If `species_id` is given, it overrides the template's default species. **Idempotency**: supply `order_id` to prevent duplicate processing.

Authentication

AuthorizationBearer

Bearer token required for all User API endpoints. Routes are additionally guarded by an active middleware (account must be active).

Request

This endpoint expects an object.

recipientslist of objectsOptional

List of people to plant trees for. If omitted, the API user is the sole recipient.

planter_idintegerOptional

Target planter user ID. Defaults to the API user’s configured planter. Falls back to the catch-all template (planter_id = 0) if no specific template exists.

species_idintegerOptional

Override the species. Must be complete and belong to an affiliated project. If omitted, uses the tree template's default species.

quantityinteger or nullOptional>=1

Trees to plant per recipient. Defaults to the tree template’s package_quantity.

order_idstringOptional

Idempotency key. If an order with this order_id was already processed for the same API user, the request is rejected with already_processed.

languageenumOptional

Locale for certificate/notification emails.

messagestringOptional

Custom message to include in the planting certificate.

hashtagstringOptional

Hashtag to associate with all trees in this order.

Response

Planting result. Check status field — HTTP 200 is returned even for business-logic errors.

statusenum

payment_idinteger

ID of the created payment record (present on success).

errorCodeenum or null

errorMessagestring or null

Errors

401

Unauthorized Error

403

Forbidden Error

$	curl -X POST https://tree-nation.com/api/plant \
>	-H "Authorization: Bearer <token>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"recipients": [
>	{
>	"name": "test user",
>	"email": "test875349@test.com"
>	},
>	{
>	"name": "test user2",
>	"email": "test458954@test.com"
>	}
>	],
>	"planter_id": 1,
>	"species_id": 1,
>	"quantity": 2,
>	"message": "Thank you for your purchase!"
>	}'

1	{
2	"status": "ok",
3	"payment_id": 1,
4	"errorCode": "already_processed",
5	"errorMessage": "string"
6	}