Override core strings

Learn to customize text strings for InStore core functions.

What you can and cannot override with the tenant API

For core product modules, InStore retrieves UI strings from the InStore API. Override only the keys you want to change. Other keys fall back to defaults. Strings open to customization include menu options, page headings, error messages, and more.

The tenant API does not provide a means to customize:

Receipt text, whose customization is described in Receipt template sets.
Reference lists (reason codes), whose customization is described in Reference lists.
InStore colleague app accelerator modules, for which the API is consulted first and predefined language bundles second. The bundles are accessible in the retailer-accessible repository.

Style overrides are described in Override product module styling.

You can specify text for use with a single payment option. For example, you can provide different values for on-screen text that are appropriate for a return voucher versus a branded gift card.

Use the tenant API to replace string values

Follow these steps to override strings in the InStore core:

Make this API request:

PUT {{api-url}}/:tenantId/translations

Replace api-url with the appropriate API host listed in InStore documentation.
Replace tenantId with the 16-character identifier for the environment whose text you want to override. For example, "bc6e-2e4c-ff43-1711".
Specify overrides as shown in this example.
Define a payload { ... } for each section based on the main payload in the example.
Get an administrator access token. The credentials used here are the same as the ones you use with all InStore APIs.
You must include {{login_token}} in the header of your request. For example, in the PUT call, insert the {{login_token}} as the value for the token key that pairs with the header.

Route

Path	Type	Description
/:tenantId/translations	PUT	Override default translations for supported locales.

Request

Field	Type	Description
`translations`	array	List of per-locale translation override objects.

Example

The following example replaces the string Cash Drawer with Till in the en-GB bundle.

Translations override payload (excerpt)json
{
  "translations": [
    {
      "locale": "en-GB",
      "bundle": {
        "CashCollection": {
          "promptMessageChangeDue": "Give change to customer and close the till.",
          "userMessageCreditApproved": "Card payment approved."
        },
        "CashDrawer": {
          "promptMessageClose": "Confirm the till is closed and press OK.",
          "promptMessageSelection": "Select the Till and Reason for the count.",
          "promptMessagePayInOpen": "Place cash received in till, close the till, and press DONE.",
          "promptMessagePayOutOpen": "Remove disbursement amount from till, close the till, and press DONE.",
          "promptMessageCashAuditOpen": "Remove transfer amount from till, close the till, and press DONE.",
          "userMessageOpenCashDrawer": "Till open.",
          "userMessageCashDrawerClosed": "Till closed."
        },
        "CashManagement": {
          "promptMessageCashAudit": "Select a Till, review the data and press DONE to finish.",
          "promptMessageSafeDeposit": "Select the Till and Reason and press NEXT to continue.",
          "promptMessageSafeReserve": "Leave the Reserve Amount in the till. Close the till. Place the Deposit Amount in the safe, and press DONE."
        },
        "Custom": {
          "option-credit-uk": {
            "Checkout": {
              "cashCollectionPaymentBox": "Processing card payment",
              "cashCollectionExactChange": "Exact change received"
            }
          },
          "custom-event": "Payment completed"
        }
      }
    }
  ]
}

The fields are defined as follows:

Element	Description
locale	The locale whose strings you want to override. The locale must be in xx-XX format where xx is the language code and XX is the country code, separated by a hyphen. InStore supports a subset of locales. To view the list of locales, access the InStore Center and view the Supported Languages control on the Environment > Localization tab. Your overrides will show up in locations where this locale value matches the "Locale" field set for the location in the InStore Center.
bundle	Section marker containing the list of overrides.
CashCollection	Example of a heading that contains some strings you want to override. Find the heading by looking it up in the List of core strings.
promptMessageChangeDue	The first example of a string key contained within the specified heading. Never edit string keys.
"Give change to customer and close the till."	The first example of an override string, which is the value you want to display in the application. Place it to the right of the colon and enclose it in double quotes. After a successful run of this request, the override string replaces the default text in the user interface.
Custom segment	Section marker for payment stepper overrides and more. See Customize payment stepper messages. Use this section to override text on payment option-specific screens. See Override strings for multiple payment options.
option-credit-uk	Example of the payment option key whose flow you are customizing strings for. This is the universally unique name that was specified by a user when the payment option was created.
custom-event	Example of a key within the Custom section when your organization created a custom event. For example, the Stepper in the credit flow is a typical place for custom events. If you omit a value for this type of custom key, the key will be ignored.

After you send the request:

Include only the strings that you want to override.
Verify that the :tenantId path parameter matches the tenant environment you intend to update.
Run the request and review the response. The response contains the updated bundle in JSON format.

Important notes

The body of your request should always contain all the InStore core overrides you want. If you omit a previously specified override from the current request, the API reverts that key to its default value.
In the InStore Center, your administrator user record must have the tenant environment that you are overriding assigned as its default environment.
Do not specify null values in the tenant API. You can supply blank values or empty strings (" "), which will result in no string being displayed in the application. Remove a key from the API request body to revert to its default value.
Keep overrides for a single locale within the same locale section.
Do not alter or translate the string keys; edit only their override values.
Do not repeat the same key within a single object.
When overriding toast messages, let the previous value guide the character count of your override. For example, if the previous string was "Payment completed", that is 17 characters long. Choose an override with a similar character count, such as "Payment success!"

Override core strings for multiple locales

Each locale is specified at the top level below translations in the request body. You override strings for multiple locales in your tenant by creating a composite request:

Make this API request:

PUT {{api-url}}/:tenantId/translations

Replace api-url with the appropriate API host listed in InStore documentation.
Replace tenantId with the 16-character identifier for the environment whose text you want to override. For example, "bc6e-2e4c-ff43-1711".
On the Body tab, copy the entire section that is bracketed to include locale.
At an equivalent indented position in the request body, paste the section and replace the original value for locale with that of the new locale.
Edit the values for the new locale as shown in the example below:

{
  "translations": [
    {
      "locale": "en-AU",
      "bundle": {
        "Checkout": {
          "cashCollectionPaymentBox": "Processing credit payment",
          "cashCollectionExactChange": "Customer gave Exact Change"
        }
      }
    },
    {
      "locale": "es-MX",
      "bundle": {
        "Checkout": {
          "cashCollectionPaymentBox": "Procesando pago con crédito",
          "cashCollectionExactChange": "Cliente dio cambio exacto"
        }
      }
    }
  ]
}

The body of your request should always contain all the overrides for all the locales you want. If you omit a previously specified override from the current request, the API reverts that key to its default value for the specified locale.

Override strings for multiple payment options

Each payment option is specified within the "Custom" section of the request body as described in Specify your override strings. You can override strings that are visible in the application's payment flow after that payment option has been selected by the user.

You can override strings for multiple payment options in your tenant by creating a composite request as described below.

Make this API request:

PUT {{api-url}}/:tenantId/translations

Replace api-url with the appropriate API host listed in InStore documentation.
Replace tenantId with the 16-character identifier for the environment whose text you want to override. For example, "bc6e-2e4c-ff43-1711".
On the Body tab and within the relevant locale and Custom section, copy a payment option section, using the JSON brackets as your guide. Your selection may include toast or error messages.
At an equivalent indented position within the Custom section of the request body, paste and replace the original payment option key with that of a different payment option.
Edit the values for the new payment option as shown in the example below:

{
  "translations": [
    {
      "locale": "en-GB",
      "bundle": {
        "Custom": {
          "credit-payment-option-1": {
            "Checkout": {
              "cashCollectionPaymentBox": "Processing type 1 payment"
            }
          },
          "credit-payment-option-2": {
            "Checkout": {
              "cashCollectionPaymentBox": "Processing type 2 payment"
            }
          }
        }
      }
    }
  ]
}

Look up overrides currently in the tenant

You can confirm the contents of the current override or translations section for the tenant you have been working with.

Make this API request:

GET {{api-url}}/tenant

Replace api-url with the appropriate API host listed in InStore documentation.
Run the request and view the response. Scroll down until you see:

 "translations": [],

The string keys and values that are being overridden are listed within the square brackets.

Override core strings

What you can and cannot override with the tenant API.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Use the tenant API to replace string values.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Route.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Request.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Example.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Important notes.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Override core strings for multiple locales.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Override strings for multiple payment options.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Look up overrides currently in the tenant.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}