Call POST /v3/checkout/sessions to create a session for the checkout SDK. The response returns a sessionId and clientSecret that you pass to the frontend SDK to render the impact component inside your checkout flow.

For SDK initialisation, events and customisation options, see Checkout SDK.

📘

You can omit merchant if the organisation has an MCC set at organisation level.

Making the request

The request requires organisationId, consumer and transaction. Set impactType to carbon or nature (defaults to carbon if omitted). The impactType decides which footprint the session generates and which quote endpoint runs in the backend.

{
  "organisationId": "2f6d6b1f-1c6a-4e9a-9c15-7b8a0db1a2c3",
  "impactType": "carbon",
  "consumer": {
    "reference": "consumer_123",
    "postalCode": "SW1A 1AA",
    "city": "London",
    "countryCode": "GBR"
  },
  "merchant": {
    "name": "Blossom & Bloom",
    "mcc": "5992",
    "address": {
      "line1": "Ground floor",
      "line2": "45 Rosewood Avenue",
      "city": "London",
      "postalCode": "SW1A 1AA",
      "countryCode": "GBR"
    }
  },
  "transaction": {
    "amount": 47.97,
    "currencyCode": "GBP"
  },
  "orderItems": [
    {
      "itemReference": "line_1",
      "sku": "POT_MEDIUM",
      "description": "Flower pot",
      "category": "pots",
      "quantity": 3,
      "unitPrice": {
        "value": 15.99,
        "currencyCode": "GBP"
      }
    }
  ],
  "projectFilters": {
    "credits": {
      "matchConsumerLocation": true
    }
  }
}

orderItems are optional and not used in the footprint calculation, but are recommended for analytics and reporting.

Choosing an impact type

A session carries one impact type. An impactType array (for example ["carbon", "nature"]) is rejected. To show both metrics, create two sessions. Filter fields that don't apply to the chosen impact type are ignored.

For background on the biodiversity metric, see nature footprint.

Nature request example

{
  "organisationId": "2f6d6b1f-1c6a-4e9a-9c15-7b8a0db1a2c3",
  "impactType": "nature",
  "consumer": {
    "reference": "consumer_123",
    "postalCode": "SW1A 1AA",
    "city": "London",
    "countryCode": "GBR"
  },
  "merchant": {
    "name": "Blossom & Bloom",
    "mcc": "5992",
    "address": {
      "line1": "Ground floor",
      "line2": "45 Rosewood Avenue",
      "city": "London",
      "postalCode": "SW1A 1AA",
      "countryCode": "GBR"
    }
  },
  "transaction": {
    "amount": 47.97,
    "currencyCode": "GBP"
  },
  "projectFilters": {
    "contribution": {
      "matchConsumerLocation": true,
      "matchTheme": true
    }
  }
}

Set projectFilters.contribution.matchTheme to true to rank impact partners by the transaction's dominant pressure category. Set matchConsumerLocation to true to rank them by how closely their projects match the consumer's location.

🚧

matchConsumerLocation differs by impact type

For carbon it sits under projectFilters.credits and targets carbon credit projects by location. For nature it sits under projectFilters.contribution and ranks contribution impact partners by location. The field name is shared, the behaviour is not.

The response

A successful request returns HTTP 201 with a session you can use to initialise the frontend SDK.

{
  "sessionId": "a3d8f6b2-9c14-4e7a-b8d5-2e6f1a3c9b78",
  "clientSecret": "cs_live_a94f2e7b1c3d4e5f9a0b_secret_K8mQ2R",
  "quoteId": "7b4f1b1b-47a0-4c2a-a5ed-2cfe5bfc2c4a",
  "expiresAt": "2026-01-07T17:14:58Z"
}

Pass sessionId and clientSecret to the Checkout SDK on the frontend. The quoteId is for your records and can be used to trace the session back to the underlying quote.

⚠️

Sessions expire at the time shown in expiresAt. Create a new session if the current one has expired.