From bc6af5ad157b60b27bc6c04d6463594621e947f3 Mon Sep 17 00:00:00 2001 From: Kristina Pototska Date: Tue, 6 Jan 2026 11:16:56 +0000 Subject: [PATCH 1/3] Add Order Statuses and Promotions translation docs - Add order-statuses.mdx with list/by-id/update/delete examples - Add promotions.mdx with list/by-id/update/delete examples - Update index.mdx to include Order Statuses and Promotions --- docs/store-operations/translations/index.mdx | 4 + .../translations/order-statuses.mdx | 332 ++++++++++++++++ .../translations/promotions.mdx | 358 ++++++++++++++++++ 3 files changed, 694 insertions(+) create mode 100644 docs/store-operations/translations/order-statuses.mdx create mode 100644 docs/store-operations/translations/promotions.mdx diff --git a/docs/store-operations/translations/index.mdx b/docs/store-operations/translations/index.mdx index e71378314..60bc59bff 100644 --- a/docs/store-operations/translations/index.mdx +++ b/docs/store-operations/translations/index.mdx @@ -16,6 +16,8 @@ The API currently supports translations for the following resource types, and mo * Brands * [Product Filters](/docs/store-operations/translations/filters) * [Locations](/docs/store-operations/translations/locations) +* [Order Statuses](/docs/store-operations/translations/order-statuses) +* [Promotions](/docs/store-operations/translations/promotions) Refer to the [Error Handling](/docs/store-operations/translations/errors) guide for understanding and handling errors while managing translations. @@ -74,4 +76,6 @@ For more information on OAuth Scopes, see our [Guide to API Accounts](/docs/star - [Product Listing Page Translations](/docs/store-operations/translations/listings) - [Product Filter Translations](/docs/store-operations/translations/filters) - [Inventory Locations Translations](/docs/store-operations/translations/locations) +- [Order Status Translations](/docs/store-operations/translations/order-statuses) +- [Promotions Translations](/docs/store-operations/translations/promotions) - [Error Handling Reference](/docs/store-operations/translations/errors) diff --git a/docs/store-operations/translations/order-statuses.mdx b/docs/store-operations/translations/order-statuses.mdx new file mode 100644 index 000000000..dbce59774 --- /dev/null +++ b/docs/store-operations/translations/order-statuses.mdx @@ -0,0 +1,332 @@ +# Translations for Order Statuses (Beta) + + + The Translations Admin GraphQL API is currently available on Catalyst + storefronts only. + + +The following entities are translatable for order statuses: + +- Label as `label` + +## Resource fields + +| Entity Type | `resourceType` | `resourceId` Format | +| --------------- | ----------------- | ---------------------------------- | +| Order Status | `ORDER_STATUSES` | `bc/store/orderStatus/{status_id}` | + +## Examples + +Below are examples of GraphQL queries and mutations for retrieving and managing translation settings for order statuses. + +### Query a List of Translations + +This query returns up to 50 order status 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. + + + + +```graphql filename="Example query: Query a list of translations" showLineNumbers copy +GRAPHQL https://api.bigcommerce.com/stores/{{store_hash}}/graphql +X-Auth-Token: {{token}} + +query { + store { + translations( + filters: { + resourceType: ORDER_STATUSES + 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 + } + } + } +} +``` + + + + +```json filename="Example query: Query a list of translations" showLineNumbers copy +{ + "data": { + "store": { + "translations": { + "edges": [ + { + "node": { + "resourceId": "bc/store/orderStatus/0", + "fields": [ + { + "fieldName": "label", + "original": "Incomplete", + "translation": "Incomplete (FR)" + } + ] + }, + "cursor": "eyJpZCI6MH0" + }, + { + "node": { + "resourceId": "bc/store/orderStatus/1", + "fields": [ + { + "fieldName": "label", + "original": "Pending", + "translation": "Pending (FR)" + } + ] + }, + "cursor": "eyJpZCI6MX0" + } + ], + "pageInfo": { + "hasNextPage": false, + "hasPreviousPage": false, + "startCursor": "eyJpZCI6MH0", + "endCursor": "eyJpZCI6MX0" + } + } + } + } +} +``` + + + + +### Query a Translation by Resource ID + +This query returns translation(s) by resourceId. + +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](#resource-fields) table. + + + + +```graphql filename="Example query: Query a translation by id" showLineNumbers copy +GRAPHQL https://api.bigcommerce.com/stores/{{store_hash}}/graphql +X-Auth-Token: {{token}} + +query { + store { + translations( + filters: { + resourceType: ORDER_STATUSES + channelId: "bc/store/channel/{{channel_id}}" + localeId: "bc/store/locale/{{locale_code}}" + resourceIds: ["{{resourceId}}"] + } + ) { + edges { + node { + resourceId + fields { + fieldName + original + translation + } + } + cursor + } + } + } +} +``` + + + + +```json filename="Example query: Query a translation by id" showLineNumbers copy +{ + "data": { + "store": { + "translations": { + "edges": [ + { + "node": { + "resourceId": "bc/store/orderStatus/1", + "fields": [ + { + "fieldName": "label", + "original": "Pending", + "translation": "Pending (FR)" + } + ] + }, + "cursor": "eyJpZCI6MX0" + } + ] + } + } + } +} +``` + + + + +### Update a Translation + +This mutation updates translated values for order statuses for a specific channel and locale. + + + + +```graphql filename="Example mutation: Update a translation" showLineNumbers copy +GRAPHQL https://api.bigcommerce.com/stores/{{store_hash}}/graphql +X-Auth-Token: {{token}} + +mutation { + translation { + updateTranslations( + input: { + resourceType: ORDER_STATUSES, + channelId: "bc/store/channel/{{channel_id}}", + localeId: "bc/store/locale/{{locale_code}}", + entities: [ + { + resourceId: "bc/store/orderStatus/0", + fields: [ + { fieldName: "label", value: "Incomplete (FR)" } + ] + }, + { + resourceId: "bc/store/orderStatus/1", + fields: [ + { fieldName: "label", value: "Pending (FR)" } + ] + } + ] + } + ) { + __typename + errors { + __typename + ... on ValidationError { + message + } + ... on EntityNotFoundError { + id + message + } + ... on InvalidTranslationEntityFieldsError { + id + message + fields + } + } + } + } +} +``` + + + + +```json filename="Example mutation: Update a translation" showLineNumbers copy +{ + "data": { + "translation": { + "updateTranslations": { + "__typename": "UpdateTranslationsResult", + "errors": [] + } + } + } +} +``` + + + + +### Delete a Translation + +The following mutation removes translated values for specified order status fields, reverting them to the original values for a specific channel and locale. + + + + +```graphql filename="Example mutation: Delete a translation" showLineNumbers copy +GRAPHQL https://api.bigcommerce.com/stores/{{store_hash}}/graphql +X-Auth-Token: {{token}} + +mutation { + translation { + deleteTranslations( + input: { + resourceType: ORDER_STATUSES, + channelId: "bc/store/channel/{{channel_id}}", + localeId: "bc/store/locale/{{locale_code}}", + resources: [ + { + resourceId: "bc/store/orderStatus/0", + fields: ["label"] + }, + { + resourceId: "bc/store/orderStatus/1", + fields: ["label"] + } + ] + } + ) { + __typename + errors { + __typename + ... on ValidationError { + message + } + ... on EntityNotFoundError { + id + message + } + ... on InvalidTranslationEntityFieldsError { + id + message + fields + } + } + } + } +} +``` + + + + +```json filename="Example mutation: Delete a translation" showLineNumbers copy +{ + "data": { + "translation": { + "deleteTranslations": { + "__typename": "DeleteTranslationsResult", + "errors": [] + } + } + } +} +``` + + + + diff --git a/docs/store-operations/translations/promotions.mdx b/docs/store-operations/translations/promotions.mdx new file mode 100644 index 000000000..a53572e17 --- /dev/null +++ b/docs/store-operations/translations/promotions.mdx @@ -0,0 +1,358 @@ +# Translations for Promotions (Beta) + + + The Translations Admin GraphQL API is currently available on Catalyst + storefronts only. + + +The following entities are translatable for promotions: + +- Name as `name` +- Description as `description` + +## Resource fields + +| Entity Type | `resourceType` | `resourceId` Format | +| ----------- | ---------------- | --------------------------------- | +| Promotion | `PROMOTIONS` | `bc/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. + + + + +```graphql filename="Example query: Query a list of translations" showLineNumbers copy +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 + } + } + } +} +``` + + + + +```json filename="Example query: Query a list of translations" showLineNumbers copy +{ + "data": { + "store": { + "translations": { + "edges": [ + { + "node": { + "resourceId": "bc/store/promotion/101", + "fields": [ + { + "fieldName": "name", + "original": "Holiday Promo", + "translation": "Promotion des fêtes" + }, + { + "fieldName": "description", + "original": "Seasonal discount", + "translation": "Remise saisonnière" + } + ] + }, + "cursor": "eyJpZCI6MTAxfQ" + }, + { + "node": { + "resourceId": "bc/store/promotion/102", + "fields": [ + { + "fieldName": "name", + "original": "Spring Sale", + "translation": null + }, + { + "fieldName": "description", + "original": "Limited time offer", + "translation": null + } + ] + }, + "cursor": "eyJpZCI6MTAyfQ" + } + ], + "pageInfo": { + "hasNextPage": false, + "hasPreviousPage": false, + "startCursor": "eyJpZCI6MTAxfQ", + "endCursor": "eyJpZCI6MTAyfQ" + } + } + } + } +} +``` + + + + +### 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](#resource-fields) table. + + + + +```graphql filename="Example query: Query a translation by id" showLineNumbers copy +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 + } + } + } +} +``` + + + + +```json filename="Example query: Query a translation by id" showLineNumbers copy +{ + "data": { + "store": { + "translations": { + "edges": [ + { + "node": { + "resourceId": "bc/store/promotion/101", + "fields": [ + { + "fieldName": "name", + "original": "Holiday Promo", + "translation": "Promotion des fêtes" + }, + { + "fieldName": "description", + "original": "Seasonal discount", + "translation": "Remise saisonnière" + } + ] + }, + "cursor": "eyJpZCI6MTAxfQ" + } + ] + } + } + } +} +``` + + + + +### Update a Translation + +This mutation updates translated values for promotions for a specific channel and locale. + + + + +```graphql filename="Example mutation: Update a translation" showLineNumbers copy +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: "name", value: "Promotion des fêtes" }, + { fieldName: "description", value: "Remise saisonnière" } + ] + }, + { + resourceId: "bc/store/promotion/102", + fields: [ + { fieldName: "name", value: "Vente de printemps" }, + { fieldName: "description", value: "Offre limitée" } + ] + } + ] + } + ) { + __typename + errors { + __typename + ... on ValidationError { + message + } + ... on EntityNotFoundError { + id + message + } + ... on InvalidTranslationEntityFieldsError { + id + message + fields + } + } + } + } +} +``` + + + + +```json filename="Example mutation: Update a translation" showLineNumbers copy +{ + "data": { + "translation": { + "updateTranslations": { + "__typename": "UpdateTranslationsResult", + "errors": [] + } + } + } +} +``` + + + + + +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](/docs/store-operations/translations/errors) 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. + + + + +```graphql filename="Example mutation: Delete a translation" showLineNumbers copy +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: ["name", "description"] + }, + { + resourceId: "bc/store/promotion/102", + fields: ["name"] + } + ] + } + ) { + __typename + errors { + __typename + ... on ValidationError { + message + } + ... on EntityNotFoundError { + id + message + } + ... on InvalidTranslationEntityFieldsError { + id + message + fields + } + } + } + } +} +``` + + + + +```json filename="Example mutation: Delete a translation" showLineNumbers copy +{ + "data": { + "translation": { + "deleteTranslations": { + "__typename": "DeleteTranslationsResult", + "errors": [] + } + } + } +} +``` + + + + From 84fc3eb26360b67829d7800a4921636463b0df04 Mon Sep 17 00:00:00 2001 From: Kristina Pototska Date: Wed, 7 Jan 2026 11:14:22 +0000 Subject: [PATCH 2/3] Clarify order status IDs are static and link to REST docs --- docs/store-operations/translations/order-statuses.mdx | 5 +++++ docs/store-operations/translations/promotions.mdx | 1 + 2 files changed, 6 insertions(+) diff --git a/docs/store-operations/translations/order-statuses.mdx b/docs/store-operations/translations/order-statuses.mdx index dbce59774..3e4c50885 100644 --- a/docs/store-operations/translations/order-statuses.mdx +++ b/docs/store-operations/translations/order-statuses.mdx @@ -9,6 +9,10 @@ The following entities are translatable for order statuses: - Label as `label` + + Order status IDs are predefined and static; merchants can only change the status name. See the [Order Status REST API](https://developer.bigcommerce.com/docs/rest-management/orders/order-status#get-all-order-statuses) for the full list of statuses and their IDs. + + ## Resource fields | Entity Type | `resourceType` | `resourceId` Format | @@ -330,3 +334,4 @@ mutation { + diff --git a/docs/store-operations/translations/promotions.mdx b/docs/store-operations/translations/promotions.mdx index a53572e17..ac90c9f39 100644 --- a/docs/store-operations/translations/promotions.mdx +++ b/docs/store-operations/translations/promotions.mdx @@ -356,3 +356,4 @@ mutation { + From 5bdad7bc249ec37ba4b44be748616e6751410e7f Mon Sep 17 00:00:00 2001 From: Kristina Pototska Date: Wed, 7 Jan 2026 11:27:34 +0000 Subject: [PATCH 3/3] Clarify order status IDs and restrict promotion fields --- .../translations/order-statuses.mdx | 2 +- .../translations/promotions.mdx | 78 +++++++++---------- 2 files changed, 40 insertions(+), 40 deletions(-) diff --git a/docs/store-operations/translations/order-statuses.mdx b/docs/store-operations/translations/order-statuses.mdx index 3e4c50885..9c823f171 100644 --- a/docs/store-operations/translations/order-statuses.mdx +++ b/docs/store-operations/translations/order-statuses.mdx @@ -10,7 +10,7 @@ The following entities are translatable for order statuses: - Label as `label` - Order status IDs are predefined and static; merchants can only change the status name. See the [Order Status REST API](https://developer.bigcommerce.com/docs/rest-management/orders/order-status#get-all-order-statuses) for the full list of statuses and their IDs. + Order status IDs are predefined and static (0–14). Merchants can only change the status name. See the [Order Status REST API](https://developer.bigcommerce.com/docs/rest-management/orders/order-status#get-all-order-statuses) for the full list of statuses and their IDs. ## Resource fields diff --git a/docs/store-operations/translations/promotions.mdx b/docs/store-operations/translations/promotions.mdx index ac90c9f39..ad68f16bc 100644 --- a/docs/store-operations/translations/promotions.mdx +++ b/docs/store-operations/translations/promotions.mdx @@ -5,10 +5,16 @@ storefronts only. -The following entities are translatable for promotions: +The following fields are translatable for promotions (all fields are required in responses; values may be null if no translation exists): -- Name as `name` -- Description as `description` +- Banners availability as `banners_availability` +- Banners upsell as `banners_upsell` +- Banners eligibility as `banners_eligibility` +- Banners congratulations as `banners_congratulations` + + + Only the fields above are supported for promotion translations. Requests with other field names will return an error. + ## Resource fields @@ -78,16 +84,10 @@ query { "node": { "resourceId": "bc/store/promotion/101", "fields": [ - { - "fieldName": "name", - "original": "Holiday Promo", - "translation": "Promotion des fêtes" - }, - { - "fieldName": "description", - "original": "Seasonal discount", - "translation": "Remise saisonnière" - } + { "fieldName": "banners_availability", "original": "Available banner", "translation": "Bannière disponible" }, + { "fieldName": "banners_upsell", "original": "Upsell banner", "translation": "Bannière de montée en gamme" }, + { "fieldName": "banners_eligibility", "original": "Eligibility banner", "translation": "Bannière d'éligibilité" }, + { "fieldName": "banners_congratulations", "original": "Congrats banner", "translation": "Bannière de félicitations" } ] }, "cursor": "eyJpZCI6MTAxfQ" @@ -96,16 +96,10 @@ query { "node": { "resourceId": "bc/store/promotion/102", "fields": [ - { - "fieldName": "name", - "original": "Spring Sale", - "translation": null - }, - { - "fieldName": "description", - "original": "Limited time offer", - "translation": null - } + { "fieldName": "banners_availability", "original": "Available banner", "translation": null }, + { "fieldName": "banners_upsell", "original": "Upsell banner", "translation": null }, + { "fieldName": "banners_eligibility", "original": "Eligibility banner", "translation": null }, + { "fieldName": "banners_congratulations", "original": "Congrats banner", "translation": null } ] }, "cursor": "eyJpZCI6MTAyfQ" @@ -182,16 +176,10 @@ query { "node": { "resourceId": "bc/store/promotion/101", "fields": [ - { - "fieldName": "name", - "original": "Holiday Promo", - "translation": "Promotion des fêtes" - }, - { - "fieldName": "description", - "original": "Seasonal discount", - "translation": "Remise saisonnière" - } + { "fieldName": "banners_availability", "original": "Available banner", "translation": "Bannière disponible" }, + { "fieldName": "banners_upsell", "original": "Upsell banner", "translation": "Bannière de montée en gamme" }, + { "fieldName": "banners_eligibility", "original": "Eligibility banner", "translation": "Bannière d'éligibilité" }, + { "fieldName": "banners_congratulations", "original": "Congrats banner", "translation": "Bannière de félicitations" } ] }, "cursor": "eyJpZCI6MTAxfQ" @@ -228,15 +216,19 @@ mutation { { resourceId: "bc/store/promotion/101", fields: [ - { fieldName: "name", value: "Promotion des fêtes" }, - { fieldName: "description", value: "Remise saisonnière" } + { fieldName: "banners_availability", value: "Bannière disponible" }, + { fieldName: "banners_upsell", value: "Bannière de montée en gamme" }, + { fieldName: "banners_eligibility", value: "Bannière d'éligibilité" }, + { fieldName: "banners_congratulations", value: "Bannière de félicitations" } ] }, { resourceId: "bc/store/promotion/102", fields: [ - { fieldName: "name", value: "Vente de printemps" }, - { fieldName: "description", value: "Offre limitée" } + { fieldName: "banners_availability", value: "Bannière disponible" }, + { fieldName: "banners_upsell", value: "Bannière de montée en gamme" }, + { fieldName: "banners_eligibility", value: "Bannière d'éligibilité" }, + { fieldName: "banners_congratulations", value: "Bannière de félicitations" } ] } ] @@ -307,11 +299,19 @@ mutation { resources: [ { resourceId: "bc/store/promotion/101", - fields: ["name", "description"] + fields: [ + "banners_availability", + "banners_upsell", + "banners_eligibility", + "banners_congratulations" + ] }, { resourceId: "bc/store/promotion/102", - fields: ["name"] + fields: [ + "banners_availability", + "banners_upsell" + ] } ] }