Lune Webhook request API

openapi: 3.2.0
info:
  title: Lune Webhook request API
  version: '1.0'
  contact:
    name: Lune Support
    email: support@lune.co
  termsOfService: https://lune.co/terms
  description: 'Operations tagged Webhook request across 2 of this provider''s published API definitions: openapi.yml, lune-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.lune.co/v1
  description: Lune's REST API
tags:
- name: Webhook request
  description: Webhook request response example.
  x-lune-component: WebhookRequest
paths:
  /WebhookRequest:
    post:
      tags:
      - Webhook request
      summary: Webhook request
      operationId: webhookRequest
      description: The endpoint describes the request that you will receive in your webhook receiver and the responses the Lune webhook infrastructure expects.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookRequest'
      responses:
        '200':
          description: The events have been successfully handled. Any status code of the `2xx` format has the same behaviour. Any header or body are ignored by Lune.
    servers:
    - url: https://api.lune.co/v1
      description: Lune's REST API
components:
  schemas:
    WebhookRequest:
      description: 'WebhookRequest represents the request that your webhook receiver receives.

        '
      type: object
      required:
      - events
      properties:
        events:
          type: array
          description: An array of WebhookEvent objects.
          items:
            $ref: '#/components/schemas/WebhookEvent'
    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
          example: va1BER4JZqnzPkYxJgALg0GeQDoXlWO5
        idempotency_key:
          type:
          - string
          - 'null'
          maxLength: 100
          example: 5bd808a954e
          description: 'Account-unique identifier provided by the client.


            `idempotency_key` has two purposes:

            1. Clients can use `idempotency_key` to prevent duplicate orders.

            2. Clients can use `idempotency_key` to reconcile orders with other entities on their system.


            If an order with the same `idempotency_key` already exists, the API returns

            HTTP 409 Conflict with error code `order_idempotency_already_exists`. To

            retrieve the existing order, use the

            `GET /v1/orders/by-idempotency-key/{idempotency_key}` endpoint.

            '
          default: null
        type:
          type: string
          description: Identifies whether the order has been placed by quantity (kg CO2) or value (monetary amount)
          example: quantity
          enum:
          - quantity
          - value
        status:
          type: string
          description: Order status
          example: complete
          enum:
          - received
          - placed
          - paid
          - retiring
          - cancelled
          - complete
          - failed
        currency:
          type: string
          description: Order currency code
          example: GBP
        offset_cost:
          type:
          - string
          - 'null'
          description: 'The net offset cost being purchased. May be lower than `requested_value`.


            This property is set when bundles are assigned to the order.

            Unit: order currency

            '
          pattern: ^[0-9]+(\.[0-9]+)?$
          example: '7176.00'
        total_cost:
          type:
          - string
          - 'null'
          description: 'The total cost for the order inclusive of fees.


            Unit: order currency

            '
          pattern: ^[0-9]+(\.[0-9]+)?$
          example: '7696.00'
        commission:
          type:
          - string
          - 'null'
          description: 'Lune''s fee.


            This property is set when bundles are assigned to the order.

            Unit: order currency

            '
          pattern: ^[0-9]+(\.[0-9]+)?$
          example: '520.00'
        quantity:
          type:
          - string
          - 'null'
          pattern: ^[0-9]+(\.[0-9]+)?$
          example: '1040'
          description: Quantity of CO2 offsets purchased in tonnes.
        payment_method:
          description: 'How the order will be paid.

            When `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`.


            The bundles associated with the order including their relative quantity and cost breakdown.

            '
          items:
            $ref: '#/components/schemas/OrderBundle'
        projects:
          type:
          - array
          - 'null'
          description: 'Projects are set when the order''s status is `retiring` or `complete`.


            The projects associated with the order including their relative quantity and cost breakdown.


            Orders are placed against bundles, not projects. Projects in a bundle may change based on supply.


            This property is set as soon as we can guarantee project supply.

            '
          items:
            $ref: '#/components/schemas/OrderProject'
          example:
          - quantity: '600'
            unit_price: '6.90'
            offset_cost: '4140.00'
            project_id: gMbvJoOaX54V1wpNaRY8dWDGQ7m239Bx
            project_name: Madre De Dios
            project_type: Forest Conservation
            project_slug: madre-de-dios
          - quantity: '440'
            unit_price: '6.90'
            offset_cost: '3036.00'
            project_id: xe1BEV2VZqnzPkYxJgALg0GeQDoXlWO5
            project_name: Alto Mayo
            project_type: Forest Conservation
            project_slug: alto-mayo
        certificate:
          type:
          - string
          - 'null'
          description: 'Carbon credits PDF certificate URL.


            This property is set when an order has state ''complete''


            The property is set (and the certificate is available) regardless of the

            Sustainability page configuration.


            The URL requires API authentication and cannot be accessed anonymously.

            '
          example: https://api.lune.co/v1/orders/08QD7GPaBx5b6Y60ndAONXLvrZljRE2e/certificate
        public_certificate_url:
          type:
          - string
          - 'null'
          description: 'The Carbon credits certificate public URL.


            Once the Sustainability page of the associated account is enabled and configured to include the

            certificate section, and the order is set to ''complete'', this URL will link to the publicly accessible certificate.

            '
          example: https://sustainability.lune.co/account?certificate=1
        metadata:
          $ref: '#/components/schemas/Metadata'
        offset_link_id:
          type:
          - string
          - 'null'
          description: The offset link identifier, if the order was placed through an offset link
          example: UwjfkXjfksoHXzA1qjANL58GhjwqkxpB
        email:
          type:
          - string
          - 'null'
          description: 'End-user email.


            This property is currently populated on orders placed through offset links.

            '
          example: john@doe.com
    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]+)?$
          example: '7700'
        requested_quantity:
          description: Requested quantity of CO2 offsets to purchase in tonnes.
          oneOf:
          - $ref: '#/components/schemas/NullEnum'
        estimate_id:
          description: The emission calculation unique identifier
          oneOf:
          - $ref: '#/components/schemas/NullEnum'
    OrderEventDetails:
      type: object
      required:
      - order
      properties:
        order:
          $ref: '#/components/schemas/Order'
    NullEnum:
      type:
      - string
      - 'null'
      x-lune-name: 'Null'
      description: The property is set to `null`.
      enum:
      - null
    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
          example: xe1BEV2VZqnzPkYxJgALg0GeQDoXlWO5
        project_name:
          type: string
          description: The project's name
          example: Alto Mayo
        project_type:
          type: string
          description: The project's offset type, eg Forest conservation, Afforestation, Direct Air Capture
          example: Forest conservation
        project_slug:
          type: string
          description: The project's unique slug
          example: alto-mayo
        project_logo:
          type: string
          description: URL to the project's logo
          example: https://assets.lune.co/projects/green-sand-logo.png
        quantity:
          type: string
          pattern: ^[0-9]+(\.[0-9]+)?$
          example: '1040'
          description: Carbon offset purchased (tonnes CO2)
        unit_price:
          type: string
          description: 'Project unit price per tonne CO2


            Unit: order currency

            '
          pattern: ^[0-9]+(\.[0-9]+)?$
          example: '6.09'
        offset_cost:
          type: string
          description: 'The net offset cost being purchased.


            Unit: order currency

            '
          pattern: ^[0-9]+(\.[0-9]+)?$
          example: '7176.00'
        status:
          description: 'Describes whether credits for a project have been allocated to an order or retired

            '
          type: string
          enum:
          - allocated
          - retired
          example: retired
    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
          example: va1BEV2VZqnzPkYxJgALg0GeQDoXlWO5
        bundle_name:
          type: string
          description: The bundle's name
          example: Latin America Forestry
        primary_image:
          type: string
          description: A bundle's image URL
          example: https://assets.lune.co/bundles/latin-america-forestry.png
        quantity:
          type: string
          pattern: ^[0-9]+(\.[0-9]+)?$
          example: '1040'
          description: Quantity for the specific bundle (tonnes CO2)
        unit_price:
          type: string
          description: 'Bundle unit price per tonne CO2


            Unit: order currency

            '
          pattern: ^[0-9]+(\.[0-9]+)?$
          example: '6.90'
        gross_unit_price:
          type: string
          description: 'Bundle unit price per tonne CO2 inclusive of fees.


            Unit: order currency

            '
          pattern: ^[0-9]+(\.[0-9]+)?$
          example: '7.90'
        offset_cost:
          type: string
          description: 'The bundle''s net offset cost being purchased.


            Unit: order currency

            '
          pattern: ^[0-9]+(\.[0-9]+)?$
          example: '7176.00'
        insufficient_available_quantity:
          type:
          - boolean
          - 'null'
          description: 'If true, there is no inventory necessary to fully satisfy the order for this bundle.

            '
          example: true
    Order:
      type: object
      description: 'An Order represents a carbon credit purchase.


        Orders 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.


        An Order transitions through multiple statuses throughout its lifetime as Lune fulfills the Order.


        As soon as an Order has a credit retired, the Order''s certificate can be downloaded.

        '
      allOf:
      - $ref: '#/components/schemas/OrderBase'
      - type: object
        oneOf:
        - x-lune-name: By quantity
          $ref: '#/components/schemas/OrderByQuantityProperties'
        - x-lune-name: By estimate
          $ref: '#/components/schemas/OrderByEstimateProperties'
        - x-lune-name: By value
          $ref: '#/components/schemas/OrderByValueProperties'
        discriminator:
          propertyName: type
          mapping:
            quantity: '#/components/schemas/OrderByQuantityProperties'
            value: '#/components/schemas/OrderByValueProperties'
    OrderByEstimateProperties:
      type: object
      required:
      - estimate_id
      - requested_value
      - requested_quantity
      properties:
        estimate_id:
          type: string
          description: The emission calculation unique identifier
          example: 90ng23MKvLqbkpMwMw7yMBD4wJQrV6O6
        requested_value:
          description: Requested value of CO2 offsets to purchase in the account's currency.
          oneOf:
          - $ref: '#/components/schemas/NullEnum'
        requested_quantity:
          type: string
          pattern: ^[0-9]+(\.[0-9]+)?$
          example: '1045'
          description: Requested quantity of CO2 offsets to purchase in tonnes.
    OrderAllocation:
      type: object
      required:
      - id
      - order_id
      - project_id
      - quantity
      - status
      - created_at
      properties:
        id:
          type: string
          description: The allocation's unique identifier
          example: ka1aAQ61sAB8DQ12KggnaKG21EftR4E6
        order_id:
          type: string
          description: The order's unique identifier
          example: xe1BEV2VZqnzPkYxJgALg0GeQDoXlWO3
        project_id:
          type: string
          description: The project's unique identifier
          example: 1vE213P96LbXNap56NAqVoM7knOedQg4
        quantity:
          type: string
          example: '222.667'
          pattern: ^[0-9]+(\.[0-9]+)?$
        status:
          type: string
          description: Allocation status
          example: new
          enum:
          - new
          - retired
        created_at:
          type: string
          format: date-time
          description: Allocation creation timestamp
    OrderByQuantityProperties:
      type: object
      required:
      - requested_quantity
      - requested_value
      - estimate_id
      properties:
        requested_quantity:
          type: string
          pattern: ^[0-9]+(\.[0-9]+)?$
          example: '1045'
          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: '#/components/schemas/NullEnum'
        estimate_id:
          description: The emission calculation unique identifier
          oneOf:
          - $ref: '#/components/schemas/NullEnum'
    Metadata:
      description: 'An arbitrary dictionary (key-value pairs) to store application-specific information.


        Lune doesn''t use this information for order processing. Its purpose is for the API

        clients to be able to attach arbitrary information (to an order for example) and

        then retrieve it.

        '
      type: object
      additionalProperties:
        type: string
    WebhookEvent:
      type: object
      required:
      - api_version
      - event_id
      - event_type
      - sequence
      - data
      properties:
        api_version:
          type: string
          example: v1
          description: 'Version of the API that serialized the event. The only possible value at the moment is `v1`.

            '
        account_id:
          type: string
          example: ljmkOq7vXd239gAE9WALWQ8ZGVD5ExNz
          description: The account identifier the event belongs to.
        event_id:
          type: string
          example: va1BER4JZqnzPkYxJgALg0GeQDoXlWO5
          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
          example: 2021-09-13 16:21:29.067803
          description: 'The event’s sequence. This can be compared lexicographically to determine the order of events.


            The details of the format are subject to change without notice as long as the lexicographical

            ordering property remains intact. You can''t depend on the values having any particular shape

            (in particular you can''t depend on them being valid timestamps).

            '
        data:
          description: Data of the event. On order.* events, this means an Order. On allocation.* events, this mean an allocation.
          oneOf:
          - $ref: '#/components/schemas/OrderEventDetails'
          - $ref: '#/components/schemas/AllocationEventDetails'
    AllocationEventDetails:
      type: object
      required:
      - allocation
      properties:
        allocation:
          description: Snapshot of the allocation at the time of the event
          $ref: '#/components/schemas/OrderAllocation'
        splitFrom:
          description: Original allocation that triggered the split
          $ref: '#/components/schemas/OrderAllocation'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Authorization Bearer API Key (see <a href="#section/Authentication">Authentication</a>)
    AccessToken:
      type: apiKey
      in: query
      name: access_token
      description: 'An API key used to access a resource that accepts it in the URL.


        Note: Lune API keys are not URL-safe, which means that they can''t be included in URLs directly.

        They need to be percent-encoded using a function like JavaScript''s [`encodeURIComponent()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) or

        Python''s [`urllib.parse.quote()`](https://docs.python.org/3/library/urllib.parse.html#urllib.parse.quote).

        '
x-refined-from:
- openapi.yml
- lune-openapi.yml