Create a Purchase

POST /v2/purchases
Bearer auth

You can register a purchase programmatically to compensate for carbon emissions on this endpoint. You must quote for pricing beforehand and pass the returned pricing ID as a parameter.

Alternatively, you can use the payment_link from the pricing endpoint to finalize the purchase using SQUAKE's provided checkout page.

Lifecycle

When purchasing via API (this endpoint)
  • reserved: A successful purchase starts in the state "reserved"; SQUAKE registered your purchase and reserved carbon credits accordingly.
  • canceled: SQUAKE offers 14 days to cancel a purchase worry-free. This is a terminal state.
  • confirmed: The refundable period has passed. If you need to cancel the purchase beyond this point, please request a refund on the refunds endpoint.
  • invoiced: Without further action, a purchase is invoiced after the grace period and transitions to "invoiced".
When purchasing via the checkout page
  • payment_initiated: the end customer entered the payment flow on the checkout page
  • payment_aborted: the payment failed permanently, for example, because the customer exited the page without finalizing the payment and didn't return before the pricing's validity ended. This is a terminal state.
  • confirmed: the payment provider informed SQUAKE about the successful payment. In this flow, this state exists only for a short time; the purchase immediately continues to "settled".
Both
  • settled: SQUAKE has received the payment.
  • refunded: a refund request was successfully processed. This is a terminal state.
  • certificates_confirmed: all certificates for the carbon credits have been confirmed from all project partners related to the purchase.
  • certificates_retired: all certificates have been retired in the corresponding registries. This is a terminal state.
application/json

Body

  • pricing string Required

    The ID from the pricing endpoint

  • confirmation_document object

    Additional properties are allowed.

    Hide confirmation_document attributes Show confirmation_document attributes object
    • full_name string Required

      Legal name of an entity or natural person to which the document shall be issued. If you cannot disclose this, you can send any de-personalized identifier (such as a UUID).

    • address object Required

      Address of a legal entity. Some (legal) documets require a full address to be given, e.g. an invoice.

      Additional properties are allowed.

      Hide address attributes Show address attributes object
      • city string Required

        City, town, village,...

      • country string Required

        Two-letter or three-letter code as defined in ISO 3166-1 alpha-2 and alpha-3 respectively.

        Minimum length is 2, maximum length is 3. Format should match the following pattern: ^[A-Z]{2,3}$.

      • line1 string Required

        street, post box, company name, ...

      • line2 string

        suite, apartment number, ...

      • postal_code string Required

        ZIP or postal code

      • state string

        County, Province, Region, State,...

    • email string(email)

      SQUAKE can send an email with the compensation confirmation. If omitted, no email is sent. In either case, a download link will be made available.

    • on_behalf_of object

      If you make a compensation on behalf on another entity or person. This will be printed on the issued document.

      Additional properties are allowed.

      Hide on_behalf_of attributes Show on_behalf_of attributes object
      • full_name string Required
      • address object

        Address of a legal entity. Some (legal) documets require a full address to be given, e.g. an invoice.

        Additional properties are allowed.

        Hide address attributes Show address attributes object
        • city string Required

          City, town, village,...

        • country string Required

          Two-letter or three-letter code as defined in ISO 3166-1 alpha-2 and alpha-3 respectively.

          Minimum length is 2, maximum length is 3. Format should match the following pattern: ^[A-Z]{2,3}$.

        • line1 string Required

          street, post box, company name, ...

        • line2 string

          suite, apartment number, ...

        • postal_code string Required

          ZIP or postal code

        • state string

          County, Province, Region, State,...

    • locale string

      Two-letter ISO 639-1 or BCP 47 code describing a language. Descriptions and emails meant for end users can be localized. System messages meant for developers are always in english.

      Minimum length is 2, maximum length is 5. Format should match the following pattern: ^(?:[a-z]{2}|[a-z]{2}-[A-Z]{2})$. Values are de, en, es, fr, hi, it, ja, pt, pt-BR, or zh-CN. Default value is en.

  • certificate_document object

    Additional properties are allowed.

    Hide certificate_document attributes Show certificate_document attributes object
    • full_name string Required

      Legal name of an entity or natural person to which the document shall be issued. If you cannot disclose this, you can send any de-personalized identifier (such as a UUID).

    • address object Required

      Address of a legal entity. Some (legal) documets require a full address to be given, e.g. an invoice.

      Additional properties are allowed.

      Hide address attributes Show address attributes object
      • city string Required

        City, town, village,...

      • country string Required

        Two-letter or three-letter code as defined in ISO 3166-1 alpha-2 and alpha-3 respectively.

        Minimum length is 2, maximum length is 3. Format should match the following pattern: ^[A-Z]{2,3}$.

      • line1 string Required

        street, post box, company name, ...

      • line2 string

        suite, apartment number, ...

      • postal_code string Required

        ZIP or postal code

      • state string

        County, Province, Region, State,...

    • email string(email)

      SQUAKE can send an email with the compensation certificate. If omitted, no email is sent. In either case, a download link will be made available.

    • flags array[string]

      If "with_attribution" is sent, your name will be mentioned on the certificate; e.g. "(..) enabled by ${your_name} (..)".

      Value is with_attribution.

    • locale string

      Two-letter ISO 639-1 or BCP 47 code describing a language. Descriptions and emails meant for end users can be localized. System messages meant for developers are always in english.

      Minimum length is 2, maximum length is 5. Format should match the following pattern: ^(?:[a-z]{2}|[a-z]{2}-[A-Z]{2})$. Values are de, en, es, fr, hi, it, ja, pt, pt-BR, or zh-CN. Default value is en.

  • expand array[string]

    Receive either the file-id, or the file-object of a requested document. If omitted, only IDs are returned.

    Value is files.

  • metadata object

    A set of key-value pairs of yours that helps you link this record in your system. Never displayed to users.

    Additional properties are allowed.

  • external_reference string

    If given, this reference must be unique. Suppose you need idempotency on the purchase endpoint: in that case, the external reference must be provided, meaning you can retry a purchase call with the same pricing id multiple times without registering multiple purchases, e.g., to recover from a network failure. Remember: with a valid pricing id, you can register as many purchases as you need. The reference should have enough entropy; a great choice is a V4 UUID.

Responses

  • 201 application/json

    Created

    Hide headers attribute Show headers attribute
    • SQUAKE-Request-Id

      Unique identifier linked to this API request. If you need to contact us regarding a specific request, providing the request identifier helps the resolution process.

    Hide response attributes Show response attributes object
    • id string Required

      Format should match the following pattern: purchase_[a-zA-Z0-9]*.

    • files array[string | object]

      Contains for example the certificate document if it was requested during the purchase.

      One of:
      string-1 string File object

      Format should match the following pattern: file_[A-Za-z0-9]*.

    • payment_method string Required

      Mode of payment. The batch settlement means SQUAKE will invoice you regularly for a batch of purchases. The checkout page is SQUAKEs self-fulfillment solution where end-customers can purchase a product directly from SQUAKE as the merchant of record.

      Values are batch_settlement or stripe. Default value is batch_settlement.

    • state string Required

      Values are reserved, confirmed, invoiced, settled, certificates_confirmed, certificates_retired, payment_initiated, canceled, voided, refunded, or payment_aborted.

    • metadata object

      A set of key-value pairs of yours that helps you link this record in your system. Never displayed to users.

      Additional properties are allowed.

    • checkout_page object

      Present if the payment method is stripe, meaning self-fulfillment by the customer on SQUAKEs payment page.

      Additional properties are allowed.

      Hide checkout_page attributes Show checkout_page attributes object
      • url string(uri)

        Send your customer to this URL to finalise the purchase. This link is not the stateless payment link, but bound to this purchase.

      • return_url string(uri)

        If the customer does not exit the browser after the purchase, on success, SQUAKE will redirect the customer to this link.

    • carbon_quantity number Required
    • carbon_unit string Required

      SQUAKE uses The International System of Units (SI), commonly referred to as "metric system".

      Values are tonne, kilogram, or gram.

    • total integer Required
    • currency string Required

      3-letter ISO 4217 alpha code of the currency.

      Minimum length is 3, maximum length is 3. Format should match the following pattern: ^[A-Z]{3}$. Values are AED, AMD, ARS, AUD, AZN, BAM, BGN, BHD, BRL, CAD, CHF, CLP, CNY, COP, CRC, CZK, DKK, DZD, EGP, ETB, EUR, GBP, GEL, HKD, HUF, IDR, INR, ISK, JMD, JOD, JPY, KES, KRW, KWD, KZT, LKR, LYD, MAD, MUR, MXN, MYR, NOK, NZD, OMR, PHP, PKR, PLN, QAR, RSD, RUB, SAR, SEK, SGD, SYP, THB, TND, TRY, TTD, TWD, UAH, USD, VND, XAF, XOF, or ZAR. Default value is EUR.

    • external_reference string

      Unique identifier from your system; used as idempotency when creating this resource.
  • 400 application/json

    Example response

    Hide headers attribute Show headers attribute
    • SQUAKE-Request-Id string

      Unique identifier linked to this API request. If you need to contact us regarding a specific request, providing the request identifier helps the resolution process.

      Format should match the following pattern: req_[a-zA-Z0-9-]+.

    Hide response attributes Show response attributes object
    • code string Required

      An application-specific error code, expressed as a string value.

      Values are field_validation_error, server_error, not_authorized, not_found, invalid_methodology, or invalid_type.

    • detail string

      A human-readable explanation specific to this occurrence of the problem. Like title, this field's value can be localized.

    • source object

      An object containing references to the primary source of the error

      Additional properties are allowed.

      Hide source attributes Show source attributes object
  • 401 application/json

    Example response

    Hide headers attribute Show headers attribute
    • SQUAKE-Request-Id string

      Unique identifier linked to this API request. If you need to contact us regarding a specific request, providing the request identifier helps the resolution process.

      Format should match the following pattern: req_[a-zA-Z0-9-]+.

    Hide response attributes Show response attributes object
    • code string Required

      An application-specific error code, expressed as a string value.

      Values are field_validation_error, server_error, not_authorized, not_found, invalid_methodology, or invalid_type.

    • detail string

      A human-readable explanation specific to this occurrence of the problem. Like title, this field's value can be localized.

    • source object

      An object containing references to the primary source of the error

      Additional properties are allowed.

      Hide source attributes Show source attributes object
POST /v2/purchases 
curl \
 -X POST https://api.squake.earth/v2/purchases \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"pricing":"string","confirmation_document":{"full_name":"string","address":{"city":"string","country":"DE","line1":"string","line2":"string","postal_code":"string","state":"string"},"email":"hello@example.com","on_behalf_of":{"full_name":"string","address":{"city":"string","country":"DE","line1":"string","line2":"string","postal_code":"string","state":"string"}},"locale":"en"},"certificate_document":{"full_name":"string","address":{"city":"string","country":"DE","line1":"string","line2":"string","postal_code":"string","state":"string"},"email":"hello@example.com","flags":["with_attribution"],"locale":"en"},"expand":["files"],"metadata":{},"external_reference":"string"}'
Request examples 
{
  "pricing": "string",
  "confirmation_document": {
    "full_name": "string",
    "address": {
      "city": "string",
      "country": "DE",
      "line1": "string",
      "line2": "string",
      "postal_code": "string",
      "state": "string"
    },
    "email": "hello@example.com",
    "on_behalf_of": {
      "full_name": "string",
      "address": {
        "city": "string",
        "country": "DE",
        "line1": "string",
        "line2": "string",
        "postal_code": "string",
        "state": "string"
      }
    },
    "locale": "en"
  },
  "certificate_document": {
    "full_name": "string",
    "address": {
      "city": "string",
      "country": "DE",
      "line1": "string",
      "line2": "string",
      "postal_code": "string",
      "state": "string"
    },
    "email": "hello@example.com",
    "flags": [
      "with_attribution"
    ],
    "locale": "en"
  },
  "expand": [
    "files"
  ],
  "metadata": {},
  "external_reference": "string"
}
Response examples (201) 
# Headers

# Payload
{
  "id": "purchase_sd234asdfl23",
  "files": [
    "file_34sdfgJH9df4g35"
  ],
  "payment_method": "batch_settlement",
  "state": "reserved",
  "metadata": {},
  "checkout_page": {
    "url": "https://checkout.squake.earth",
    "return_url": "https://example.com"
  },
  "carbon_quantity": 42.0,
  "carbon_unit": "tonne",
  "total": 42,
  "currency": "EUR",
  "external_reference": "string"
}
Response examples (400) 
# Headers
SQUAKE-Request-Id: req_70394c00-728e-4d70-90bc-2b589c9ebdf8

# Payload
[
  {
    "code": "field_validation_error",
    "detail": "string",
    "source": {
      "id": "string",
      "attribute": "string",
      "model": "string"
    }
  }
]
Response examples (401) 
# Headers
SQUAKE-Request-Id: req_70394c00-728e-4d70-90bc-2b589c9ebdf8

# Payload
[
  {
    "code": "field_validation_error",
    "detail": "string",
    "source": {
      "id": "string",
      "attribute": "string",
      "model": "string"
    }
  }
]