The Allocate funds endpoint converts a carbon quote into an active contribution, directing funds to carbon credit projects or impact partners. This page covers how to build the request, the difference between credits and contributions and tax receipts.

Credits and contributions

Credits and contributions are allocated differently because they represent different types of positive impact from funded projects.

Credits are tied to specific carbon credit projects. Project selection happens when you create the quote, and the allocation is split across the projects that quote priced. To influence which projects are selected, set projectFilters.credits.matchConsumerLocation on the carbon quote. To see which projects a quote priced, call the List quote projects endpoint (GET /quotes/{id}/projects).

Contributions are made at the impact partner level. The impact partner decides how to distribute funds across its projects. You can optionally specify one or more impactPartnerIds. If you omit impactPartnerIds, ekko uses the impact partners from the quote.

You must send at least one of credits or contribution in every request. Both are allowed in a single call.

Making the request

Call POST /funds/allocations with your organisationId and the quoteId. Include credits, contribution or both. The allocation is priced in the quote's currency.

Pass an idempotencyKey to make retries safe. Sending the same key with the same payload returns the same allocation instead of creating a second one.

See the Create funds allocation endpoint for the full request and response schema.

Credits only:

{
  "organisationId": "1f9e36e2-fdf3-4d36-a6ae-a2a146ab5ca1",
  "quoteId": "a6711057-1b63-41e0-81c3-24c02c5ef63b",
  "idempotencyKey": "order_abc123",
  "credits": {
    "amount": 0.52
  }
}

Contribution only:

{
  "organisationId": "1f9e36e2-fdf3-4d36-a6ae-a2a146ab5ca1",
  "quoteId": "a6711057-1b63-41e0-81c3-24c02c5ef63b",
  "contribution": {
    "amount": 1.00,
    "impactPartnerIds": ["abdc3eb2-5464-4630-b0c8-b40dac0b930e"]
  }
}

Credits and contribution together:

{
  "organisationId": "1f9e36e2-fdf3-4d36-a6ae-a2a146ab5ca1",
  "quoteId": "a6711057-1b63-41e0-81c3-24c02c5ef63b",
  "credits": {
    "amount": 0.52
  },
  "contribution": {
    "amount": 1.00,
    "impactPartnerIds": ["abdc3eb2-5464-4630-b0c8-b40dac0b930e"]
  }
}

Tax receipts

For US-based organisations that require a donation tax receipt, set issueTaxReceipt to true and include consumerEmail. ekko sends a tax receipt directly to the consumer confirming the sustainability contribution and noting it may be tax deductible.

consumerEmail is required when issueTaxReceipt is true.

{
  "organisationId": "1f9e36e2-fdf3-4d36-a6ae-a2a146ab5ca1",
  "quoteId": "a6711057-1b63-41e0-81c3-24c02c5ef63b",
  "credits": {
    "amount": 0.52
  },
  "contribution": {
    "amount": 1.00,
    "impactPartnerIds": ["abdc3eb2-5464-4630-b0c8-b40dac0b930e"]
  },
  "issueTaxReceipt": true,
  "consumerEmail": "[email protected]"
}

The response

A successful request returns HTTP 201 with a fundsAllocationId and a breakdown per project or impact partner.

The credits array contains one entry per project, with impactAmount showing the amount directed to the project and serviceFeeAmount showing ekko's service fee. Sales tax amounts and rates are included for both.

The contributions array follows the same structure but groups by impactPartnerId rather than project.

taxLiability indicates whether your organisation or ekko's platform is responsible for sales tax handling on this allocation.

{
  "fundsAllocationId": "b7e9c4a2-8f31-4d6e-a529-3c7b8e1f0d42",
  "currencyCode": "GBP",
  "credits": [
    {
      "projectId": "dfa40a8a-8c24-404d-bed9-6bc3ee60b2b6",
      "impactAmount": 1.98,
      "impactSalesTaxAmount": 0,
      "impactSalesTaxRate": 0.0,
      "serviceFeeAmount": 0.5,
      "serviceFeeSalesTaxAmount": 0.02,
      "serviceFeeSalesTaxRate": 0.05
    }
  ],
  "contributions": [
    {
      "impactPartnerId": "9405545f-a850-4427-ab0d-10b5b734e925",
      "impactAmount": 0.27,
      "impactSalesTaxAmount": 0,
      "impactSalesTaxRate": 0.0,
      "serviceFeeAmount": 0.07,
      "serviceFeeSalesTaxAmount": 0.003,
      "serviceFeeSalesTaxRate": 0.05
    }
  ],
  "taxLiability": "platform"
}