This page explains when and how to create organisations in the ekko Climate API. For the full request and response schema, see the Create organisation endpoint in the API reference.

Your top-level organisation is always set up by ekko. From there, you can create child organisations to represent the entities in your hierarchy.

When to create an organisation

Create a child organisation when:

The organisation needs its own API key
You need detailed reporting per organisation in ekko

If the organisation has a consistent Merchant Category Code (MCC), you can set it during creation. When an MCC is set at the organisation level, you don't need to pass merchant details in impact quote or SDK session requests.

When not to create an organisation

You don't need to create organisations for every entity in your hierarchy. For example:

You're a bank and need footprint calculations for a large variety of merchants on behalf of your consumers. The merchants don't need to be organisations. Instead, pass merchant details per quote request.
You don't need detailed reporting per organisation.

In these cases, you generate quotes by passing merchant details in each request.

Request fields

The v3 API requires the following fields to create an organisation:

Field	Type	Required	Description
`parentOrganisationId`	UUID	Yes	The parent organisation's ID
`tradingName`	String	Yes	Trading name of the organisation
`legalName`	String	Yes	Legal name of the organisation
`address`	Object	Yes	Organisation address
`address.line1`	String	Yes	First line of the address
`address.line2`	String	No	Second line of the address
`address.line3`	String	No	Third line of the address
`address.city`	String	Yes	City
`address.postalCode`	String	Yes	Postal code
`address.state`	String	No	State, if applicable
`address.countryCode`	String	Yes	ISO 3166-1 alpha-3 country code (3 characters)
`currencyCode`	String	Yes	ISO currency code
`website`	String	No	Organisation website
`billing`	Object	No	Billing configuration. If omitted, ekko bills the nearest parent organisation up the tree where billing is configured.
`billing.companyRegistrationNumber`	String	Yes (if billing provided)	Company registration number
`billing.currencyCode`	String	Yes (if billing provided)	Billing currency code
`billing.email`	String	Yes (if billing provided)	Billing email address
`billing.taxNumber`	String	No	Tax number
`mcc`	String	No	Merchant Category Code (4 digits). If set, you can omit merchant details in impact quote and SDK session requests.
`relativeProfitShare`	Number	No	The organisation's percentage of the service fee passed down from its parent, expressed as a decimal (e.g. 0.6 = 60%). Defaults to 0 if not provided.
`organisationReference`	String	No	Optional metadata for your own internal references, such as a merchant ID or CRM identifier. Returned in reporting responses.

📘
Billing rules
If billing is omitted, ekko bills the nearest parent organisation up the tree where billing is configured. This may be several levels above. If billing is provided, include all required billing fields for this organisation.

Example: minimal request

This request creates an organisation with only the required fields. Billing defaults to the parent organisation and the relative profit share defaults to 0.

{
  "parentOrganisationId": "c2603ad7-d377-4f52-8a78-02b5c3ee9523",
  "tradingName": "Blossom & Bloom",
  "legalName": "BB Flowers Ltd",
  "address": {
    "line1": "Ground floor",
    "line2": "45 Rosewood Avenue",
    "line3": "Unit 124A",
    "city": "London",
    "postalCode": "SW1A 1AA",
    "countryCode": "GBR"
  },
  "currencyCode": "GBP"
}

Example: full request with billing and profit share

This request includes billing details, an MCC and a relative profit share.

{
  "parentOrganisationId": "c2603ad7-d377-4f52-8a78-02b5c3ee9523",
  "tradingName": "Blossom & Bloom",
  "legalName": "BB Flowers Ltd",
  "address": {
    "line1": "Ground floor",
    "line2": "45 Rosewood Avenue",
    "line3": "Unit 124A",
    "city": "London",
    "postalCode": "SW1A 1AA",
    "countryCode": "GBR"
  },
  "currencyCode": "GBP",
  "website": "https://www.blossombloom.co.uk",
  "billing": {
    "companyRegistrationNumber": "987654321",
    "currencyCode": "GBP",
    "email": "[email protected]",
    "taxNumber": "123456789"
  },
  "mcc": "5992",
  "relativeProfitShare": 0.6,
  "organisationReference": "MID1234567"
}

Response

The response includes all the fields you sent, plus fields that ekko populates automatically:

Field	Description
`organisationId`	The unique ID for the newly created organisation
`proportionalProfitShare`	The effective profit share after applying the full organisation hierarchy. See Fee structure for details.
`serviceFeePercentage`	The service fee percentage, set by ekko during onboarding of the top-level organisation
`status`	Organisation status (`active` or `inactive`) with an optional message
`impactPartners`	Impact partners inherited from the parent organisation
`calculationTypes`	The impact types available for this organisation (e.g. `carbon`, `nature`)

{
  "organisationId": "2f6d6b1f-1c6a-4e9a-9c15-7b8a0db1a2c3",
  "parentOrganisationId": "9e1d3a52-0e3d-4a9f-8b6e-1c2d3e4f5a6b",
  "organisationReference": "MID1234567",
  "tradingName": "Blossom & Bloom",
  "legalName": "BB Flowers Ltd",
  "address": {
    "line1": "Ground floor",
    "line2": "45 Rosewood Avenue",
    "line3": "Unit 124A",
    "city": "London",
    "postalCode": "SW1A 1AA",
    "state": "",
    "countryCode": "GBR"
  },
  "currencyCode": "GBP",
  "website": "https://www.blossombloom.co.uk",
  "billing": {
    "companyRegistrationNumber": "987654321",
    "currencyCode": "GBP",
    "email": "[email protected]",
    "taxNumber": "123456789"
  },
  "mcc": "5992",
  "relativeProfitShare": 0.6,
  "proportionalProfitShare": 0.12,
  "serviceFeePercentage": 0.2,
  "status": {
    "value": "active",
    "message": null
  },
  "impactPartners": [
    {
      "id": "250636c2-8702-47c1-9720-7c3f93395790",
      "name": "Gold Standard"
    },
    {
      "id": "9405545f-a850-4427-ab0d-10b5b734e925",
      "name": "Tusk"
    }
  ],
  "calculationTypes": [
    "carbon"
  ]
}

Exclusions

In some cases, an impact partner may choose not to work with certain types of organisations or merchant categories (e.g. gambling). When an exclusion applies, the response includes an explanation in the status.message field:

{
  "status": {
    "value": "active",
    "message": "Impact partner Gold Standard has chosen not to work with gambling companies and is therefore not available for this organisation."
  }
}