From b5e0b91ba5569bdcc90a64f0eccf7377fc1ce60b Mon Sep 17 00:00:00 2001 From: Chris Nowicki Date: Thu, 11 Dec 2025 14:13:36 -0500 Subject: [PATCH 1/3] Add translation docs for payments --- .../translations/payments.mdx | 232 ++++++++++++++++++ 1 file changed, 232 insertions(+) create mode 100644 docs/store-operations/translations/payments.mdx diff --git a/docs/store-operations/translations/payments.mdx b/docs/store-operations/translations/payments.mdx new file mode 100644 index 000000000..db4f2240a --- /dev/null +++ b/docs/store-operations/translations/payments.mdx @@ -0,0 +1,232 @@ +# Translations for Payments (Beta) + +The following entities are translatable for payments: + +- Display Name as `display_name` +- Payment Instruction as `payment_instruction` + +Translations appear in the following storefront views: + +- Checkout page (payment methods listing) +- Order confirmation page +- Order email +- My Account page (payment methods and orders) + +## Resource fields + +For payment method related translation entries, the `resourceId` follows this structure: + +`bc/store/paymentMethod/{payment_method_id}.{currency}` + +| **Segment** | **Description** | +| ------------------------ | -------------------------------------------------------------------- | +| `bc/store/paymentMethod` | Namespace prefix for payment translation resources. | +| `{payment_method_id}` | Payment method identifier (e.g., `authorizenet.credit_card`). | +| `{currency}` | The ISO currency code configured for the payment method (e.g `USD`). | + +A single `resourceId` corresponds to all payment profiles that share the same payment method ID and currency. As a result: + +- Translations apply at the payment method \+ currency level. +- If a provider has multiple profiles (e.g., multiple gateway configurations) using the same payment method ID and same currency, they share the same translation resource. +- Updating the translation updates the display for every profile in that set. + +### Example + +In this example, the payment method is `authorizenet.credit_card` and the currency is `USD`. The translation will be applied to all payment profiles that use the same payment method ID and currency. + +`"resourceId": "bc/store/paymentMethod/authorizenet.credit_card.USD"` + +## Querying Payment Method Translations + +This query retrieves all payment method translations for a specific channel and locale, including the original and translated values for display names and payment instructions. + + + +```graphql +query ListPaymentMethodTranslations { + store { + translations( + filters: { + resourceType: PAYMENT_METHODS + channelId: "bc/store/channel/1" + localeId: "bc/store/locale/en-AU" + } + ) { + edges { + node { + resourceId + fields { + fieldName + original + translation + } + } + cursor + } + pageInfo { + hasNextPage + hasPreviousPage + startCursor + endCursor + } + } + } +} +``` + + +```json +{ + "data": { + "store": { + "translations": { + "edges": [ + { + "node": { + "resourceId": "bc/store/paymentMethod/authorizenet.credit_card.USD", + "fields": [ + { + "fieldName": "display_name", + "original": "Authorize.Net", + "translation": null + }, + { + "fieldName": "payment_instruction", + "original": "", + "translation": null + } + ] + }, + "cursor": "YXV0aG9yaXplbmV0LmNyZWRpdF9jYXJkLlVTRA" + } + ], + "pageInfo": { + "hasNextPage": false, + "hasPreviousPage": false, + "startCursor": "YXV0aG9yaXplbmV0LmNyZWRpdF9jYXJkLlVTRA", + "endCursor": "YXV0aG9yaXplbmV0LmNyZWRpdF9jYXJkLlVTRA" + } + } + } + } +} +``` + + + +## Update a Payment Method Translation + +This mutation updates the translated values for payment method display names and payment instructions for a specific payment method, channel, and locale. + + + +```graphql +mutation UpdatePaymentMethodTranslations { + translation { + updateTranslations( + input: { + resourceType: PAYMENT_METHODS + channelId: "bc/store/channel/1" + localeId: "bc/store/locale/en-AU" + entities: [ + { + resourceId: "bc/store/paymentMethod/authorizenet.credit_card.USD" + fields: [ + { fieldName: "display_name", value: "Translated display" } + { fieldName: "payment_instruction", value: "Translated instrumention" } + ] + } + ] + } + ) { + errors { + __typename + ... on ValidationError { + message + } + ... on EntityNotFoundError { + id + message + } + ... on InvalidTranslationEntityFieldsError { + id + message + fields + } + } + } + } +} +``` + + +```json +{ + "data": { + "translation": { + "updateTranslations": { + "errors": [] + } + } + } +} +``` + + + +## Delete a Payment Method Translation + +This mutation removes translated values for specified payment method fields, reverting them to the original values for a specific payment method, channel, and locale. + + + +```graphql +mutation { + translation { + deleteTranslations( + input: { + resourceType: PAYMENT_METHODS + channelId: "bc/store/channel/1" + localeId: "bc/store/locale/en-AU" + resources: [ + { + resourceId: "bc/store/paymentMethod/authorizenet.credit_card.USD" + fields: ["display_name", "payment_instruction"] + } + ] + } + ) { + errors { + __typename + ... on ValidationError { + message + } + ... on EntityNotFoundError { + id + message + } + ... on InvalidTranslationEntityFieldsError { + id + message + fields + } + } + } + } +} +``` + + +```json +{ + "data": { + "translation": { + "deleteTranslations": { + "errors": [] + } + } + } +} +``` + + From 51c6d2e2e43448c304a6a14dad908cfecb510e66 Mon Sep 17 00:00:00 2001 From: Chris Nowicki Date: Thu, 11 Dec 2025 14:16:30 -0500 Subject: [PATCH 2/3] update translation index to include payments --- docs/store-operations/translations/index.mdx | 33 +++++++++++--------- 1 file changed, 18 insertions(+), 15 deletions(-) diff --git a/docs/store-operations/translations/index.mdx b/docs/store-operations/translations/index.mdx index 639aaf989..2ea508719 100644 --- a/docs/store-operations/translations/index.mdx +++ b/docs/store-operations/translations/index.mdx @@ -1,24 +1,26 @@ # Translations Admin GraphQL API (Beta) - -The Translations Admin GraphQL API is currently available on Catalyst storefronts only. This API enables merchants to translate a single website into multiple languages. +The Translations Admin GraphQL API is currently available on Catalyst storefronts only. This API enables merchants to translate a single website into multiple languages. With a single storefront setup, the shopper's experience remains consistent, but the content is displayed in their preferred language. This use case is particularly common in multilingual countries like Canada and for customers selling cross-border, where the same storefront serves shoppers in multiple languages without altering the overall user experience. The API currently supports translations for the following resource types, and more are expected in the future: -* [Product Data](/docs/store-operations/translations/products) - * Product Options - * Custom Fields -* [Catalog Pages](/docs/store-operations/translations/listings) - * Categories - * Brands -* [Locations](/docs/store-operations/translations/locations) +- [Product Data](/docs/store-operations/translations/products) + - Product Options + - Custom Fields +- [Catalog Pages](/docs/store-operations/translations/listings) + - Categories + - Brands +- [Locations](/docs/store-operations/translations/locations) +- [Payment Methods](/docs/store-operations/translations/payments) Refer to the [Error Handling](/docs/store-operations/translations/errors) guide for understanding and handling errors while managing translations. - -Translation API allows users to add content translations to any non-default channel locale. In order to update content on a default channel language, please use respective management API. + + Translation API allows users to add content translations to any non-default + channel locale. In order to update content on a default channel language, + please use respective management API. ## How does this API work? @@ -38,10 +40,10 @@ Access to the Translations Admin GraphQL API requires valid API credentials. Gra #### OAuth scopes -| Name | Permission | Description | -|:-----|:-----------|:------------| -| Store Translations | read-only | View translation details | -| Store Translations | modify | View and modify translation details | +| Name | Permission | Description | +| :----------------- | :--------- | :---------------------------------- | +| Store Translations | read-only | View translation details | +| Store Translations | modify | View and modify translation details | For more information on OAuth Scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). @@ -71,4 +73,5 @@ For more information on OAuth Scopes, see our [Guide to API Accounts](/docs/star - [Product Translations](/docs/store-operations/translations/products) - [Catalog Page Translations](/docs/store-operations/translations/listings) - [Inventory Locations Translations](/docs/store-operations/translations/locations) +- [Payment Method Translations](/docs/store-operations/translations/payments) - [Error Handling Reference](/docs/store-operations/translations/errors) From 98639b984ecfaa693390d31b364860664482dd68 Mon Sep 17 00:00:00 2001 From: Chris Nowicki Date: Wed, 17 Dec 2025 09:26:01 -0500 Subject: [PATCH 3/3] Added query by resource id --- .../translations/payments.mdx | 73 +++++++++++++++++++ 1 file changed, 73 insertions(+) diff --git a/docs/store-operations/translations/payments.mdx b/docs/store-operations/translations/payments.mdx index db4f2240a..eb5c198bd 100644 --- a/docs/store-operations/translations/payments.mdx +++ b/docs/store-operations/translations/payments.mdx @@ -114,6 +114,79 @@ query ListPaymentMethodTranslations { +## Querying Payment Method Translations by resourceId + + +When querying a translation by `resourceId`, you must provide the full `resourceId` in the format `bc/store/paymentMethod/{payment_method_id}.{currency}`. + + +This query returns a translation by `resourceId`. + + + +```graphql +query { + store { + translations( + filters: { + resourceType: PAYMENT_METHODS + channelId: "bc/store/channel/1" + localeId: "bc/store/locale/en" + resourceIds: [ + "bc/store/paymentMethod/authorizenet.credit_card.USD" + ] + } + ) { + edges { + node { + resourceId + fields { + fieldName + original + translation + } + } + cursor + } + } + } +} +``` + + +```json +{ + "data": { + "store": { + "translations": { + "edges": [ + { + "node": { + "resourceId": "bc/store/paymentMethod/authorizenet.credit_card.USD", + "fields": [ + { + "fieldName": "display_name", + "original": "Authorize.Net", + "translation": null + }, + { + "fieldName": "payment_instruction", + "original": "", + "translation": null + } + ] + }, + "cursor": "YXV0aG9yaXplbmV0LmNyZWRpdF9jYXJkLlVTRA" + } + ] + } + } + } +} +``` + + + ## Update a Payment Method Translation This mutation updates the translated values for payment method display names and payment instructions for a specific payment method, channel, and locale.