Update a Purchase

PATCH /v2/purchases/{id}
Bearer auth

Update a purchase placed earlier.

You can use the external_reference as ID as well for the lookup; i.e. your unique identifier.

Omitted keys will not affect any present data.

To remove optional data you must explicitly set the value to null

Path parameters

  • id string Required
application/json

Body

  • 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

      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

    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

Responses

  • 200 application/json

    OK

    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.

    • cancellable_until string(date-time)

      The date until which purchase can be cancelled
  • 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
  • 404 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
PATCH /v2/purchases/{id} 
curl \
 --request PATCH https://api.squake.earth/v2/purchases/{id} \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{"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 
{
  "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 (200) 
# 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",
  "cancellable_until": "2025-01-01T15:00:00+00:00"
}
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"
    }
  }
]
Response examples (404) 
# Headers
SQUAKE-Request-Id: req_70394c00-728e-4d70-90bc-2b589c9ebdf8

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