Create a purchase

Buy carbon credits with a pricing ID, request confirmation and certificate documents, and make retries safe.

Registers a purchase of carbon credits. You need a pricing ID from Quote a price or Calculate and price in one request. With the payment method batch_settlement, SQUAKE invoices you regularly for a batch of purchases.

Request

POST /v2/purchases

pricingstringrequired

The pricing ID, the id returned by the pricing endpoint.

external_referencestring

Your own unique reference for the purchase. A retry with the same reference doesn't register a second purchase. Use a value with enough entropy, such as a version 4 UUID.

metadataobject

Your own key-value pairs. Never shown to users.

confirmation_documentobject

Request a compensation confirmation. See Document fields.

certificate_documentobject

Request a compensation certificate. See Document fields.

expandarray

["files"] to receive the requested documents as file objects instead of IDs.

See every field of POST /v2/purchases in the API reference
{
  "pricing": "eyJhbGciOiJIUzI1NiJ9.eyJwIjoicHJpY2VfMU1Ncm9MMmVaIn0...",
  "external_reference": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
  "metadata": { "booking_id": "BK-2026-0042" },
  "confirmation_document": {
    "full_name": "Example Company GmbH",
    "email": "sustainability@example.com",
    "locale": "de",
    "address": {
      "line1": "Example Street 1",
      "city": "Berlin",
      "postal_code": "10115",
      "country": "DE"
    }
  },
  "certificate_document": {
    "full_name": "Example Company GmbH",
    "flags": ["with_attribution"],
    "locale": "de",
    "address": {
      "line1": "Example Street 1",
      "city": "Berlin",
      "postal_code": "10115",
      "country": "DE"
    }
  }
}

Save the request as purchase.json and send it:

curl --request POST "https://api.sandbox.squake.earth/v2/purchases" \
  --header "Authorization: Bearer $SQUAKE_API_KEY" \
  --header "Content-Type: application/json" \
  --data @purchase.json

Response

SQUAKE responds with 201 Created and the purchase:

201 Createdapplication/json
{
  "id": "purchase_sd234asdfl23",
  "files": [
    "file_34sdfgJH9df4g35",
    "file_7hkLm2Qp9xZt4"
  ],
  "payment_method": "batch_settlement",
  "state": "reserved",
  "metadata": { "booking_id": "BK-2026-0042" },
  "carbon_quantity": 0.123,
  "carbon_unit": "tonne",
  "total": 1845,
  "currency": "EUR",
  "external_reference": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
  "cancellable_until": "2026-11-24T10:15:00+00:00"
}
FieldTypeDescription
idstringThe purchase ID.
filesarrayThe requested documents, as file IDs or, with expand: ["files"], as file objects.
payment_methodstringbatch_settlement or stripe.
statestringWhere the purchase stands. See Purchase states.
metadataobjectYour own key-value pairs.
checkout_pageobjectWith the payment method stripe, the url of a checkout page bound to this purchase and the return_url.
carbon_quantitynumberThe carbon quantity bought.
carbon_unitstringUnit of carbon_quantity.
totalintegerThe price in the smallest unit of the currency.
currencystringCurrency of total.
external_referencestringYour reference, echoed from the request.
cancellable_untilstring (date-time)Until when you can cancel the purchase.

A new purchase starts as reserved: SQUAKE registered it and reserved the carbon credits. You can cancel it for 14 days, until cancellable_until.

Document fields

confirmation_document and certificate_document take the same fields:

full_namestringrequired

Legal name of the company or person the document is issued to. If you can't disclose it, send a de-personalized identifier such as a UUID.

addressobjectrequired

Address with line1, city, postal_code and country (ISO 3166-1 alpha-2 or alpha-3), all required, plus optional line2 and state.

emailstring

If set, SQUAKE emails the document to this address. Without it, no email is sent. Either way, a download link is available.

localestring

Language of the document and the email: de, en, es, fr, hi, it, ja, pt, pt-BR or zh-CN. Defaults to en.

confirmation_document also takes on_behalf_of, with a full_name and an optional address, when you compensate on behalf of another company or person. That name is printed on the document. certificate_document also takes flags: ["with_attribution"] mentions your name on the certificate.

Getting the documents

The response lists the document IDs right away, but generating a document takes time. Fetch the files after the purchase with Retrieve a file to keep the purchase call fast. A file's download_url is empty until the document exists. To avoid polling, register a confirmation_document_available or certificate_document_available webhook.

Retries and idempotency

A pricing can back any number of purchases, so retrying a failed call without an external_reference can buy twice. Send a unique external_reference with every purchase. If the network fails, retry with the same reference: SQUAKE doesn't register a second purchase. You can also read the purchase by its external_reference with Retrieve a purchase.

Errors

StatusMeaning
400The request is malformed or misses a required field.
401The API key is missing or invalid.
403The request is forbidden for your account. Contact SQUAKE if you think it shouldn't be.

On this page

POST/v2/purchases

Run this request against the sandbox with your test key.

Open in API reference