Partner API

Create Order

Add MCP server to your AI tool

Allow AI tools and LLMs to interact with the API documentation portal through MCP.

MCP server URL

https://bump.sh/protect-earth/doc/partner-api/mcp

Standard setup for AI tools providing an mcp.json file

mcp.json 
{
  "Partner API MCP server": {
    "url": "https://bump.sh/protect-earth/doc/partner-api/mcp"
  }
}
Close
POST /orders
Api key

Create a manual order for the organization identified by the bearer token. Orders created here are billed manually and use the tree product type. Contact support to arrange another product type.

Headers

  • idempotency-key string Required

    A unique key for this order request. Reusing the same key for 15 minutes returns the original response instead of creating another order.

    Minimum length is 1.

application/json

Body Required

  • orderedUnits integer Required

    Number of tree units to order. Orders created through this endpoint always use the tree product type.

    Minimum value is 1.

Responses

  • 201 application/json

    Order created.

    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
    • personalisedCertificateMessage string Deprecated
    • personalisedEmailMessage string Deprecated
    • 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
        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
        Hide photos attribute Show photos attribute object | null
        • large object
          Hide large attributes Show large attributes object
          • height integer(int64)
          • width integer(int64)
          • url string(url) Required
      • species string
      • plantedOn string(date-time)
    • links object
      Hide links attribute Show links attribute object
      • organization string(uri)
  • 400 application/problem+json

    Idempotency-Key header is missing.

    Hide response attributes Show response attributes object
    • type string Required
    • title string Required
    • status integer
    • detail string
    • instance string
  • 401 application/problem+json

    Unauthorized.

    Hide response attributes Show response attributes object
    • type string Required
    • title string Required
    • status integer
    • detail string
    • instance string
  • 422 application/problem+json

    Validation failed.

    Hide response attributes Show response attributes object
    • type string Required
    • title string Required
    • status integer
    • detail string
    • instance string
POST /orders 
curl \
 --request POST 'https://api.protect.earth/orders' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --header "idempotency-key: string" \
 --data '{
  "orderedUnits": 600
}'
Request examples 
# Headers
idempotency-key: string

# Payload
{
  "orderedUnits": 600
}
Response examples (201) 
{
  "id": "string",
  "brand": "string",
  "type": "manual",
  "source": "corporate",
  "status": "incomplete",
  "receivedOn": "2026-05-04T09:42:00Z",
  "fulfilledOn": "2026-05-04T09:42:00Z",
  "personalisedCertificateMessage": "string",
  "personalisedEmailMessage": "string",
  "unitType": "tree",
  "orderedUnits": 600,
  "allocatedUnits": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "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"
    }
  ],
  "links": {
    "organization": "https://example.com"
  }
}
Response examples (400) 
{
  "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"
}
Response examples (401) 
{
  "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"
}
Response examples (422) 
{
  "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"
}