Skip to content

Add Order Statuses and Promotions Translation Documentation #1221

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
kristinapototska wants to merge 6 commits into
base: main
Choose a base branch
from
Open

Add Order Statuses and Promotions Translation Documentation #1221

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
bc6af5a
Add Order Statuses and Promotions translation docs
kristinapototska Jan 6, 2026
84fc3eb
Clarify order status IDs are static and link to REST docs
kristinapototska Jan 7, 2026
5bdad7b
Clarify order status IDs and restrict promotion fields
kristinapototska Jan 7, 2026
c1937ca
Merge branch 'main' into CSS-1937-1953-order-statuses-promotions-tran…
kristinapototska Jan 7, 2026
d996ea7
Apply suggestions from code review
bc-terra Jan 29, 2026
489a0b7
Apply suggestions from code review
bc-terra Jan 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions docs/store-operations/translations/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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)
337 changes: 337 additions & 0 deletions docs/store-operations/translations/order-statuses.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,337 @@
# Translations for Order Statuses (Beta)

<Callout type='info'>
The Translations Admin GraphQL API is currently available on Catalyst
storefronts only.
</Callout>

The following entities are translatable for order statuses:

- Label as `label`

<Callout type='info'>
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.
</Callout>

## 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.

<Tabs items={['Request', 'Response']}>
<Tab>

```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: 2
) {
edges {
node {
resourceId
fields {
fieldName
original
translation
}
}
cursor
}
pageInfo {
hasNextPage
hasPreviousPage
startCursor
endCursor
}
}
}
}
```

</Tab>
<Tab>

```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": true,
"hasPreviousPage": false,
"startCursor": "eyJpZCI6MH0",
"endCursor": "eyJpZCI6MX0"
}
}
}
}
}
```

</Tab>
</Tabs>

### 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.

<Tabs items={['Request', 'Response']}>
<Tab>

```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
}
}
}
}
```

</Tab>
<Tab>

```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"
}
]
}
}
}
}
```

</Tab>
</Tabs>

### Update a Translation

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

<Tabs items={['Request', 'Response']}>
<Tab>

```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
}
}
}
}
}
```

</Tab>
<Tab>

```json filename="Example mutation: Update a translation" showLineNumbers copy
{
"data": {
"translation": {
"updateTranslations": {
"__typename": "UpdateTranslationsResult",
"errors": []
}
}
}
}
```

</Tab>
</Tabs>

### 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.

<Tabs items={['Request', 'Response']}>
<Tab>

```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
}
}
}
}
}
```

</Tab>
<Tab>

```json filename="Example mutation: Delete a translation" showLineNumbers copy
{
"data": {
"translation": {
"deleteTranslations": {
"__typename": "DeleteTranslationsResult",
"errors": []
}
}
}
}
```

</Tab>
</Tabs>


Loading