Documentation

Customize the texts and labels of commercetools 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.

This is possible by adding the optional languageOverrides object in the checkoutConfig object during the checkout initialization. In the languageOverrides object, you can include the properties for which you want to customize the content.

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 title and description of the 'emptyCart' message using the Browser SDKJavaScript
import { ctc } from '@commercetools/checkout-browser-sdk';


ctc('init', {
  checkoutConfig: {
    projectKey: '{projectKey}',
    applicationKey: '{applicationKey}',
    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.',
        },
      },
    },
  },
});
Customize title and description of the 'emptyCart' message using a WebView componentJavaScript
injectedJavaScript={`
   window.commercetoolsCheckoutData =  {
     projectKey: '{projectKey}',
     applicationKey: '{applicationKey}',
     cartId: '{cartId}',
     host: 'https://app.checkout.{region}.commercetools.com',
     accessToken: '{accessToken}',
     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.',
        },
     },
   }
   window.initCommercetoolsCheckout();
   window.addEventListener('message', function (messageEvent) {
     if (origin === '{commercetoolsCheckoutHost}') {
       window.ReactNativeWebView.postMessage(JSON.stringify(messageEvent.data));
     }
   });
 `}

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 Browser SDKJavaScript
import { ctc } from '@commercetools/checkout-browser-sdk';


ctc('init', {
  checkoutConfig: {
    projectKey: '{projectKey}',
    applicationKey: '{applicationKey}',
    locale: 'de',
    languageOverrides: {
      address: {
        email: 'E-Mail-Addresse',
        phone: 'Optionale Telefonnummer',
        city: 'Stadt',
      },
    },
  },
});
Customize 'email', 'phone', and 'city' fields using a WebView componentJavaScript
injectedJavaScript={`
   window.commercetoolsCheckoutData =  {
     projectKey: '{projectKey}',
     applicationKey: '{applicationKey}',
     cartId: '{cartId}',
     host: 'https://app.checkout.{region}.commercetools.com',
     accessToken: '{accessToken}',
     locale: 'de',
     languageOverrides: {
      'address': {
        'email': 'E-Mail-Addresse',
        'phone': 'Optionale Telefonnummer',
        'city': 'Stadt',
     },
   }
   window.initCommercetoolsCheckout();
   window.addEventListener('message', function (messageEvent) {
     if (origin === '{commercetoolsCheckoutHost}') {
       window.ReactNativeWebView.postMessage(JSON.stringify(messageEvent.data));
     }
   });
 `}

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 commercetools 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}".

commercetools Checkout supports only the following 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 (optional)",
    "shippingAddress": "Shipping Address",
    "firstName": "First Name",
    "lastName": "Last Name",
    "streetName": "Street address",
    "state": "State",
    "additionalStreetInfo": "Apt, suite, building, etc. (optional)",
    "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 (optional)",
    "saveAndContinue": "Save & Continue",
    "title": "Address",
    "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"
      },
      "postalCode": {
        "required": "Required field",
        "pattern": "Invalid ZIP code"
      },
      "city": {
        "required": "Required field"
      },
      "phone": {
        "custom": "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.",
    "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"
        }
      }
    },
    "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."
    },
    "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",
      "payWith": "Pay with {paymentMethodType}"
    }
  },
  "orderSummary": {
    "heading": "Order Summary",
    "cartDetails": {
      "heading": "Cart Details",
      "count": {
        "singular": "| {count} item",
        "plural": "| {count} items"
      },
      "item": {
        "quantity": "Qty: {count}",
        "unitPrice": "per item",
        "gift": "Gift"
      }
    },
    "totals": {
      "heading": "Total price",
      "subtotal": "Subtotal",
      "discount": "Discount",
      "shippingMethod": "Shipping: ",
      "total": "Total",
      "includingVAT": "incl. VAT",
      "free": "Free",
      "shippingDiscount": "Shipping discount"
    },
    "voucher": {
      "heading": "Voucher",
      "count": "| {count} redeemed",
      "label": "Enter and redeem your code",
      "button": "Redeem Voucher",
      "success": "Successfully redeemed voucher:",
      "link": "Add voucher code",
      "list": "List of successfully redeemed vouchers: {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 voucher code: {codes}",
        "plural": "An error occurred while trying to delete the voucher 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."
      }
    }
  },
  "country": {
    "germany": "Germany"
  },
  "cart": {
    "total": "Total"
  },
  "shared": {
    "back": "Back",
    "cancel": "Cancel",
    "datePlaceholder": "MM/YY",
    "edit": {
      "button": "Edit",
      "tooltip": "Save or cancel your changes first"
    }
  },
  "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."
      }
    },
    "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!"
      }
    },
    "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."
    },
    "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"
  }
}