Partner API

Get Order

GET /orders/{order}

Orders are made by organizations to fund tree planting or other biodiversity work, all tracked as "units". When the number of orderedUnits has been met with the same number of allocatedUnits, the order will be considered fulfilled. You may find an order has units allocated, and its up to the end user if they want to take these units now, or wait until the order is fulfilled. Use the ID to ensure you are getting unique units.

Path parameters

  • order string(uuid) Required

Responses

  • 200 application/json

    OK

    Hide response attributes Show response attributes object
    • id string(uuid) Required
    • brand string(slug)

      Format should match the following pattern: [a-z\-]+.

    • type string

      Values are manual or automatic.

    • source string

      Values are corporate, event, or onlineStore.

    • status string

      Values are incomplete, fulfilled, or complete.

    • receivedOn string(date-time)
    • fulfilledOn string(date-time) | null
    • organization object

      Additional properties are allowed.

      Hide organization attributes Show organization attributes object
      • id string(uuid)
      • name string
    • plantedByName string
    • plantedForName string
    • personalisedCertificateMessage string
    • personalisedEmailMessage string
    • unitType string Required

      Values are tree, biodiversity, or hedgerow.

    • orderedUnits integer Required

      Minimum value is 1.

    • allocatedUnits array[object] Required
      Hide allocatedUnits attributes Show allocatedUnits attributes object
      • id string Required
      • unitType string Required

        Values are tree, biodiversity, or hedgerow.

      • location object Required

        Additional properties are allowed.

        Hide location attributes Show location attributes object
        • latitude number(double) Required
        • longitude number(double) Required
        • name string Required
        • what3words string Required
      • photos object | null Required

        Additional properties are allowed.

        Hide photos attribute Show photos attribute object | null
        • large object

          Additional properties are allowed.

          Hide large attributes Show large attributes object
          • height integer(int64)
          • width integer(int64)
          • url string(url) Required
      • species string
      • plantedOn string(date-time)
  • 404 application/problem+json

    Organization not found.

    Hide response attributes Show response attributes object
    • type string Required
    • title string Required
    • status integer
    • detail string
    • instance string
GET /orders/{order} 
curl \
 --request GET 'https://api.protect.earth/orders/53f7bd7b-2ee2-4be4-a15b-e09c76a150f9'
Response examples (200) 
{
  "id": "string",
  "brand": "string",
  "type": "manual",
  "source": "corporate",
  "status": "incomplete",
  "receivedOn": "2025-05-04T09:42:00Z",
  "fulfilledOn": "2025-05-04T09:42:00Z",
  "organization": {
    "id": "string",
    "name": "string",
    "logo": "string"
  },
  "plantedByName": "string",
  "plantedForName": "string",
  "personalisedCertificateMessage": "string",
  "personalisedEmailMessage": "string",
  "unitType": "tree",
  "orderedUnits": 600,
  "allocatedUnits": [
    {
      "id": "o2j",
      "unitType": "tree",
      "location": {
        "latitude": 51.87351,
        "longitude": -1.90973,
        "name": "Hawling, England",
        "what3words": "headlight.hunches.heads"
      },
      "photos": {
        "large": {
          "height": 3000,
          "width": 3000,
          "url": "https://aws-bucket-name.s3.eu-west-2.amazonaws.com/trees/eyJpdiI6IkJ6S1hJcE40UGRUbFk4UXd6WVdkYWc9PSIsInZhbHVlIjoiUlk2Q05TalQ3WnpnTnNDbWhzbURIQT09IiwibWFjIjoiYmY1NmNhMDMzMDU2NTk3OTEwMzNiMzUxZjA1Mzc3MGMyYjFhM2ZhYWJhNjQyNjhiZjQxNDhiYWMyYjlhYWUzZSIsInRhZyI6IiJ9.jpg"
        }
      },
      "species": "Silver Birch",
      "plantedOn": "2021-12-26T15:20:42.000000Z"
    }
  ]
}
Response examples (404) 
{
  "type": "https://protect.earth/probs/something-went-wrong",
  "title": "You do not have enough credit.",
  "status": 400,
  "detail": "Your current balance is 30, but that costs 50.",
  "instance": "/account/12345/msgs/abc"
}