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
pricingstringrequiredThe pricing ID, the id returned by the pricing endpoint.
external_referencestringYour 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.
metadataobjectYour own key-value pairs. Never shown to users.
confirmation_documentobjectRequest a compensation confirmation. See Document fields.
certificate_documentobjectRequest a compensation certificate. See Document fields.
expandarray["files"] to receive the requested documents as file objects instead of IDs.
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.jsonResponse
SQUAKE responds with 201 Created and the purchase:
{
"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"
}| Field | Type | Description |
|---|---|---|
id | string | The purchase ID. |
files | array | The requested documents, as file IDs or, with expand: ["files"], as file objects. |
payment_method | string | batch_settlement or stripe. |
state | string | Where the purchase stands. See Purchase states. |
metadata | object | Your own key-value pairs. |
checkout_page | object | With the payment method stripe, the url of a checkout page bound to this purchase and the return_url. |
carbon_quantity | number | The carbon quantity bought. |
carbon_unit | string | Unit of carbon_quantity. |
total | integer | The price in the smallest unit of the currency. |
currency | string | Currency of total. |
external_reference | string | Your reference, echoed from the request. |
cancellable_until | string (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_namestringrequiredLegal 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.
addressobjectrequiredAddress with line1, city, postal_code and country (ISO 3166-1 alpha-2 or alpha-3), all required, plus optional line2 and state.
emailstringIf set, SQUAKE emails the document to this address. Without it, no email is sent. Either way, a download link is available.
localestringLanguage 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
| Status | Meaning |
|---|---|
400 | The request is malformed or misses a required field. |
401 | The API key is missing or invalid. |
403 | The request is forbidden for your account. Contact SQUAKE if you think it shouldn't be. |
Related
- Retrieve a purchase
- Cancel a purchase
- Create a Purchase in the API reference