{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/lune/json-schema/lune-webhook-request-schema.json",
  "title": "WebhookRequest",
  "description": "WebhookRequest represents the request that your webhook receiver receives.\n",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/lune-webhook-request-api-openapi.yml#/components/schemas/WebhookRequest",
  "type": "object",
  "required": [
    "events"
  ],
  "properties": {
    "events": {
      "type": "array",
      "description": "An array of WebhookEvent objects.",
      "items": {
        "$ref": "#/$defs/WebhookEvent"
      }
    }
  },
  "$defs": {
    "AllocationEventDetails": {
      "type": "object",
      "required": [
        "allocation"
      ],
      "properties": {
        "allocation": {
          "description": "Snapshot of the allocation at the time of the event",
          "$ref": "#/$defs/OrderAllocation"
        },
        "splitFrom": {
          "description": "Original allocation that triggered the split",
          "$ref": "#/$defs/OrderAllocation"
        }
      }
    },
    "Metadata": {
      "description": "An arbitrary dictionary (key-value pairs) to store application-specific information.\n\nLune doesn't use this information for order processing. Its purpose is for the API\nclients to be able to attach arbitrary information (to an order for example) and\nthen retrieve it.\n",
      "type": "object",
      "additionalProperties": {
        "type": "string"
      }
    },
    "NullEnum": {
      "type": [
        "string",
        "null"
      ],
      "x-lune-name": "Null",
      "description": "The property is set to `null`.",
      "enum": [
        null
      ]
    },
    "Order": {
      "type": "object",
      "description": "An Order represents a carbon credit purchase.\n\nOrders are placed against one or multiple project bundles. Credits are allocated to the Order from any of the projects that belong to the bundles. These are then retired.\n\nAn Order transitions through multiple statuses throughout its lifetime as Lune fulfills the Order.\n\nAs soon as an Order has a credit retired, the Order's certificate can be downloaded.\n",
      "allOf": [
        {
          "$ref": "#/$defs/OrderBase"
        },
        {
          "type": "object",
          "oneOf": [
            {
              "x-lune-name": "By quantity",
              "$ref": "#/$defs/OrderByQuantityProperties"
            },
            {
              "x-lune-name": "By estimate",
              "$ref": "#/$defs/OrderByEstimateProperties"
            },
            {
              "x-lune-name": "By value",
              "$ref": "#/$defs/OrderByValueProperties"
            }
          ]
        }
      ]
    },
    "OrderAllocation": {
      "type": "object",
      "required": [
        "id",
        "order_id",
        "project_id",
        "quantity",
        "status",
        "created_at"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "The allocation's unique identifier"
        },
        "order_id": {
          "type": "string",
          "description": "The order's unique identifier"
        },
        "project_id": {
          "type": "string",
          "description": "The project's unique identifier"
        },
        "quantity": {
          "type": "string",
          "pattern": "^[0-9]+(\\.[0-9]+)?$"
        },
        "status": {
          "type": "string",
          "description": "Allocation status",
          "enum": [
            "new",
            "retired"
          ]
        },
        "created_at": {
          "type": "string",
          "format": "date-time",
          "description": "Allocation creation timestamp"
        }
      }
    },
    "OrderBase": {
      "type": "object",
      "description": "Order object",
      "required": [
        "id",
        "idempotency_key",
        "type",
        "status",
        "currency",
        "offset_cost",
        "total_cost",
        "commission",
        "quantity",
        "created_at",
        "bundles",
        "projects",
        "certificate",
        "public_certificate_url",
        "metadata",
        "offset_link_id",
        "email",
        "payment_method"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "The order's unique identifier"
        },
        "idempotency_key": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 100,
          "description": "Account-unique identifier provided by the client.\n\n`idempotency_key` has two purposes:\n1. Clients can use `idempotency_key` to prevent duplicate orders.\n2. Clients can use `idempotency_key` to reconcile orders with other entities on their system.\n\nIf an order with the same `idempotency_key` already exists, the API returns\nHTTP 409 Conflict with error code `order_idempotency_already_exists`. To\nretrieve the existing order, use the\n`GET /v1/orders/by-idempotency-key/{idempotency_key}` endpoint.\n",
          "default": null
        },
        "type": {
          "type": "string",
          "description": "Identifies whether the order has been placed by quantity (kg CO2) or value (monetary amount)",
          "enum": [
            "quantity",
            "value"
          ]
        },
        "status": {
          "type": "string",
          "description": "Order status",
          "enum": [
            "received",
            "placed",
            "paid",
            "retiring",
            "cancelled",
            "complete",
            "failed"
          ]
        },
        "currency": {
          "type": "string",
          "description": "Order currency code"
        },
        "offset_cost": {
          "type": [
            "string",
            "null"
          ],
          "description": "The net offset cost being purchased. May be lower than `requested_value`.\n\nThis property is set when bundles are assigned to the order.\nUnit: order currency\n",
          "pattern": "^[0-9]+(\\.[0-9]+)?$"
        },
        "total_cost": {
          "type": [
            "string",
            "null"
          ],
          "description": "The total cost for the order inclusive of fees.\n\nUnit: order currency\n",
          "pattern": "^[0-9]+(\\.[0-9]+)?$"
        },
        "commission": {
          "type": [
            "string",
            "null"
          ],
          "description": "Lune's fee.\n\nThis property is set when bundles are assigned to the order.\nUnit: order currency\n",
          "pattern": "^[0-9]+(\\.[0-9]+)?$"
        },
        "quantity": {
          "type": [
            "string",
            "null"
          ],
          "pattern": "^[0-9]+(\\.[0-9]+)?$",
          "description": "Quantity of CO2 offsets purchased in tonnes."
        },
        "payment_method": {
          "description": "How the order will be paid.\nWhen `card`, Lune will attempt to charge the card and pay this order. When `invoice`, Lune will email an invoice with payment instructions.",
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "invoice",
            "card",
            null
          ]
        },
        "created_at": {
          "type": "string",
          "format": "date-time",
          "description": "Order creation timestamp"
        },
        "bundles": {
          "type": [
            "array",
            "null"
          ],
          "description": "bundles are set when the order's status is `placed`, `paid`, `retiring` or `complete`.\n\nThe bundles associated with the order including their relative quantity and cost breakdown.\n",
          "items": {
            "$ref": "#/$defs/OrderBundle"
          }
        },
        "projects": {
          "type": [
            "array",
            "null"
          ],
          "description": "Projects are set when the order's status is `retiring` or `complete`.\n\nThe projects associated with the order including their relative quantity and cost breakdown.\n\nOrders are placed against bundles, not projects. Projects in a bundle may change based on supply.\n\nThis property is set as soon as we can guarantee project supply.\n",
          "items": {
            "$ref": "#/$defs/OrderProject"
          }
        },
        "certificate": {
          "type": [
            "string",
            "null"
          ],
          "description": "Carbon credits PDF certificate URL.\n\nThis property is set when an order has state 'complete'\n\nThe property is set (and the certificate is available) regardless of the\nSustainability page configuration.\n\nThe URL requires API authentication and cannot be accessed anonymously.\n"
        },
        "public_certificate_url": {
          "type": [
            "string",
            "null"
          ],
          "description": "The Carbon credits certificate public URL.\n\nOnce the Sustainability page of the associated account is enabled and configured to include the\ncertificate section, and the order is set to 'complete', this URL will link to the publicly accessible certificate.\n"
        },
        "metadata": {
          "$ref": "#/$defs/Metadata"
        },
        "offset_link_id": {
          "type": [
            "string",
            "null"
          ],
          "description": "The offset link identifier, if the order was placed through an offset link"
        },
        "email": {
          "type": [
            "string",
            "null"
          ],
          "description": "End-user email.\n\nThis property is currently populated on orders placed through offset links.\n"
        }
      }
    },
    "OrderBundle": {
      "type": "object",
      "required": [
        "bundle_id",
        "bundle_name",
        "quantity",
        "unit_price",
        "gross_unit_price",
        "offset_cost",
        "insufficient_available_quantity"
      ],
      "properties": {
        "bundle_id": {
          "type": "string",
          "description": "The bundle's unique identifier"
        },
        "bundle_name": {
          "type": "string",
          "description": "The bundle's name"
        },
        "primary_image": {
          "type": "string",
          "description": "A bundle's image URL"
        },
        "quantity": {
          "type": "string",
          "pattern": "^[0-9]+(\\.[0-9]+)?$",
          "description": "Quantity for the specific bundle (tonnes CO2)"
        },
        "unit_price": {
          "type": "string",
          "description": "Bundle unit price per tonne CO2\n\nUnit: order currency\n",
          "pattern": "^[0-9]+(\\.[0-9]+)?$"
        },
        "gross_unit_price": {
          "type": "string",
          "description": "Bundle unit price per tonne CO2 inclusive of fees.\n\nUnit: order currency\n",
          "pattern": "^[0-9]+(\\.[0-9]+)?$"
        },
        "offset_cost": {
          "type": "string",
          "description": "The bundle's net offset cost being purchased.\n\nUnit: order currency\n",
          "pattern": "^[0-9]+(\\.[0-9]+)?$"
        },
        "insufficient_available_quantity": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "If true, there is no inventory necessary to fully satisfy the order for this bundle.\n"
        }
      }
    },
    "OrderByEstimateProperties": {
      "type": "object",
      "required": [
        "estimate_id",
        "requested_value",
        "requested_quantity"
      ],
      "properties": {
        "estimate_id": {
          "type": "string",
          "description": "The emission calculation unique identifier"
        },
        "requested_value": {
          "description": "Requested value of CO2 offsets to purchase in the account's currency.",
          "oneOf": [
            {
              "$ref": "#/$defs/NullEnum"
            }
          ]
        },
        "requested_quantity": {
          "type": "string",
          "pattern": "^[0-9]+(\\.[0-9]+)?$",
          "description": "Requested quantity of CO2 offsets to purchase in tonnes."
        }
      }
    },
    "OrderByQuantityProperties": {
      "type": "object",
      "required": [
        "requested_quantity",
        "requested_value",
        "estimate_id"
      ],
      "properties": {
        "requested_quantity": {
          "type": "string",
          "pattern": "^[0-9]+(\\.[0-9]+)?$",
          "description": "Requested quantity of CO2 offsets to purchase in tonnes."
        },
        "requested_value": {
          "description": "Requested value of CO2 offsets to purchase in the account's currency.",
          "oneOf": [
            {
              "$ref": "#/$defs/NullEnum"
            }
          ]
        },
        "estimate_id": {
          "description": "The emission calculation unique identifier",
          "oneOf": [
            {
              "$ref": "#/$defs/NullEnum"
            }
          ]
        }
      }
    },
    "OrderByValueProperties": {
      "type": "object",
      "required": [
        "requested_value",
        "requested_quantity",
        "estimate_id"
      ],
      "properties": {
        "requested_value": {
          "description": "Requested value of CO2 offsets to purchase in the account's currency.",
          "type": "string",
          "pattern": "^[0-9]+(\\.[0-9]+)?$"
        },
        "requested_quantity": {
          "description": "Requested quantity of CO2 offsets to purchase in tonnes.",
          "oneOf": [
            {
              "$ref": "#/$defs/NullEnum"
            }
          ]
        },
        "estimate_id": {
          "description": "The emission calculation unique identifier",
          "oneOf": [
            {
              "$ref": "#/$defs/NullEnum"
            }
          ]
        }
      }
    },
    "OrderEventDetails": {
      "type": "object",
      "required": [
        "order"
      ],
      "properties": {
        "order": {
          "$ref": "#/$defs/Order"
        }
      }
    },
    "OrderProject": {
      "type": "object",
      "required": [
        "project_id",
        "project_name",
        "project_type",
        "project_slug",
        "quantity",
        "unit_price",
        "offset_cost",
        "status"
      ],
      "properties": {
        "project_id": {
          "type": "string",
          "description": "The project's unique identifier"
        },
        "project_name": {
          "type": "string",
          "description": "The project's name"
        },
        "project_type": {
          "type": "string",
          "description": "The project's offset type, eg Forest conservation, Afforestation, Direct Air Capture"
        },
        "project_slug": {
          "type": "string",
          "description": "The project's unique slug"
        },
        "project_logo": {
          "type": "string",
          "description": "URL to the project's logo"
        },
        "quantity": {
          "type": "string",
          "pattern": "^[0-9]+(\\.[0-9]+)?$",
          "description": "Carbon offset purchased (tonnes CO2)"
        },
        "unit_price": {
          "type": "string",
          "description": "Project unit price per tonne CO2\n\nUnit: order currency\n",
          "pattern": "^[0-9]+(\\.[0-9]+)?$"
        },
        "offset_cost": {
          "type": "string",
          "description": "The net offset cost being purchased.\n\nUnit: order currency\n",
          "pattern": "^[0-9]+(\\.[0-9]+)?$"
        },
        "status": {
          "description": "Describes whether credits for a project have been allocated to an order or retired\n",
          "type": "string",
          "enum": [
            "allocated",
            "retired"
          ]
        }
      }
    },
    "WebhookEvent": {
      "type": "object",
      "required": [
        "api_version",
        "event_id",
        "event_type",
        "sequence",
        "data"
      ],
      "properties": {
        "api_version": {
          "type": "string",
          "description": "Version of the API that serialized the event. The only possible value at the moment is `v1`.\n"
        },
        "account_id": {
          "type": "string",
          "description": "The account identifier the event belongs to."
        },
        "event_id": {
          "type": "string",
          "description": "The event’s id. The id can be used for idempotency behaviour if stored on the client side."
        },
        "event_type": {
          "type": "string",
          "enum": [
            "order.received",
            "order.placed",
            "order.paid",
            "order.retiring",
            "order.cancelled",
            "order.failed",
            "order.completed",
            "allocation.new",
            "allocation.retired"
          ],
          "description": "The event type. The type of event data will depend on the value present here."
        },
        "sequence": {
          "type": "string",
          "description": "The event’s sequence. This can be compared lexicographically to determine the order of events.\n\nThe details of the format are subject to change without notice as long as the lexicographical\nordering property remains intact. You can't depend on the values having any particular shape\n(in particular you can't depend on them being valid timestamps).\n"
        },
        "data": {
          "description": "Data of the event. On order.* events, this means an Order. On allocation.* events, this mean an allocation.",
          "oneOf": [
            {
              "$ref": "#/$defs/OrderEventDetails"
            },
            {
              "$ref": "#/$defs/AllocationEventDetails"
            }
          ]
        }
      }
    }
  }
}