Customize the texts and labels of your checkout experience with Checkout.
Checkout lets you customize the texts and labels displayed at every step of your checkout flow.
Whether it's adjusting the text of a message or a field label, you have full control of the content. You can do this by passing the
languageOverrides configuration property with the checkoutFlow or paymentFlow methods when initializing Checkout.Text customization example
The following example customizes the title and description of the error message that appears for the English locale when the checkout is initialized with an empty cart.
import { checkoutFlow } from '@commercetools/checkout-browser-sdk';
checkoutFlow({
projectKey: '{projectKey}',
region: '{region}',
sessionId: '{sessionId}',
locale: 'en',
languageOverrides: {
error: {
emptyCart: {
title: 'The cart is empty',
message:
'Please add at least one product to your cart before proceeding with the checkout.',
},
},
},
});
Labels customization example
The following example customizes the labels of the
email, phone, and city address fields for the German locale. The other fields will not change.import { checkoutFlow } from '@commercetools/checkout-browser-sdk';
checkoutFlow({
projectKey: '{projectKey}',
region: '{region}',
sessionId: '{sessionId}',
locale: 'de',
languageOverrides: {
address: {
email: 'E-Mail-Addresse',
phone: 'Optionale Telefonnummer',
city: 'Stadt',
},
},
});
Customizable properties
Following are the properties that you can add to the
languageOverrides object to customize the texts and labels of your checkout experience. To customize them, you must provide the corresponding object, the key, and the desired value in the languageOverrides object, like in the preceding examples.Some values contain dynamic parameters that are rendered according to your Checkout configuration. For example, the property
When customizing content, you must keep the dynamic parameters that are present in the default values. For example, if you want to customize the text from Pay with PayPal to Carry out payment with PayPal, the property must be set to
"payWith": "Pay with {paymentMethodType}" appears as Pay with PayPal if you set PayPal as a payment integration. When customizing content, you must keep the dynamic parameters that are present in the default values. For example, if you want to customize the text from Pay with PayPal to Carry out payment with PayPal, the property must be set to
"payWith": "Carry out payment with {paymentMethodType}".You can customize the text and labels of payment integrations only if they are rendered via the web components Payment Integration Type.
Checkout supports only the following properties and eventual custom payment integrations properties. Any other property declared will be ignored.
Dynamic parameters must have single curly braces. Otherwise, the related dynamic content is not rendered.
{
"address": {
"email": "Email Address",
"phone": "Phone number",
"shippingAddress": "Shipping Address",
"firstName": "First Name",
"lastName": "Last Name",
"streetName": "Street address",
"streetNumber": "Street number",
"state": "State",
"additionalStreetInfo": "Apt, suite, building, etc.",
"postalCode": "ZIP code",
"city": "City/Town",
"country": "Country",
"continue": "Continue",
"editShippingAddress": "Edit shipping address",
"saveShippingAddress": "Save change of shipping address",
"cancelShippingAddress": "Cancel change of shipping address",
"editBillingAddress": "Edit billing address",
"saveBillingAddress": "Save change of billing address",
"cancelBillingAddress": "Cancel change of billing address",
"editAddress": "Edit address",
"requiredFields": "Required Fields",
"addAdditionalStreetInfo": "Add apt, suite, building, etc. (optional)",
"sameBillingAddress": "Billing address same as shipping address",
"sameBillingAddressCompletedForm": "Same as shipping address",
"billingAddress": "Billing address",
"company": "Company name",
"saveAndContinue": "Save & Continue",
"title": "Address",
"technicalError": "We have a technical issue with the provided address. Please update your address to continue.",
"copyShippingValues": "Copy shipping values",
"heading": {
"shipping": "Shipping",
"billing": "Billing"
},
"validations": {
"firstName": {
"required": "Required field"
},
"lastName": {
"required": "Required field"
},
"email": {
"required": "Required field",
"pattern": "Invalid email address"
},
"country": {
"required": "Required field"
},
"streetName": {
"required": "Required field"
},
"streetNumber": {
"required": "Required field"
},
"postalCode": {
"required": "Required field",
"pattern": "Invalid ZIP code"
},
"city": {
"required": "Required field"
},
"state": {
"required": "Required field"
},
"phone": {
"maxLength": "Invalid phone number",
"pattern": "Invalid phone number"
}
},
"a11y": {
"edit": "Edit shipping and billing address",
"save": "Save shipping and billing address, continue with delivery",
"cancel": "Cancel change of shipping and billing address"
}
},
"delivery": {
"heading": "Delivery",
"shippingNotAvailableError": "We have a technical issue with the delivery option. Try again now or come back later.",
"shippingNotMatches": "Your previously selected delivery method is no longer suitable for your current cart. Please select another delivery method:",
"freeFrom": "free from",
"button": {
"save": "Save Changes",
"continue": "Continue",
"saveAndContinue": "Save & Continue",
"tryAgain": "Try again"
},
"a11y": {
"legend": "Select a shipping method for your order",
"tryAgain": "Try again to obtain shipping methods",
"button": {
"save": "Save {deliveryType} and continue with payment",
"edit": "Edit delivery type",
"cancel": "Cancel change of delivery type {deliveryType}"
}
}
},
"payment": {
"heading": "Payment",
"paymentDetails": "Payment details",
"subheader": "Select your payment method.",
"continueButton": "Continue to review",
"paymentMethodError": "There is a problem with this payment method at this moment, please select a different payment method",
"error": "An error occurred. Please try again.",
"tryAgain": "Try again",
"a11y": {
"button": {
"edit": "Edit payment method",
"save": "Save payment {paymentMethodType} and continue to order review",
"cancel": "Cancel change of payment method {paymentMethodType}"
},
"tryAgain": "Try again to load payment methods"
},
"creditCard": {
"requiredHeader": "Required fields for payment by credit card",
"label": "Credit Card",
"cardPlaceHolder": "0000 0000 0000 0000",
"error": "Something has gone wrong during the payment process. Review your payment details and try again.",
"paymentMethodsError": "Error",
"required": "Required field",
"holderNameLabel": "Cardholder name",
"cardNumber": "Card number",
"expiryDate": "Expiry date",
"expiryMonth": "Expiry month",
"expiryYear": "Expiry year",
"verification": "CVC/CVV",
"tooltip": {
"heading": "Find your CVC/CVV",
"cardCvvInfo": "MasterCard/Visa/Discover: 3 digits on the back of your card",
"cardCvvInfoAmex": "American Express: 4 digits on the back of your card"
},
"validations": {
"cardHolderName": {
"required": "This field is required"
},
"cardNumber": {
"required": "This field is required",
"custom": "Invalid card number",
"pattern": "Invalid card number"
},
"expiryDate": {
"required": "This field is required",
"custom": "Invalid Expiry Date"
},
"cvc": {
"required": "This field is required",
"custom": "Invalid CVC/CVV",
"pattern": "Invalid CVC/CVV"
}
},
"payButtonText": "PAY WITH CREDIT CARD"
},
"invoice": {
"label": "Pay by Invoice",
"description": "Pay easily with Invoice and transfer the shopping amount within the specified date.",
"payButtonText": "PAY BY INVOICE"
},
"paypal": {
"label": "PayPal",
"description": "After reviewing your order, you will be redirected to PayPal to complete your payment.",
"payButtonText": "PAY WITH PAYPAL"
},
"klarna_pay_later": {
"label": "Klarna Pay later",
"description": "After reviewing your order, you will be redirected to Klarna to complete your payment.",
"payButtonText": "PAY WITH KLARNA PAY LATER"
},
"klarna_pay_now": {
"label": "Klarna Pay now",
"description": "After reviewing your order, you will be redirected to Klarna to complete your payment.",
"payButtonText": "PAY WITH KLARNA PAY NOW"
},
"klarna_pay_overtime": {
"label": "Klarna Pay over time",
"description": "After reviewing your order, you will be redirected to Klarna to complete your payment.",
"payButtonText": "PAY WITH KLARNA PAY OVER TIME"
},
"sofort": {
"label": "Sofort",
"description": "After reviewing your order, you will be redirected to Sofort to complete your payment.",
"payButtonText": "PAY WITH SOFORT"
},
"ideal": {
"label": "iDEAL",
"description": "After reviewing your order, you will be redirected to iDEAL to complete your payment.",
"placeholder": "Select your bank",
"required": "Required fields for payment by iDEAL",
"error": "Required field",
"payButtonText": "PAY WITH iDEAL"
},
"adyenChallenge": {
"heading": "Authenticate your payment",
"description": "To complete your payment please follow the instructions in the authentication window.",
"subheader": "Can't see the window?",
"link": "Open authentication window",
"cancel": "Cancel Payment"
},
"eps": {
"label": "eps",
"description": "After reviewing your order, you will be redirected to EPS to complete your payment.",
"payButtonText": "PAY WITH EPS"
},
"bancontactcard": {
"label": "Bancontact card",
"payButtonText": "PAY WITH BANCONTACT CARD"
},
"bancontactmobile": {
"label": "Bancontact Mobile",
"description": "After reviewing your order, you will be redirected to Bancontact Mobile to complete your payment.",
"payButtonText": "PAY WITH BANCONTACT MOBILE"
},
"twint": {
"label": "TWINT",
"description": "After reviewing your order, you will be redirected to TWINT to complete your payment.",
"payButtonText": "PAY WITH TWINT"
},
"sepadirectdebit": {
"label": "SEPA Direct Debit",
"payButtonText": "PAY WITH SEPA DIRECT DEBIT"
},
"klarna_billie": {
"label": "Buy Now, Pay Later with Billie",
"description": "After reviewing your order, you will be redirected to Klarna to complete your payment.",
"payButtonText": "PAY WITH BILLIE"
},
"googlepay": {
"label": "Google Pay",
"description": "After reviewing your order, you will be redirected to Google Pay to complete your payment.",
"payButtonText": "PAY WITH GOOGLE PAY"
},
"applepay": {
"label": "Apple Pay",
"description": "After reviewing your order, you will be redirected to Apple Pay to complete your payment.",
"payButtonText": "PAY WITH APPLE PAY"
},
"blik": {
"label": "BLIK",
"description": "After reviewing your order, you will be redirected to BLIK to complete your payment.",
"payButtonText": "PAY WITH BLIK"
},
"przelewy24": {
"label": "Przelewy24",
"description": "After reviewing your order, you will be redirected to Przelewy24 to complete your payment.",
"payButtonText": "PAY WITH PRZELEWY24"
},
"swish": {
"label": "Swish",
"description": "After reviewing your order, you will be redirected to Swish to complete your payment.",
"payButtonText": "PAY WITH SWISH"
},
"vipps": {
"label": "Vipps",
"description": "After reviewing your order, you will be redirected to Vipps to complete your payment.",
"payButtonText": "PAY WITH VIPPS"
},
"mobilepay": {
"label": "MobilePay",
"description": "After reviewing your order, you will be redirected to MobilePay to complete your payment.",
"payButtonText": "PAY WITH MOBILEPAY"
},
"afterpay": {
"label": "Afterpay",
"description": "After reviewing your order, you will be redirected to Afterpay to complete your payment.",
"payButtonText": "PAY WITH AFTERPAY"
},
"purchaseorder": {
"label": "Purchase Order (PO)",
"description": "Please enter a single authorized purchase order number generated by your organization. The PO number and payment instructions will appear on the invoice.",
"payButtonText": "PAY WITH PURCHASE ORDER (PO)"
},
"giftcard": {
"label": "Gift card",
"description": "Apply your gift card. If the balance is insufficient, a second payment method will be requested.",
"applyButtonText": "Apply Gift Card",
"error": "The number you entered is invalid. Please try again.",
"confirmPendingError": "Click \"Apply Gift Card\" to confirm your gift card number before you can continue.",
"inputEmptyError": "Enter and apply your gift card number before you can continue.",
"balanceTitle": "Gift card balance: {balance}",
"balanceTextSufficient": "The balance is sufficient to cover the entire payment.",
"balanceTextInsufficient": "The balance is not sufficient to cover the entire payment. Use a second payment method to cover the remaining amount.",
"giftcardApplied": "Successfully applied gift card",
"remove": "Remove",
"payButtonText": "PAY WITH GIFT CARD"
},
"zeroPayment": {
"info": "No payment is needed for your order"
}
},
"checkout": {
"button": {
"completePurchase": "Complete Purchase",
"payByInvoice": "Pay by Invoice",
"payWith": "Pay with {paymentMethodType}",
"leaveCheckout": "Leave checkout",
"zeroPayment": "GET YOUR FREE ORDER"
},
"heading": "Checkout"
},
"orderSummary": {
"heading": "Summary",
"cartDetails": {
"count": {
"singular": "{count} item",
"plural": "{count} items"
},
"item": {
"quantity": "Qty: {count}",
"unitPrice": "per item",
"gift": "Gift"
}
},
"totals": {
"subtotal": "Subtotal",
"discount": "Discount",
"shippingMethod": "Shipping cost: ",
"total": "Total",
"includingVAT": "incl. VAT",
"free": "Free",
"shippingDiscount": "Shipping discount",
"withoutTaxes": "Total without taxes",
"estimatedTaxes": "Estimated tax",
"calculatedLater": "Calculated later",
"coveredByGiftcard": "Covered by gift card",
"coveredBy": "Covered by {paymentMethodName}"
},
"discountCode": {
"heading": "Do you have a discount code?",
"yourCode": "Your discount code",
"label": "Enter and redeem your code",
"button": "Redeem Code",
"success": "Successfully redeemed code:",
"add": "+ Add code",
"another": "+ Add another code",
"list": "List of successfully redeemed codes: {codes}",
"invalidCode": "The code you entered is either invalid or has expired. Please try again.",
"noLongerValid": {
"singular": "The code {codes} has been removed as it no longer meets the conditions for use.",
"plural": "The following codes no longer meet the conditions for use and have been removed: {codes}"
},
"notApplicable": "{codeName} is a valid code, but it's not applicable right now. Ensure the correct item is in your cart. If it applies to delivery, select your delivery option first.",
"maxApplicationReached": "The code {codeName} no longer meets the conditions to be applied.",
"error": {
"singular": "An error occurred while trying to delete the discount code: {codes}",
"plural": "An error occurred while trying to delete the discount codes: {codes}"
},
"invalid": {
"singular": "The following code no longer meets the conditions to be applied and currently has no effect in the cart: {codes}",
"plural": "The following codes no longer meet the conditions to be applied and currently have no effect in the cart: {codes}"
},
"info": {
"singular": "The following code has been removed from the cart: {codes}",
"plural": "The following codes have been removed from the cart: {codes}"
},
"duplicated": {
"singular": "The code {codes} cannot be applied because the applied code {main} is based on the same discount.",
"plural": "The codes {codes} cannot be applied because the applied code {main} is based on the same discount."
}
},
"summaryBanner": {
"heading": "Summary",
"continue": "Continue to next step",
"ariaLabel": "Order Summary total price {totalPrice}, {numOfItems} {isPlural, select, true {items} other {item}}",
"a11y": {
"close": "Close summary",
"open": "Open summary"
}
}
},
"country": {
"germany": "Germany"
},
"cart": {
"total": "Total"
},
"shared": {
"back": "Back",
"boolean": {
"true": "Yes",
"false": "No"
},
"cancel": "Cancel",
"datePlaceholder": "MM/YY",
"edit": {
"button": "Edit",
"tooltip": "Save or cancel your changes first"
},
"optional": "(optional)"
},
"paymentConfirmation": {
"success": {
"alert": "Your payment has been successfully completed.",
"button": "Done",
"totalAmount": "Total amount",
"paidBy": "Paid by",
"a11y": {
"countdown": {
"singular": "Closing window in {seconds} second",
"plural": "Closing window in {seconds} seconds"
},
"close": "Close window.",
"done": "Payment successful. You will get redirected to into the main page in {seconds} second."
}
},
"zeroPaymentSuccess": {
"alert": "Your free order has been placed successfully."
},
"invoiceSuccess": {
"alert": "Your payment request has been successfully completed."
},
"error": {
"alert": "Something has gone wrong. {paymentMethodName, select, yourPayment {your payment} other {{paymentMethodName}}} could not be completed. Review your payment details and try again.",
"goToPaymentButton": "Go to payment details",
"leaveButton": "Leave checkout"
},
"orderCreationError": {
"title": "Order creation failed.",
"alert": "Something has gone wrong. Your payment has been completed, but the order cannot be processed."
},
"giftcardError": {
"alert": "Something has gone wrong with your gift card. Your payment could not be completed. Review your payment details and try again."
},
"secondPaymentIntegrationError": {
"alert": "Something has gone wrong with your second payment method. Your payment could not be completed. The amount paid with your gift card will be reimbursed."
},
"zeroPaymentError": {
"alert": "Something has gone wrong. Your order could not be placed successfully."
}
},
"components": {
"alert": {
"description": "Alert",
"error": {
"type": "Error alert.",
"message": "An error occurred. Please try again."
},
"warning": {
"type": "Warning alert.",
"message": "Please take a look."
},
"info": {
"type": "Info alert.",
"message": "Please take a look."
},
"success": {
"type": "Success alert.",
"message": "Everything went successfully."
},
"close": "Close window."
},
"result": {
"description": "Result",
"error": {
"type": "Error",
"title": "Payment failed!"
},
"orderCreationError": {
"type": "Error",
"title": "Problem with your order!"
},
"success": {
"type": "Success",
"title": "Payment successful!"
},
"invoiceSuccess": {
"type": "Success",
"title": "Payment request successful!"
},
"zeroPaymentSuccess": {
"type": "Success",
"title": "Order successful!"
}
},
"tag": {
"close": "You will remove the tag with text {tag}"
}
},
"error": {
"technicalIssue": {
"title": "Unable to proceed with the checkout",
"description": "There is a technical issue on our end. We are working on fixing this. Please leave this checkout and try again later.",
"retryDescription": "There is a technical issue on our end. We are working on fixing this. Try again now or leave this checkout.",
"close": "Leave checkout",
"retry": "Try again"
},
"emptyCart": {
"title": "Your cart is empty",
"message": "Please add at least one product to your cart before proceeding with the checkout."
},
"emptyCartBackgroundUpdate": {
"title": "Your cart is empty",
"message": "Your cart was updated during the checkout process. There are no more products in your cart, therefore you cannot proceed with the checkout."
},
"orderCreationError": {
"message": "Your payment has been processed but your order could not be created due to technical difficulties. Please reach out to customer service regarding your order status."
},
"reviewCart": {
"button": "Review cart",
"title": "Review your cart",
"message": "Your cart was updated during the checkout process. Please check if everything is still correct."
}
},
"agreements": {
"error": "This confirmation is required",
"tag": "required"
},
"shippingMethods": {
"feeWaived": "You have received free shipping.",
"feeDiscounted": "You have received a discount on your shipping."
}
}
Customize labels and descriptions of custom payment integrations
Standard payment integrations—available through Public Connectors—have default labels and descriptions that you can override. However, custom payment integrations—configurable through Organization Connectors—by default have no description and their label is the key provided by the Connector.
To improve the labels and descriptions of your custom payment integrations, you can customize the related properties in the
languageOverrides object, as you do for standard payment integrations.The following example customizes the label and description of a standard payment integration (
paypal) and of a sample custom payment integration (mypaymentintegration).You can customize the labels and descriptions of your custom payment integrations only if they are rendered via the web components Payment Integration Type.
import { checkoutFlow } from '@commercetools/checkout-browser-sdk';
checkoutFlow({
projectKey: '{projectKey}',
region: '{region}',
sessionId: '{sessionId}',
locale: 'en',
languageOverrides: {
payment: {
paypal: {
label: 'PayPal',
description: 'You will be redirected to PayPal',
},
mypaymentintegration: {
label: 'My Payment Integration',
description: 'Pay with our custom payment integration',
},
},
},
});