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.

❗️

You need a quote first

The request requires a quoteId. You get this from a Create carbon quote call, or from any of the session endpoints (checkout, post-purchase and ImpactPay). The quote locks in pricing and tax rates. Do not recalculate amounts independently.

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. You can optionally specify one or more projectIds to direct funds to particular projects. If you omit projectIds, ekko uses the projects from the quote and splits the allocation across them.

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.

⚠️

Unmatched project IDs

If you pass a project ID that wasn't included in the original quote, ekko will allocate the funds across all projects for the same impact partner. A warning is returned in the response. To allocate to a specific project, use a project ID returned by the List quote projects endpoint (GET /quotes/{id}/projects) for that quote.

Making the request

Call POST /funds/allocations with your organisationId, the quoteId and currencyCode. Include credits, contribution or both.

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",
  "currencyCode": "GBP",
  "credits": {
    "amount": 0.52,
    "projectIds": ["5cc398c1-baa2-4504-a95e-f925c8c7ac9c"]
  }
}

Contribution only:

{
  "organisationId": "1f9e36e2-fdf3-4d36-a6ae-a2a146ab5ca1",
  "quoteId": "a6711057-1b63-41e0-81c3-24c02c5ef63b",
  "currencyCode": "GBP",
  "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",
  "currencyCode": "GBP",
  "credits": {
    "amount": 0.52,
    "projectIds": ["5cc398c1-baa2-4504-a95e-f925c8c7ac9c"]
  },
  "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",
  "currencyCode": "USD",
  "credits": {
    "amount": 0.52,
    "projectIds": ["5cc398c1-baa2-4504-a95e-f925c8c7ac9c"]
  },
  "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"
}