Customize the texts and labels of Checkout
Customize the texts and labels of your checkout experience with commercetools Checkout.
commercetools 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.
Customize the 'emptyCart' error using the 'checkoutFlow' methodJavaScript
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.
Customize 'email', 'phone', and 'city' fields using the 'checkoutFlow' methodJavaScript
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 "payWith": "Pay with {paymentMethodType}" appears as Pay with PayPal if you set PayPal as a payment method.
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}".
Checkout supports only the following properties and eventual custom payment methods properties. Any other property declared will be ignored.
Dynamic parameters must have single curly braces. Otherwise, the related dynamic content is not rendered.
Customizable properties and their default value for the English localejson
{"address": {"email": "Email Address","phone": "Phone number","shippingAddress": "Shipping Address","firstName": "First Name","lastName": "Last Name","streetName": "Street address","streetNumber": "Street number","salutation": "Salutation","state": "State","additionalStreetInfo": "Apt, suite, building, etc.","postalCode": "ZIP code","city": "City/Town","country": "Country","continue": "Continue","editShippingAddress": "Edit shipping address","editBillingAddress": "Edit 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.","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": {"save": "Save shipping and billing address","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 delivery type","edit": "Edit delivery type","cancel": "Cancel change of delivery type"}}},"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": "The internet connection is down. Please check your connection and try again.","tryAgain": "Try again","a11y": {"button": {"edit": "Edit payment method","save": "Continue to review payment method {paymentMethodType}","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"}}},"invoice": {"label": "Pay by Invoice","description": "Pay easily with Invoice and transfer the shopping amount within the specified date."},"paypal": {"label": "PayPal","description": "After reviewing your order, you will be redirected to PayPal to complete your payment."},"klarna": {"label": "Klarna","description": "After reviewing your order, you will be redirected to Klarna to complete your payment."},"klarna_paynow": {"label": "Klarna Pay now","description": "After reviewing your order, you will be redirected to Klarna to complete your payment."},"klarna_account": {"label": "Klarna Pay over time","description": "After reviewing your order, you will be redirected to Klarna to complete your payment."},"sofort": {"label": "Sofort","description": "After reviewing your order, you will be redirected to Sofort to complete your payment."},"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"},"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"}},"checkout": {"button": {"completePurchase": "Complete Purchase","payByInvoice": "Pay by Invoice","payWith": "Pay with {paymentMethodType}","leaveCheckout": "Leave checkout"},"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: ","total": "Total","includingVAT": "incl. VAT","free": "Free","shippingDiscount": "Shipping discount","withoutTaxes": "Total without taxes","estimatedTaxes": "Estimated tax","calculatedLater": "Calculated later"},"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.","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","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","totalPayment": "Total payment","paymentMethod": "Payment method","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."}},"invoiceSuccess": {"alert": "Your payment request has been successfully received.","paymentMethod": "Invoice payment method"},"error": {"alert": "Something has gone wrong. Your payment could not be completed. Review your payment details and try again.","goToPaymentButton": "Go to payment details","leaveButton": "Leave checkout"},"orderCreationError": {"alert": "Something has gone wrong. Your payment was confirmed but your order could not be placed. Please contact us and provide this ID: {cartId} "}},"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!"}},"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"}}
Customize labels and descriptions of custom payment methods
Standard payment methods—available through Public Connectors—have default labels and descriptions that you can override. However, custom payment methods—configurable through Organization Connectors—by default have no description and their label is the key provided by the payment Connector.
To improve the labels and descriptions of your custom payment methods, you can customize the related properties in the languageOverrides object, as you do for standard payment methods.
The following example customizes the label and description of a standard payment method (paypal) and of a sample custom payment method (mypaymentmethod).
Customize 'paypal' and 'mypaymentmethod' using the 'checkoutFlow' methodJavaScript
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',},mypaymentmethod: {label: 'My Payment Method',description: 'Pay with our custom payment method',},},},});