# Create a Purchase 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 from the pricing endpoint to finalize the purchase using SQUAKE's provided checkout page. ### Lifecycle #### When purchasing via API (this endpoint) * : A successful purchase starts in the state "reserved"; SQUAKE registered your purchase and reserved carbon credits accordingly. * : SQUAKE offers 14 days to cancel a purchase worry-free. This is a terminal state. * : The refundable period has passed. If you need to cancel the purchase beyond this point, please request a refund on the refunds endpoint. * : Without further action, a purchase is invoiced after the grace period and transitions to "invoiced". #### When purchasing via the checkout page * : the end customer entered the payment flow on the checkout page * : 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. * : 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 * : SQUAKE has received the payment. * : a refund request was successfully processed. This is a terminal state. * : all certificates for the carbon credits have been confirmed from all project partners related to the purchase. * : all certificates have been retired in the corresponding registries. This is a terminal state. Endpoint: POST /v2/purchases Security: Bearer-Auth ## Request fields (application/json): - `pricing` (string, required) The ID from the pricing endpoint - `confirmation_document` (object) - `confirmation_document.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). - `confirmation_document.address` (object, required) Address of a legal entity. Some (legal) documets require a full address to be given, e.g. an invoice. - `confirmation_document.address.city` (string, required) City, town, village,... - `confirmation_document.address.country` (string, required) Two-letter or three-letter code as defined in ISO 3166-1 alpha-2 and alpha-3 respectively. - `confirmation_document.address.line1` (string, required) street, post box, company name, ... - `confirmation_document.address.line2` (string) suite, apartment number, ... - `confirmation_document.address.postal_code` (string, required) ZIP or postal code - `confirmation_document.address.state` (string) County, Province, Region, State,... - `confirmation_document.email` (string) 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. - `confirmation_document.on_behalf_of` (object) If you make a compensation on behalf on another entity or person. This will be printed on the issued document. - `confirmation_document.on_behalf_of.full_name` (string, required) - `confirmation_document.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. Enum: "de", "en", "es", "fr", "hi", "it", "ja", "pt", "pt-BR", "zh-CN" - `certificate_document` (object) - `certificate_document.email` (string) 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. - `certificate_document.flags` (array) If "with_attribution" is sent, your name will be mentioned on the certificate; e.g. "(..) enabled by ${your_name} (..)". - `expand` (array) Receive either the file-id, or the file-object of a requested document. If omitted, only IDs are returned. - `metadata` (object) A set of key-value pairs of yours that helps you link this record in your system. Never displayed to users. - `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. ## Response 201 fields (application/json): - `id` (string, required) - `files` (array) Contains for example the certificate document if it was requested during the purchase. - `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. Enum: "batch_settlement", "stripe" - `state` (string, required) Enum: "reserved", "confirmed", "invoiced", "settled", "certificates_confirmed", "certificates_retired", "payment_initiated", "canceled", "voided", "refunded", "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. - `checkout_page` (object) Present if the payment method is , meaning self-fulfillment by the customer on SQUAKEs payment page. - `checkout_page.url` (string) Send your customer to this URL to finalise the purchase. This link is not the stateless payment link, but bound to this purchase. - `checkout_page.return_url` (string) 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". Enum: "tonne", "kilogram", "gram" - `total` (integer, required) - `currency` (string, required) 3-letter ISO 4217 alpha code of the currency. Enum: "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", "ZAR" - `external_reference` (string) Unique identifier from your system; used as idempotency when creating this resource. - `cancellable_until` (string) The date until which purchase can be cancelled Example: "2025-01-01T15:00:00+00:00" ## Response 400 fields (application/json): - `errors` (array) - `errors.code` (string, required) An application-specific error code, expressed as a string value. Enum: "field_validation_error", "server_error", "not_authorized", "not_found", "invalid_methodology", "invalid_type" - `errors.detail` (string) A human-readable explanation specific to this occurrence of the problem. Like title, this field's value can be localized. - `errors.source` (object) An object containing references to the primary source of the error - `errors.source.id` (string) - `errors.source.attribute` (string, required) - `errors.source.model` (string) ## Response 401 fields (application/json): - `errors` (array) - `errors.code` (string, required) An application-specific error code, expressed as a string value. Enum: "field_validation_error", "server_error", "not_authorized", "not_found", "invalid_methodology", "invalid_type" - `errors.detail` (string) A human-readable explanation specific to this occurrence of the problem. Like title, this field's value can be localized. - `errors.source` (object) An object containing references to the primary source of the error - `errors.source.id` (string) - `errors.source.attribute` (string, required) - `errors.source.model` (string) ## Response 403 fields (application/json): - `errors` (array) - `errors.code` (string, required) An application-specific error code, expressed as a string value. Enum: "field_validation_error", "server_error", "not_authorized", "not_found", "invalid_methodology", "invalid_type" - `errors.detail` (string) A human-readable explanation specific to this occurrence of the problem. Like title, this field's value can be localized. - `errors.source` (object) An object containing references to the primary source of the error - `errors.source.id` (string) - `errors.source.attribute` (string, required) - `errors.source.model` (string)