DocsAdminStore ConfigurationTranslations

Translations for Promotions (Beta)

The Translations Admin GraphQL API is available on Catalyst storefronts by default and in early access for Stencil and other headless storefronts. To get early access, reach out to the BigCommerce support team.

The following fields are translatable for promotions (all fields are included in responses; values may be null if no translation exists):

  • Banner availability as banner_availability
  • Banner upsell as banner_upsell
  • Banner eligibility as banner_eligibility
  • Banner congratulations as banner_congratulations

Only the fields above are supported for promotion translations. Requests with other field names will return an error.

Resource fields

Entity TyperesourceTyperesourceId Format
PromotionPROMOTIONSbc/store/promotion/{promotion_id}

Examples

Below are examples of GraphQL queries and mutations for retrieving and managing translation settings for promotions.

Query a List of Translations

This query returns up to 50 promotion translations for the specified resource type, channel, and locale.

The request below uses several variables for reusability. Replace {{channel_id}} and {{locale_code}} with the appropriate values for your use case.

Example query: Query a list of translations
GRAPHQL https://api.bigcommerce.com/stores/{{store_hash}}/graphql
X-Auth-Token: {{token}}
query {
  store {
    translations(
      filters: {
        resourceType: PROMOTIONS
        channelId: "bc/store/channel/{{channel_id}}"
        localeId: "bc/store/locale/{{locale_code}}"
      }
      first: 50
    ) {
      edges {
        node {
          resourceId
          fields {
            fieldName
            original
            translation
          }
        }
        cursor
      }
      pageInfo {
        hasNextPage
        hasPreviousPage
        startCursor
        endCursor
      }
    }
  }
}

Query a Translation by Resource ID

This query returns translation(s) by resourceId.

When querying a translation by resourceId, you must provide the full resourceId in the format bc/store/promotion/{promotion_id}.

The request below uses several variables for reusability. Replace {{resourceId}}, {{channel_id}}, and {{locale_code}} with appropriate values for your use case. Make sure resourceId follows the format from the Resource fields table.

Example query: Query a translation by id
GRAPHQL https://api.bigcommerce.com/stores/{{store_hash}}/graphql
X-Auth-Token: {{token}}
query {
  store {
    translations(
      filters: {
        resourceType: PROMOTIONS
        channelId: "bc/store/channel/{{channel_id}}"
        localeId: "bc/store/locale/{{locale_code}}"
        resourceIds: ["{{resourceId}}"]
      }
    ) {
      edges {
        node {
          resourceId
          fields {
            fieldName
            original
            translation
          }
        }
        cursor
      }
    }
  }
}

Update a Translation

This mutation updates translated values for promotions for a specific channel and locale.

Example mutation: Update a translation
GRAPHQL https://api.bigcommerce.com/stores/{{store_hash}}/graphql
X-Auth-Token: {{token}}
mutation {
  translation {
    updateTranslations(
      input: {
        resourceType: PROMOTIONS,
        channelId: "bc/store/channel/{{channel_id}}",
        localeId: "bc/store/locale/{{locale_code}}",
        entities: [
          {
            resourceId: "bc/store/promotion/101",
            fields: [
              { fieldName: "banner_availability", value: "Bannière disponible" },
              { fieldName: "banner_upsell", value: "Bannière de montée en gamme" },
              { fieldName: "banner_eligibility", value: "Bannière d'éligibilité" },
              { fieldName: "banner_congratulations", value: "Bannière de félicitations" }
            ]
          },
          {
            resourceId: "bc/store/promotion/102",
            fields: [
              { fieldName: "banner_availability", value: "Bannière disponible" },
              { fieldName: "banner_upsell", value: "Bannière de montée en gamme" },
              { fieldName: "banner_eligibility", value: "Bannière d'éligibilité" },
              { fieldName: "banner_congratulations", value: "Bannière de félicitations" }
            ]
          }
        ]
      }
    ) {
      __typename
      errors {
        __typename
        ... on ValidationError {
          message
        }
        ... on EntityNotFoundError {
          id
          message
        }
        ... on InvalidTranslationEntityFieldsError {
          id
          message
          fields
        }
      }
    }
  }
}

The mutation example above shows a successful response. If invalid fields or resource IDs are provided, the API will return error responses. See the Error Handling Reference for more details on error responses.

Delete a Translation

The following mutation removes translated values for specified promotion fields, reverting them to the original values for a specific channel and locale.

Example mutation: Delete a translation
GRAPHQL https://api.bigcommerce.com/stores/{{store_hash}}/graphql
X-Auth-Token: {{token}}
mutation {
  translation {
    deleteTranslations(
      input: {
        resourceType: PROMOTIONS,
        channelId: "bc/store/channel/{{channel_id}}",
        localeId: "bc/store/locale/{{locale_code}}",
        resources: [
          {
            resourceId: "bc/store/promotion/101",
            fields: [
              "banner_availability",
              "banner_upsell",
              "banner_eligibility",
              "banner_congratulations"
            ]
          },
          {
            resourceId: "bc/store/promotion/102",
            fields: [
              "banner_availability",
              "banner_upsell"
            ]
          }
        ]
      }
    ) {
      __typename
      errors {
        __typename
        ... on ValidationError {
          message
        }
        ... on EntityNotFoundError {
          id
          message
        }
        ... on InvalidTranslationEntityFieldsError {
          id
          message
          fields
        }
      }
    }
  }
}