Plant trees from your checkout.

Overview#

Treez gives your customers points for their purchases. Every 100 points plants a real, GPS-verified native tree. There are two ways to send us orders — pick whichever fits your store:

Base URL: https://api.treezplus.com/v1. JSON in and out, camelCase fields, ISO-8601 UTC timestamps. Lists use ?limit=&cursor= and return { items, nextCursor }.

Authentication#

Create API keys in the store portal under Developers → API keys. Send the key as a bearer token from your server:

Authorization: Bearer sk_live_4f8a…

Order API#

Send an order when it's paid (or completed — your choice in Settings → Earning rules). Sending the same externalOrderId again updates the order instead of creating a duplicate.

curl -X POST https://api.treezplus.com/v1/orders \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: order-1001" \
  -H "Content-Type: application/json" \
  -d '{
    "externalOrderId": "1001",
    "amount": 12.5,
    "currency": "OMR",
    "status": "paid",
    "customer": { "email": "salim@example.com", "name": "Salim", "phone": "+96890000001" },
    "occurredAt": "2026-10-24T09:30:00Z"
  }'

Request fields

Response

{
  "id": "6f1c2a7e-0b7d-4c55-9a43-3f0d2a9b1e10",
  "source": "api",
  "externalOrderId": "1001",
  "livemode": true,
  "amount": 12.5,
  "currency": "OMR",
  "status": "paid",
  "customer": {
    "email": "salim@example.com",
    "phone": "+96890000001",
    "name": "Salim",
    "trees": { "matched": true, "firstName": "Salim" }
  },
  "points": 125,
  "pointsStatus": "pending",
  "skipReason": null,
  "confirmAt": "2026-11-07T09:30:00.000Z",
  "confirmedAt": null,
  "reversedAt": null,
  "createdAt": "2026-10-24T09:30:00.000Z",
  "updatedAt": "2026-10-24T09:30:00.000Z"
}

Points = floor(amount × pointsPerUnit) for the order's currency, capped by your per-order maximum. No rule for the currency or below your minimum → points: 0 with skipReason.

Lifecycle

1. pending

   Points reserved from your budget; confirmAt = order time + hold days.

2. confirmed

   Hold period over and the customer is on Treez → points credited.

3. reversed

   Cancelled or refunded before confirmation → budget released.

Customer not on Treez yet? Points wait for up to 90 days and attach automatically when they sign in to the Treez app with that email.

Update the status

curl -X POST https://api.treezplus.com/v1/orders/1001/status \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "status": "refunded" }'

Statuses: completed, cancelled, refunded. A refund after confirmation is recorded, but points are not taken back.

List & fetch

curl "https://api.treezplus.com/v1/orders?pointsStatus=pending&limit=20" \
  -H "Authorization: Bearer sk_live_…"

Customer matching#

Points go to the Treez account whose email matches the order's customer.email. Customers and planters sign in to the Treez app with a one-time code sent to their email, so the email is the identity we trust. Always send customer.email.

Not on Treez yet

If no account has that email, the response shows trees.matched: false and the points wait as unclaimed for up to 90 days. They attach the moment someone signs in to the Treez app with that email (and confirm right away if the hold period is over). Otherwise they expire as unclaimed_expired and go back to your budget. Test-mode orders are never matched to real customers.

Skip reasons

Idempotency#

Networks fail. Send an Idempotency-Key header (for example order-1001) and retry safely: the same key returns the original response with Idempotent-Replayed: true, and never creates points twice. Reusing a key with a different body returns 409 IDEMPOTENCY_KEY_REUSED.

Even without the header, orders are upserted by (store, source, externalOrderId).

Errors#

Errors use the HTTP status and a stable code:

{
  "error": {
    "code": "MERCHANT_NOT_ACTIVE",
    "message": "Your store is not approved yet",
    "details": {}
  }
}

Webhooks#

Add an endpoint in Developers → Webhooks and Treez will POST JSON events to it — from orders to a tree going into the ground. Every event uses the same envelope:

{
  "id": "evt_01JB2Q8M4K7Y3ZP6",
  "type": "tree.planted",
  "createdAt": "2026-10-24T09:30:00.000Z",
  "livemode": true,
  "merchantId": "b2c1…",
  "data": {
    "tree": { "id": "…", "status": "planted", "species": { "nameEn": "Ghaf" }, "…": "…" },
    "passportUrl": "https://treez.om/t/ghaf-7k4p",
    "fundingShare": 0.35
  }
}

Delivery & retries

• Answer with any 2xx within 10 seconds. Do slow work in a background job.
• Failed deliveries are retried after 1m · 5m · 30m · 2h · 6h · 12h · 24h (7 attempts).
• An endpoint that fails every delivery for 3 days is disabled automatically. Re-enable it from the portal.
• Events can arrive more than once or out of order — de-duplicate on id.

Event types

order.* events carry { order }; tree.* events carry { tree, passportUrl, fundingShare } and only go to stores that funded that tree.

Verify signatures#

Every request carries a signature header:

Treez-Signature: t=1761298200,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

1. Split the header on ,; read t (unix seconds) and every v1.
2. Compute HMAC-SHA256(secret, t + "." + rawBody) as hex.
3. Accept if it equals any v1 (constant-time compare) and t is less than 5 minutes old.

import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.TREEZ_WEBHOOK_SECRET; // "whsec_…"

// Keep the raw body: the signature covers the exact bytes we sent.
app.post("/treez/webhooks", express.raw({ type: "application/json" }), (req, res) => {
  const header = req.get("Treez-Signature") ?? "";
  const parts = header.split(",").map((p) => p.trim().split("="));
  const t = parts.find(([k]) => k === "t")?.[1];
  const signatures = parts.filter(([k]) => k === "v1").map(([, v]) => v);

  // Reject old timestamps (replay protection).
  if (!t || Math.abs(Date.now() / 1000 - Number(t)) > 300) return res.status(400).send("stale");

  const expected = crypto.createHmac("sha256", SECRET).update(`${t}.`).update(req.body).digest("hex");
  const valid = signatures.some(
    (s) => s.length === expected.length && crypto.timingSafeEqual(Buffer.from(s), Buffer.from(expected)),
  );
  if (!valid) return res.status(400).send("bad signature");

  const event = JSON.parse(req.body.toString("utf8"));
  switch (event.type) {
    case "order.points_confirmed":
      // event.data.order.points were credited to the customer
      break;
    case "tree.planted":
      // event.data.passportUrl — share it with your customer!
      break;
  }
  res.sendStatus(200); // answer fast; do slow work in a queue
});

Platforms#

Each platform is an adapter that turns its install flow and webhooks into the same normalised order — so points, hold periods, refunds and your webhooks work exactly the same everywhere.

Platform tokens are stored encrypted. Uninstalling the app on the platform disconnects it in Treez. Want another platform? Adding one is a single adapter on our side — tell us at hello@treez.om.

Test mode#

• Use a sk_test_ key: orders are stored with livemode: false, appear in the portal with a TEST badge and fire webhooks — no budget or wallets change.
• Press Send test ping on an endpoint to receive a signed ping event and see the response in the delivery log.
• Test keys can't create claim codes or awards (TEST_MODE_UNSUPPORTED).
• Locally, tunnel your endpoint (e.g. with ngrok) — production endpoints must use HTTPS.