Checkout sends Messages to provide feedback about events.

To receive Messages from Checkout, pass the onInfo, onWarn, or onError message handlers with the checkoutFlow, paymentFlow, or expressPayment.init methods when initializing Checkout.

Message structure

Checkout Messages are JSON objects with the following common fields. In addition to these common fields, some Messages also contain a payload field with data about the event.
code​
String​

Message code for the event.

severity​
String​
Severity level of the event. Can be info, warn, or error.
message​
String​

Human-readable description of the event.

correlationId​
String​

Unique identifier of the event.

Example Message of severiry level 'error' with payloadjson
{
  "severity": "error",
  "code": "project_deactivated",
  "message": "Project {projectKey} is deactivated.",
  "payload": {
    "project": {
      "key": "{projectKey}"
    }
  },
  "correlationId": "spa/commercetools-checkout/1729263187262/565301612087128"
}
Example Message of severiry level 'info' with payloadjson
{
  "severity": "info",
  "code": "order_created",
  "message": "Order {orderId} created.",
  "payload": {
    "order": {
      "id": "{orderId}"
    }
  },
  "correlationId": "spa/commercetools-checkout/1729263187262/565301612087128"
}

Message types

Application Messages

Application Deactivated

Generated when the requested Application is deactivated. Activate the Application in the Merchant Center to continue.
code​
String​
"application_disabled"
severity​
String​
error
message​
String​
Application {applicationKey} for {projectKey} is disabled.
correlationId​
String​

Unique identifier of the event.

payload​
Object​
Contains the project and application objects with the related key property.

Cart Messages

Cart Empty

Generated when the Cart for the current checkout is empty. The Cart must contain at least one Line Item.
code​
String​
"cart_empty"
severity​
String​
error
message​
String​
Cart {cartId} is empty.
correlationId​
String​

Unique identifier of the event.

payload​
Object​
Contains the cart object with the id property.

Cart Emptied During Checkout

Generated when the Cart was emptied during the checkout process. It is not possible to recover from this, the customer must restart the checkout process.
code​
String​
"cart_emptied_during_checkout"
severity​
String​
error
message​
String​
Cart {cartId} was emptied during checkout.
correlationId​
String​

Unique identifier of the event.

payload​
Object​
Contains the cart object with the id property.

Cart Not Found

Generated when the Cart is not found. To start the checkout process, a valid Cart with at least one Line Item is required.
code​
String​
"cart_not_found"
severity​
String​
error
message​
String​
Cart for {projectKey} and session {sessionId} not found.
correlationId​
String​

Unique identifier of the event.

payload​
Object​
Contains the project and session objects with the related key and id properties.

Non Orderable Cart Error

Generated when the Order could not be created due to inconsistencies in the Cart.
code​
String​
"non_orderable_cart_error"
severity​
String​
error
message​
String​

This cart is not orderable.

correlationId​
String​

Unique identifier of the event.

payload​
Object​
Contains the cart object with the id and errors properties.

Cart With Existing Payment

Generated when trying to add a Payment to a Cart that already references an approved Payment.
code​
String​
"cart_with_existing_payment"
severity​
String​
error
message​
String​

Cart with existing approved payment.

correlationId​
String​

Unique identifier of the event.

payload​
Object​
Contains the cart object with the id property.

Unsupported Country

Generated when the country of the shipping address and/or billing address associated with the Cart does not match the countries set for the Application.
code​
String​
"unsupported_country"
severity​
String​
error
message​
String​
Cart {cartId} has unsupported country.
correlationId​
String​

Unique identifier of the event.

payload​
Object​
Contains the cart object with the id property, shippingCountry, billingCountry, and the supportedCountries array.

Shipping Address Missing Error

Generated when the shipping address is missing for the given Cart.

code​
String​
"shipping_address_missing"
severity​
String​
error
message​
String​
The shippingAddress field is missing for cart {cartId}.
correlationId​
String​

Unique identifier of the event.

payload​
Object​
Contains the cart object with the id property.

Shipping Address Does Not Match Cart

Generated when the selected Shipping Method does not match the Cart anymore.

code​
String​
"shipping_method_does_not_match_cart"
severity​
String​
info
message​
String​

Selected shipping method no longer matches cart.

correlationId​
String​

Unique identifier of the event.

Set Shipping Address Error

Generated when the Cart cannot be updated with the shipping address.
code​
String​
"set_shipping_address_error"
severity​
String​
error
message​
String​

Error setting shipping address.

correlationId​
String​

Unique identifier of the event.

payload​
Object​
Contains the errors array of objects, with the related code and message properties.

Checkout Messages

Checkout Loaded

Generated when Checkout is loaded and waiting for the configuration properties to be passed with the checkoutFlow or paymentFlow method.
code​
String​
"checkout_loaded"
severity​
String​
info
message​
String​

Checkout loaded.

correlationId​
String​

Unique identifier of the event.

Checkout Started

Generated when the configuration properties are passed successfully with the checkoutFlow or paymentFlow method and the checkout process starts.
code​
String​
"checkout_started"
severity​
String​
info
message​
String​

Checkout started.

correlationId​
String​

Unique identifier of the event.

Checkout Cancelled

Generated when the customer cancels the checkout process.

code​
String​
"checkout_cancelled"
severity​
String​
info
message​
String​

Checkout cancelled.

correlationId​
String​

Unique identifier of the event.

Checkout Completed

Generated when the customer completes the checkout process.

code​
String​
"checkout_completed"
severity​
String​
info
message​
String​
Checkout for {orderId} completed.
correlationId​
String​

Unique identifier of the event.

payload​
Object​
Contains the order object with the id property.

Express Payments Messages

Express Payment Started

Generated when the customer clicks an Express Payments button and the Express Payment process starts.

code​
String​
"express_payment_started"
severity​
String​
info
message​
String​

Express payment started.

correlationId​
String​

Unique identifier of the event.

payload​
Object​
Contains the integration object with the type property.

Express Payment Cancelled

Generated when the customer cancels the Express Payments process.

code​
String​
"express_payment_cancelled"
severity​
String​
info
message​
String​

Express Payments process cancelled.

correlationId​
String​

Unique identifier of the event.

payload​
Object​
Contains the paymentReference and method object with the type property (if available).

Express Payment Completed

Generated when the Express Payments process is completed.

code​
String​
"express_payment_completed"
severity​
String​
info
message​
String​
Express payment for {orderId} completed.
correlationId​
String​

Unique identifier of the event.

payload​
Object​
Contains the order object with the id property.

Express Payment Failed

Generated when the Express Payments process fails.

code​
String​
"express_payment_failed"
severity​
String​
error
message​
String​

Express payment failed.

correlationId​
String​

Unique identifier of the event.

payload​
Object​
Contains the paymentReference, error, and method object with the type property (if available).

Express Container Not Found

Generated when the container element specified in the expressId option is not found in the DOM.
code​
String​
"express_container_not_found"
severity​
String​
error
message​
String​

Express container not found.

correlationId​
String​

Unique identifier of the event.

payload​
Object​
Contains the id of the container that was not found.

No Express Payment Integrations

Generated when no express payment integrations are configured.

code​
String​
"no_express_payment_integrations"
severity​
String​
error
message​
String​

There are no Express Payments integrations configured.

correlationId​
String​

Unique identifier of the event.

Express Multiple Containers Found

Generated when multiple elements with the data-ctc-express attribute are found without an expressId specified. Use the expressId option to specify which container to use.
code​
String​
"express_multiple_containers_found"
severity​
String​
error
message​
String​

Multiple elements with data-ctc-express attribute found. Use expressId to specify which container to use.

correlationId​
String​

Unique identifier of the event.

payload​
Object​
Contains the count property indicating the number of containers found.

Express Payment Interrupted

Generated when the Express Payments process is interrupted by the seller's callback.

code​
String​
"express_payment_interrupted"
severity​
String​
info
message​
String​

Express Payments process was interrupted by a callback.

correlationId​
String​

Unique identifier of the event.

Express Payment Integration Not Available

Generated when a requested Express Payments integration is not available. This can happen when using mountMethod() with a payment method that is not configured or not available for the current session.
code​
String​
"express_payment_integration_not_available"
severity​
String​
warn
message​
String​

Express Payments integration not available.

correlationId​
String​

Unique identifier of the event.

payload​
Object​
Contains the integration object with the type property indicating the requested payment integration type, and availableMethods array listing the available payment methods.

Configuration Messages

Init Error

Generated when an error occurs during Checkout's initialization.

code​
String​
"init_error"
severity​
String​
error
message​
String​

Error during initialization.

correlationId​
String​

Unique identifier of the event.

Init Timeout

Generated when Checkout does not receive the configuration properties with the checkoutFlow or paymentFlow method on time.
code​
String​
"init_timeout"
severity​
String​
error
message​
String​

Timeout error, no init message received.

correlationId​
String​

Unique identifier of the event.

Invalid Locale

Generated when the provided locale is invalid.

code​
String​
"invalid_locale"
severity​
String​
warn
message​
String​
The provided {locale} is invalid.
correlationId​
String​

Unique identifier of the event.

payload​
Object​

Contains the provided locale string, the related locale field (language or currency), and the used fallback one.

Invalid Mode

Generated when the Application does not support the requested Checkout mode.
code​
String​
"invalid_mode"
severity​
String​
info
message​
String​
{mode} mode requires an application with mode type {modeTypeRequested}. Current mode {modeTypeReceived}.
correlationId​
String​

Unique identifier of the event.

Expired Session

Generated when the Checkout Session is expired.
code​
String​
"expired_session"
severity​
String​
error
message​
String​

Session is expired.

correlationId​
String​

Unique identifier of the event.

Failed To Refresh Session

Generated when the Checkout Session fails to refresh.
code​
String​
"failed_to_refresh_session"
severity​
String​
error
message​
String​

Failed to refresh session.

correlationId​
String​

Unique identifier of the event.

Bad Input Data

Generated when the Checkout properties contains invalid fields.
code​
String​
"invalid_fields"
severity​
String​
error
message​
String​

Some fields are invalid.

correlationId​
String​

Unique identifier of the event.

payload​
Object​
Contains the invalidFields array of objects with the related schema, path, value and message properties.

No Shipping Methods

Generated when no Shipping Method is available for the shipping address of the Cart. This may indicate an incomplete configuration.
code​
String​
"no_shipping_methods"
severity​
String​
error
message​
String​

There are no shipping methods matching cart.

correlationId​
String​

Unique identifier of the event.

payload​
Object​
Contains the cart object with the id property.

Shipping Method Selected

Generated when the customer selects a Shipping Method that is different from the default option.

code​
String​
"shipping_method_selected"
severity​
String​
info
message​
String​

Shipping Method selected.

correlationId​
String​

Unique identifier of the event.

payload​
Object​
Contains the method object with the name and id properties.

Shipping Method Selection Confirmation

Generated when the customer selects a Shipping Method and moves to the next step of the checkout process.

code​
String​
"shipping_method_selection_confirmation"
severity​
String​
info
message​
String​

Shipping Method selection confirmed.

correlationId​
String​

Unique identifier of the event.

payload​
Object​
Contains the method object with the name and id properties.

Unavailable Locale

Generated when the provided locale is not available for localization. The localization falls back to English.
code​
String​
"unavailable_locale"
severity​
String​
warn
message​
String​
The provided locale {locale} is not available for translated definitions.
correlationId​
String​

Unique identifier of the event.

payload​
Object​
Contains the locale and the fallback properties.

Deprecated Fields

Generated when the Checkout properties contains one or more deprecated fields.
code​
String​
"deprecated_fields"
severity​
String​
warn
message​
String​

Some fields are deprecated.

correlationId​
String​

Unique identifier of the event.

payload​
Object​
Contains the deprecatedFields array.

Updated Fields

Generated when some fields provided in the Checkout initialization request are invalid and have been updated to match our schema. An array of updates will be provided with a sequence of edits used to transform an invalid value into a valid one.

code​
String​
"updated_fields"
severity​
String​
warn
message​
String​

Some fields are invalid and have been updated.

correlationId​
String​

Unique identifier of the event.

payload​
Object​

Contains two arrays:

  • invalidFields contains a list of invalid fields with the related schema, path, value and message properties.
  • updatedFields contains the updated fields with its related type, path and value properties, where type can be update|insert|delete.

Discount Code Messages

Add Discount Code Error

Generated when there was an error adding a Discount Code.

code​
String​
"add_discount_code_error"
severity​
String​
error
message​
String​

Error adding discount code.

correlationId​
String​

Unique identifier of the event.

payload​
Object​
Contains the error object.

Remove Discount Code Error

Generated when there was an error removing the Discount Code.
code​
String​
"remove_discount_code_error"
severity​
String​
error
message​
String​

Error removing discount code.

correlationId​
String​

Unique identifier of the event.

payload​
Object​
Contains the error object.

Discount Not Applicable

Generated when the Discount Code is not applicable for the current Cart.
code​
String​
"discount_code_not_applicable"
severity​
String​
info
message​
String​

Discount code not applicable.

correlationId​
String​

Unique identifier of the event.

payload​
Object​
Contains the cartId and discountCode properties.

Not Applicable Discount Code Removed

Generated when using the paymentFlow method and Checkout removes a Discount Code from the Cart because it does not apply to the Cart. Checkout removes the Discount Code to avoid an order creation error when converting the Cart to an Order.
code​
String​
"not_applicable_discount_code_removed"
severity​
String​
warn
message​
String​

Not applicable discount code removed.

correlationId​
String​

Unique identifier of the event.

payload​
Object​
Contains the cartId and discountCode properties.

Gift card Messages

Gift Card Balance Started

Generated when the customer enters the gift card's code for the payment, and Checkout initiates the retrieving of the gift card's balance.

code​
String​
"gift_card_balance_started"
severity​
String​
info
message​
String​

Gift card balance started.

correlationId​
String​

Unique identifier of the event.

Gift Card Balance Success

Generated when Checkout successfully retrieves a gift card's balance.

code​
String​
"gift_card_balance_success"
severity​
String​
info
message​
String​

Gift card balance started.

correlationId​
String​

Unique identifier of the event.

payload​
Object​
Contains the amount and isBalanceSufficient properties.

Gift Card Balance Error

Generated when an error occurs while retrieving the balance of a gift card.

code​
String​
"gift_card_balance_error"
severity​
String​
error
message​
String​

Gift card balance failed.

correlationId​
String​

Unique identifier of the event.

Gift Card Balance Removed

Generated when the customer removes a gift card's balance that was initially applied as a payment integration.

code​
String​
"gift_card_balance_removed"
severity​
String​
info
message​
String​

Gift card balance removed.

correlationId​
String​

Unique identifier of the event.

Gift Card Redeem Started

Generated when the customer confirms the payment by gift card and Checkout initiates the redemption of the gift card's balance.

code​
String​
"gift_card_redeem_started"
severity​
String​
info
message​
String​

Gift card redeem started.

correlationId​
String​

Unique identifier of the event.

Gift Card Redeem Success

Generated when the redemption of a gift card's balance is successful.

code​
String​
"gift_card_redeem_success"
severity​
String​
info
message​
String​

Gift card redeem success.

correlationId​
String​

Unique identifier of the event.

Gift Card Redeem Error

Generated when the redemption of a gift card's balance fails.

code​
String​
"gift_card_redeem_error"
severity​
String​
error
message​
String​

Gift card redeem failed.

correlationId​
String​

Unique identifier of the event.

Order Messages

Order Created

Generated when an Order is created after a successful checkout process.
code​
String​
"order_created"
severity​
String​
info
message​
String​
Order {orderId} created.
correlationId​
String​

Unique identifier of the event.

payload​
Object​
Contains the order object with the id property.

Order Creation Error

Generated when an Order that references an approved Payment cannot be created.
code​
String​
"order_creation_error"
severity​
String​
error
message​
String​

Order creation failed with approved payment.

correlationId​
String​

Unique identifier of the event.

payload​
Object​
Contains paymentReference, sessionId, and the errors array of objects, with the related code and message properties.

Order Verification Started

Generated when Checkout starts verifying the Order.
code​
String​
"order_verification_started"
severity​
String​
info
message​
String​

Order verification started.

correlationId​
String​

Unique identifier of the event.

Order Verification Timeout

Generated when the verification of the Order times out.
code​
String​
"order_verification_timeout"
severity​
String​
error
message​
String​

Order verification timeout.

correlationId​
String​

Unique identifier of the event.

Order Verification Retry Error

Generated when retrying the verification of the Order results in an error.
code​
String​
"order_verification_retry_error"
severity​
String​
error
message​
String​

Order verification retry error.

correlationId​
String​

Unique identifier of the event.

payload​
Object​
Contains the error property that can be either orderReferenceNotAvailable or orderVerificationOngoing.

Payments Messages

Connector Error

Generated when the Connector triggers an error.
code​
String​
"connector_error"
severity​
String​
error
message​
String​

Connector error.

correlationId​
String​

Unique identifier of the event.

payload​
Object​
Contains the connector object with the id property and optional error, message, and data properties.

Payment Integrations Received

Generated when Checkout receives and loads the payment integrations configured for the Application.

code​
String​
"payment_integrations_received"
severity​
String​
info
message​
String​

Payment integrations received.

correlationId​
String​

Unique identifier of the event.

payload​
Object​
Contains the paymentIntegrations array of objects with the type and connectorId properties.

Multiple Payment Integration Containers

Generated when multiple containers for vendor payment buttons are found.
code​
String​
"multiple_vendor_button_containers"
severity​
String​
warn
message​
String​

Multiple vendor button containers detected, this may cause issues.

correlationId​
String​

Unique identifier of the event.

Payment Integration Not Available

Generated when there is an error with the selected payment integration and the payment integration is unavailable.

code​
String​
"payment_integration_not_available"
severity​
String​
warn
message​
String​

Payment integration not available.

correlationId​
String​

Unique identifier of the event.

payload​
Object​
Contains the method object with the type, id, and connectorId properties.

No Payment Integrations

Generated when no payment integration is set up for an Application. Add at least one Payment integration to the Application in the Merchant Center.
code​
String​
"no_payment_integrations"
severity​
String​
error
message​
String​

There are no payment integrations configured.

correlationId​
String​

Unique identifier of the event.

Payment Integration Loading

Generated when the selected payment integration is loading.

code​
String​
"payment_integration_loading"
severity​
String​
info
message​
String​

Payment integration loading.

correlationId​
String​

Unique identifier of the event.

payload​
Object​
Contains the integration object with the type and connectorId properties.

Payment Integration Loading Error

Generated when the loading of the selected payment integration fails.

code​
String​
"payment_integration_loading_error"
severity​
String​
error
message​
String​

Payment integration loading failed.

correlationId​
String​

Unique identifier of the event.

payload​
Object​
Contains an error object and the integration object with the type and connectorId properties.

Payment Integration Loaded

Generated when the selected payment integration is loaded.

code​
String​
"payment_integration_loaded"
severity​
String​
info
message​
String​

Payment integration loaded.

correlationId​
String​

Unique identifier of the event.

payload​
Object​
Contains the integration object with the type and connectorId properties.

Payment Integration Selected

Generated when the customer selects the payment integration.

code​
String​
"payment_integration_selected"
severity​
String​
info
message​
String​

Payment integration selected.

correlationId​
String​

Unique identifier of the event.

payload​
Object​
Contains the integration object with the type and hasVendorButton properties.

Payment Integration Selection Confirmation

Generated when the customer has entered the payment integration information and moves to the next step.

code​
String​
"payment_integration_selection_confirmation"
severity​
String​
info
message​
String​

Payment integration selected.

correlationId​
String​

Unique identifier of the event.

payload​
Object​
Contains the integration object with the type and hasVendorButton properties.

Payment Integration Selection Confirmation Failed

Generated when the selection of the payment integration by the customer is not successful.

code​
String​
"payment_integration_selection_confirmation_failed"
severity​
String​
info
message​
String​

Payment integration selection failed.

correlationId​
String​

Unique identifier of the event.

payload​
Object​
Contains the integration object with the type property.

Error Loading All Payment Integrations

Generated when the loading of all the payment integrations have failed.

code​
String​
"error_loading_all_payment_integrations"
severity​
String​
error
message​
String​

Error loading all payment integrations.

correlationId​
String​

Unique identifier of the event.

Payment Started

Generated when the payment starts.

code​
String​
"payment_started"
severity​
String​
info
message​
String​

Payment started.

correlationId​
String​

Unique identifier of the event.

payload​
Object​
Contains the integration object with the type property.

Payment Failed

Generated when the payment fails.

code​
String​
"payment_failed"
severity​
String​
error
message​
String​

Payment failed.

correlationId​
String​

Unique identifier of the event.

payload​

Contains the reference data of a Payment.

Payment Cancelled

Generated when the customer cancels the payment (for example, by closing the browser's window).

code​
String​
"payment_cancelled"
severity​
String​
info
message​
String​

Payment cancelled.

correlationId​
String​

Unique identifier of the event.

payload​

Contains the reference data of a Payment.

Payment Validation Failed

Generated when Checkout and the payment service provider (PSP) do not validate the payment information entered by the customer.

code​
String​
"payment_validation_failed"
severity​
String​
info
message​
String​

Payment validation failed.

correlationId​
String​

Unique identifier of the event.

payload​

Contains the reference data of a Payment.

Payment Validation Passed

Generated when Checkout and the payment service provider (PSP) validate the payment information entered by the customer.

code​
String​
"payment_validation_passed"
severity​
String​
info
message​
String​

Payment validation passed.

correlationId​
String​

Unique identifier of the event.

Payment Validation Started

Generated when the validation of the payment information entered by the customer starts.

code​
String​
"payment_validation_started"
severity​
String​
info
message​
String​

Payment validation started.

correlationId​
String​

Unique identifier of the event.

External Terms And Conditions Pending

Generated in Payment Only mode when the customer hasn't accepted the terms and conditions yet.
code​
String​
"external_terms_and_conditions_pending"
severity​
String​
info
message​
String​

External terms and conditions pending.

correlationId​
String​

Unique identifier of the event.

Project Messages

Project Is Deactivated

code​
String​
"project_deactivated"
severity​
String​
error
message​
String​
Project {projectKey} is deactivated.
correlationId​
String​

Unique identifier of the event.

payload​
Object​
Contains the project object with the key property.