From 0f06843e44bae7d09f1a0a0a4c9aec36391f5358 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A9lanie=20Vistry?= Date: Fri, 27 Mar 2026 12:04:34 +0100 Subject: [PATCH 1/8] Added agents --- .github/agents/Assess-quality.agent.md | 22 ++++++++ .github/agents/Draft.agent.md | 50 ++++++++++++++++++ .github/agents/Plan-doc.agent.md | 71 ++++++++++++++++++++++++++ .github/agents/Review.agent.md | 26 ++++++++++ 4 files changed, 169 insertions(+) create mode 100644 .github/agents/Assess-quality.agent.md create mode 100644 .github/agents/Draft.agent.md create mode 100644 .github/agents/Plan-doc.agent.md create mode 100644 .github/agents/Review.agent.md diff --git a/.github/agents/Assess-quality.agent.md b/.github/agents/Assess-quality.agent.md new file mode 100644 index 000000000..d5913f002 --- /dev/null +++ b/.github/agents/Assess-quality.agent.md @@ -0,0 +1,22 @@ +--- +description: 'Use this custom chatmode to assess the quality of Stitch documentation content based on our writing standards.' +tools: ['search', 'usages', 'problems', 'changes', 'fetch', 'githubRepo'] +--- +# Copilot Chatmode: Stitch Documentation Quality Assessment Agent + +Analyze the content to assess and provide a quality score for each criteria. See Quality scoring Guidelines below. Always refer to CONTRIBUTING.md and existing Stitch documentation for style guidelines, structure, accessibility, terminology standards, and Front Matter conventions. + +### **Quality scoring Guidelines** +Consider all the following criteria and score each factor from 1 to 5: +1. **Linguistic Accuracy** – Correct grammar, spelling, punctuation, and word usage. +2. **Terminology and Style Consistency** – Ensure consistent use of Stitch technical terms and writing style as per repository conventions. +3. **Readability** – Maintain a suitable tone, fluency, and ease of understanding appropriate for Stitch users. +4. **Formatting & Layout** – Detect display issues such as improper Markdown syntax, Front Matter formatting errors, extra spaces, encoding errors, or improper line breaks. +5. **Stitch-Specific Elements** – Proper use of integration types (SaaS, databases, webhooks), terminology (taps, destinations, replication, columns), and product references. + +Numbered score meaning: +- **Score 5**: Excellent – No issues. +- **Score 4**: Good – Minor issues that do not affect comprehension. +- **Score 3**: Acceptable – Noticeable errors but understandable. +- **Score 2**: Poor – Significant issues affecting readability. +- **Score 1**: Unusable – Major errors, incomprehensible content. diff --git a/.github/agents/Draft.agent.md b/.github/agents/Draft.agent.md new file mode 100644 index 000000000..02d2cba5b --- /dev/null +++ b/.github/agents/Draft.agent.md @@ -0,0 +1,50 @@ +--- +description: 'Expert technical writer for Stitch documentation.' +--- +# Copilot Agent: Stitch Technical Writer Agent + +## Overview +This Copilot agent acts as an expert technical writer for Stitch, specializing in software documentation, API documentation, release notes, and conceptual, procedural, and reference content. It analyzes feature code, technical specifications, and SME input to transform technical details into clear, concise, and Stitch-compliant documentation fragments. Leveraging Stitch/Talend expertise, the agent produces high-quality, accessible, and localization-ready documentation in Markdown format with Jekyll Front Matter. + +## Inputs and Outputs +1. **Input Types Supported**: + - Documentation plan generated by Plan.agent.md + - Feature code snippets + - GitHub Pull Requests of product code changes + - Technical specifications + - SME notes/instructions + - Screenshots (with alt text) + - Existing documentation fragments + +2. **Output Format**: + - Use Markdown format with Jekyll Front Matter (YAML) + - Include appropriate front matter fields: `title`, `permalink`, `layout`, `keywords`, `tags` as applicable + - Follow the structure and conventions defined in the Stitch Docs repository + - If no specific format is specified, ask for the target document type before drafting + +## Process for Documentation Requests +For each documentation request (update, addition, or creation): +1. **Analyze the Input**: + - Review the documentation plan + - Review the additional input provided in the chat for relevant information about the product change. +2. **Draft Documentation**: + - Update the documentation based on input and analysis, applying the style, structure, accessibility, localization, and content naming conventions used throughout the Stitch documentation repository + - Match the output structure and markup to the current repository's documentation format (Markdown with Front Matter) + - Use [ASSUMED] placeholders for any missing or ambiguous data, noting these in the follow-up section + - Ensure consistency with existing Stitch documentation patterns and terminology + +## Completion Criteria +- Documentation is clear, concise, and compliant with Stitch documentation standards +- All style/accessibility/legal gates satisfied or issues flagged +- Front Matter is properly formatted +- Markdown is properly formatted and follows Stitch conventions + +## Safety and Boundaries +- Refuse requests for non-documentation, speculative, or harmful content +- Never invent unsupported product features, endpoints, or version numbers +- Never commit secrets or sensitive information + +## Example Prompts +- "Draft integration documentation from this API spec for a new SaaS connector." +- "Update this destination setup documentation using the product changes in this PR." +- "Add a troubleshooting section based on these support tickets and feature changes." diff --git a/.github/agents/Plan-doc.agent.md b/.github/agents/Plan-doc.agent.md new file mode 100644 index 000000000..2f524e9c2 --- /dev/null +++ b/.github/agents/Plan-doc.agent.md @@ -0,0 +1,71 @@ +--- +description: 'Expert information architect and technical writer for Stitch documentation.' +--- +# Copilot Agent: Stitch Documentation Planning Agent + +## Overview +This Copilot agent acts as an expert information architect and technical writer for Stitch, specializing in Stitch products and technical documentation. It analyzes feature code, technical specifications, and SME input to transform technical details into a useful documentation plan. + +## Inputs + - Product change descriptions provided as pasted information from Jira or GitHub issues + - Feature code snippets + - GitHub Pull Requests of product code changes + - Technical specifications + - SME notes/instructions + - Screenshots with alt text + - Existing documentation fragments + +## Process for Documentation Requests +For each request (update, addition, or creation of documentation): +1. **Analyze the input**: + - Review the provided code/spec/SME notes from the chat for relevant information about the product change. +2. **Answer the documentation design review questions**: + - Provide clear and concise answers to the following: + - What is the value proposition ("why") of this functionality? + - Which primary personas are affected and what are their needs? + - How does this feature fit into the user's broader workflow or other tasks? + - Are there prerequisites or environment dependencies? + - Does this feature introduce new terms, new glossary entries, or impact existing terms? + - Is there a real-life end-to-end example to include? + - Are there unhappy paths (errors) and how are they addressed? + - What existing content needs updating? Identify affected content in the current repository: topics, tutorials, integration guides, TOC entries, terminology, dependencies, etc, by searching the repository for existing content related to the feature. + - How do new/updated topics fit into the helpsite architecture? Review existing relevant content folders in this repository to understand table of contents placement (e.g., `_saas-integrations/`, `_database-integrations/`, `_destinations/`, `_replication/`, `_getting-started/`). + - Are there content dependencies (other writers, UI/UX gaps, feature phasing...) to consider? + + ### Finding Impacted Documentation (Search Strategy) + When identifying what existing content needs updating: + + 1. **Search for precise identifiers**: + - Identify the most precise identifier(s) relevant to the change (e.g., integration name, feature name, destination type) + - Search for multiple term variations + - Use both literal/exact search (grep_search) and natural-language/semantic search to catch synonyms, renamed concepts, and documentation that doesn't share exact strings + + 2. **Review all high-priority candidates systematically**: + - When search returns multiple matches, read and analyze all matching files—the first good match may not capture all relevant documentation + + 3. **Know when to stop**: + - Stop when both search modes yield no new high-priority candidates or duplicative results + +3. **Create a documentation plan**: + - Provide a concise outline of the proposed documentation changes, including: + - List of existing topics to update + - If new topics are needed, topic titles and key points to cover in each topic + - At least two proposed structures that take into account existing content models and helpsite architecture + - Dependencies + +## Safety and Boundaries +- Refuse requests for non-documentation, speculative, or harmful content +- Never invent unsupported product features, endpoints, or version numbers +- Insert [ASSUMED] placeholders for missing but required data + +## Next Steps: Implementation +Once the plan is reviewed and approved, run the **Draft agent** to implement the documentation. In VS Code, attach the plan in the chat and invoke the Draft agent with this prompt: + +``` +Draft the documentation changes outlined in this plan. +Here is the approved plan: +[Paste the Plan agent's output here if not already attached to the chat] + +Additional context about the product change: +[Paste relevant code snippets, SME notes, or technical specifications here] +``` diff --git a/.github/agents/Review.agent.md b/.github/agents/Review.agent.md new file mode 100644 index 000000000..9259edc81 --- /dev/null +++ b/.github/agents/Review.agent.md @@ -0,0 +1,26 @@ +--- +description: 'Use this custom chatmode to review and improve Stitch documentation content.' +tools: ['edit', 'search', 'usages', 'problems', 'fetch', 'githubRepo'] +--- +# Copilot Chatmode: Stitch Technical Writer Reviewer Agent + +## Overview +Review and improve documentation content for Stitch. Refer to CONTRIBUTING.md and existing Stitch documentation patterns for style guidelines, structure, accessibility, and terminology standards. + +## Review Process +When asked to review content, provide output in this structure: +1. **Summary**: One concise sentence summarizing issues found. +2. **Issues**: Issues ordered by impact (group under: Style, Clarity, Structure, Terminology, Accessibility, Front Matter/Formatting, Other). +3. **Improve content**: Apply all fixes directly using the Replace tool. +4. **(optional) Follow-up**: Open questions and [ASSUMED] items. + +## Key Review Areas +- **Markdown Syntax**: Verify proper Markdown formatting +- **Front Matter**: Validate YAML correctness, required fields (title, permalink, layout), and proper formatting +- **Style Consistency**: Match existing Stitch documentation tone and conventions +- **Terminology**: Ensure consistency with Stitch product terminology (integrations, taps, destinations, replication, etc.) +- **Navigation**: Verify internal links work with correct permalink structure +- **Clarity**: Ensure instructions are step-by-step and easy to follow + +## Safety: +- Refuse requests for non-documentation or speculative reviews. From e72b26ea0656d8a177fe3c135fc6e8dd7b9913f1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A9lanie=20Vistry?= Date: Fri, 27 Mar 2026 14:33:32 +0100 Subject: [PATCH 2/8] Updated doc --- .../sources/saas/shopify-object.md | 26 +++-- _saas-integrations/shopify/v3/shopify-v3.md | 97 +++++++++++++++++-- 2 files changed, 110 insertions(+), 13 deletions(-) diff --git a/_developer-files/connect/api/objects/form-properties/sources/saas/shopify-object.md b/_developer-files/connect/api/objects/form-properties/sources/saas/shopify-object.md index dc387b6ef..f65736294 100644 --- a/_developer-files/connect/api/objects/form-properties/sources/saas/shopify-object.md +++ b/_developer-files/connect/api/objects/form-properties/sources/saas/shopify-object.md @@ -62,19 +62,31 @@ object-attributes: # -------------------------- # -# OAUTH PROPERTIES # +# CLIENT CREDENTIALS PROPERTIES # # -------------------------- # -oauth-link: "https://shopify.dev/tutorials/authenticate-with-oauth#the-oauth-flow" +client-credentials-link: "https://shopify.dev/docs/apps/build/authentication-authorization/access-tokens/client-credentials-grant" -oauth-description: "" +client-credentials-description: "Client Credentials authentication uses a custom app created in your {{ form-property.display-name }} Developer Dashboard." -oauth-attributes: - - name: "api_key" +client-credentials-attributes: + - name: "client_id" type: "string" required: true credential: true description: | - The API key for your {{ form-property.display-name }} shop, generated via an OAuth handshake. - value: "" + The Client ID for your {{ form-property.display-name }} custom app. + + You'll find this in your custom app's **API credentials** section in the {{ form-property.display-name }} Developer Dashboard. + value: "" + + - name: "client_secret" + type: "string" + required: true + credential: true + description: | + The Client Secret for your {{ form-property.display-name }} custom app. + + You'll find this in your custom app's **API credentials** section in the {{ form-property.display-name }} Developer Dashboard. Store this securely—it's only visible once after initial creation. + value: "" --- \ No newline at end of file diff --git a/_saas-integrations/shopify/v3/shopify-v3.md b/_saas-integrations/shopify/v3/shopify-v3.md index 06635e04a..e995b286d 100644 --- a/_saas-integrations/shopify/v3/shopify-v3.md +++ b/_saas-integrations/shopify/v3/shopify-v3.md @@ -83,11 +83,15 @@ feature-summary: | requirements-list: - item: | - **Admin access in {{ integration.display_name }}**. This is required to allow Stitch to replicate data. + **Admin access in {{ integration.display_name }}**. This is required to create and manage custom apps. - **Note: If you're on a {{ integration.display_name }} Plus plan**, the permissions required may differ. Store owners can grant users permissions to export orders, draft orders, products, inventory, and customer data. In general, **view-level** permissions should be sufficient. + **Note: If you're on a {{ integration.display_name }} Plus plan**, the permissions required may differ. Store owners can grant users permissions to manage apps and custom integrations. In general, **app management** permissions should be sufficient. Refer to the [{{ integration.display_name }} Staff permissions documentation](https://help.shopify.com/en/manual/your-account/staff-accounts/staff-permissions#store-owner-permissions){:target="new"} for more information. + - item: | + **Access to {{ integration.display_name }} Developer Dashboard** with app management permissions. You'll use this to create a custom app and generate credentials. + - item: | + **Note:** Access tokens refresh automatically every 24 hours and are managed server-side by Stitch. You don't need to manually refresh your credentials. setup-steps: - title: "Add {{ integration.display_name }} as a Stitch data source" @@ -105,13 +109,94 @@ setup-steps: content: | {% include integrations/shared-setup/replication-frequency.html %} + - title: "Create a {{ integration.display_name }} custom app" + anchor: "create-shopify-custom-app" + content: | + A custom app allows you to securely generate credentials that Stitch will use to authenticate and replicate data from your {{ integration.display_name }} store. + + **To create a custom app:** + + 1. Log into your [{{ integration.display_name }} Admin Dashboard](https://admin.shopify.com){:target="new"}. + 2. In the sidebar, go to **Settings** > **Apps and integrations**. + 3. Click **Develop apps** (or **App and sales channel settings** if using Shopify Plus). + 4. Click **Create an app**. + 5. Enter a name for your app (for example: `Stitch`). + 6. Click **Create app**. + 7. In the **Configuration** tab, click **Admin API access scopes**. + 8. Select the following required scopes: + + | Scope | Purpose | + |-------|---------| + | `read_orders` | Replicate order data | + | `read_all_orders` | Replicate historical order data | + | `read_customers` | Replicate customer information | + | `read_products` | Replicate product catalog | + | `read_checkouts` | Replicate checkout data | + | `read_inventory` | Replicate inventory levels | + | `read_locations` | Replicate store locations | + | `read_assigned_fulfillment_orders` | Replicate assigned fulfillment orders | + | `read_merchant_managed_fulfillment_orders` | Replicate merchant-managed fulfillment orders | + | `read_third_party_fulfillment_orders` | Replicate third-party fulfillment orders | + + 9. Click **Save**. + 10. In the **API credentials** tab, under **Admin API access token**, click **Reveal token once**. + 11. You'll see your **Client ID** and **Client Secret**. Store these securely—you'll need them in the next step. + + {% include warning.html content="Your Client Secret will only be visible once after initial creation. Store it securely before navigating away." %} + + 12. Click **Install app**. + - title: "Authorize Stitch to access {{ integration.display_name }}" anchor: "grant-stitch-authorization" content: | - 1. Next, you'll be prompted to sign into your {{ integration.display_name }} account. Enter your {{ integration.display_name }} credentials. - 2. Click **Log in**. - 3. After the authorization process is successfully completed, you'll be directed back to Stitch. - 4. Click {{ app.buttons.finish-int-setup }}. + Next, you'll enter your {{ integration.display_name }} credentials into Stitch. You'll use the credentials from the custom app you created in the previous step. + + **Choose the setup path that matches your situation:** + + - [For individual store owners](#for-individual-store-owners) + - [For multiple stores in the same organization ({{ integration.display_name }} Plus)](#for-multiple-stores) + - [For {{ integration.display_name }} Partners](#for-shopify-partners) + + #### For individual store owners {#for-individual-store-owners} + + **When to use this path:** You own a single {{ integration.display_name }} store and are connecting it directly to Stitch. + + 1. In Stitch, enter the following information from your custom app: + - **Shop:** Your store name without the domain. For example, if your store URL is `stitch-data.shopify.com`, enter `stitch-data`. + - **Client ID:** Paste your Client ID from the custom app's **API credentials** section. + - **Client Secret:** Paste your Client Secret from the custom app's **API credentials** section. + 2. Click {{ app.buttons.finish-int-setup }}. + + #### For multiple stores in the same organization ({{ integration.display_name }} Plus) {#for-multiple-stores} + + **When to use this path:** You have multiple {{ integration.display_name }} stores within your organization (Shopify Plus plan) and want to use a single app for all of them. + + **Important:** The app is organization-scoped. Stores outside your organization will require a separate app. + + 1. Follow the steps in [Create a {{ integration.display_name }} custom app](#create-shopify-custom-app) to create a single app. + 2. In your {{ integration.display_name }} Admin Dashboard, go to **Settings** > **Apps and integrations** > **Develop apps**. + 3. For each store you want to connect: + - Switch to that store's Admin Dashboard context (if not already there). + - Note the store's handle (shop name). + 4. In Stitch, create a separate connection for each store, entering: + - **Shop:** The store's handle (shop name). + - **Client ID:** Paste your Client ID from the shared custom app. + - **Client Secret:** Paste your Client Secret from the shared custom app. + 5. Click {{ app.buttons.finish-int-setup }} for each connection. + + #### For {{ integration.display_name }} Partners {#for-shopify-partners} + + **When to use this path:** You're a {{ integration.display_name }} Partner creating apps for your clients' stores, or you're a client of a partner agency. + + 1. As a partner, create your custom app via [partners.shopify.com](https://partners.shopify.com){:target="new"} with **Custom distribution** selected. + 2. Generate an installation link for your client (the link expires after 7 days). + 3. The client accesses the installation link and installs the app to their store. + 4. Provide the client with the **Client ID** and **Client Secret** from the app's **API credentials** section. + 5. The client enters the following information in Stitch: + - **Shop:** Their store handle (shop name). + - **Client ID:** The Client ID provided by their partner. + - **Client Secret:** The Client Secret provided by their partner. + 6. Click {{ app.buttons.finish-int-setup }}. - title: "Set objects to replicate" anchor: "setting-data-to-replicate" From ceb036c53bc372191bfbc0e6ab4dd5e48bc3603f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A9lanie=20Vistry?= Date: Fri, 27 Mar 2026 14:46:24 +0100 Subject: [PATCH 3/8] Deleted quality agent --- .github/agents/Assess-quality.agent.md | 22 ---------------------- 1 file changed, 22 deletions(-) delete mode 100644 .github/agents/Assess-quality.agent.md diff --git a/.github/agents/Assess-quality.agent.md b/.github/agents/Assess-quality.agent.md deleted file mode 100644 index d5913f002..000000000 --- a/.github/agents/Assess-quality.agent.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -description: 'Use this custom chatmode to assess the quality of Stitch documentation content based on our writing standards.' -tools: ['search', 'usages', 'problems', 'changes', 'fetch', 'githubRepo'] ---- -# Copilot Chatmode: Stitch Documentation Quality Assessment Agent - -Analyze the content to assess and provide a quality score for each criteria. See Quality scoring Guidelines below. Always refer to CONTRIBUTING.md and existing Stitch documentation for style guidelines, structure, accessibility, terminology standards, and Front Matter conventions. - -### **Quality scoring Guidelines** -Consider all the following criteria and score each factor from 1 to 5: -1. **Linguistic Accuracy** – Correct grammar, spelling, punctuation, and word usage. -2. **Terminology and Style Consistency** – Ensure consistent use of Stitch technical terms and writing style as per repository conventions. -3. **Readability** – Maintain a suitable tone, fluency, and ease of understanding appropriate for Stitch users. -4. **Formatting & Layout** – Detect display issues such as improper Markdown syntax, Front Matter formatting errors, extra spaces, encoding errors, or improper line breaks. -5. **Stitch-Specific Elements** – Proper use of integration types (SaaS, databases, webhooks), terminology (taps, destinations, replication, columns), and product references. - -Numbered score meaning: -- **Score 5**: Excellent – No issues. -- **Score 4**: Good – Minor issues that do not affect comprehension. -- **Score 3**: Acceptable – Noticeable errors but understandable. -- **Score 2**: Poor – Significant issues affecting readability. -- **Score 1**: Unusable – Major errors, incomprehensible content. From bf6b98aed91affdfa04eaaff2fa5c1863a09ec3d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A9lanie=20Vistry?= Date: Fri, 27 Mar 2026 15:01:47 +0100 Subject: [PATCH 4/8] Review by the Review agent --- _saas-integrations/shopify/v3/shopify-v3.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_saas-integrations/shopify/v3/shopify-v3.md b/_saas-integrations/shopify/v3/shopify-v3.md index e995b286d..a8d7b5b48 100644 --- a/_saas-integrations/shopify/v3/shopify-v3.md +++ b/_saas-integrations/shopify/v3/shopify-v3.md @@ -62,10 +62,10 @@ feature-summary: | Stitch's {{ integration.display_name }} integration replicates data using the {{ integration.api | flatify | strip }}. Refer to the [Schema](#schema) section for a list of objects available for replication. #### {{ integration.display_name }} is now powered by GraphQL - We've have enhanced the Stitch's {{ integration.display_name }} integration by replacing REST Admin API by the {{ integration.display_name }} GraphQL API. + We've enhanced the Stitch's {{ integration.display_name }} integration by replacing REST Admin API by the {{ integration.display_name }} GraphQL API. This provides: - More structured and complete data - - Better performance and scalibility + - Better performance and scalability - Access to new fields that are unavailable in REST #### What has changed? From 8cd4e72651874c63b6b1f35a424f48de458f36df Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A9lanie=20Vistry?= Date: Fri, 27 Mar 2026 15:21:23 +0100 Subject: [PATCH 5/8] Fixed a procedure --- _saas-integrations/shopify/v3/shopify-v3.md | 28 ++++++++++----------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/_saas-integrations/shopify/v3/shopify-v3.md b/_saas-integrations/shopify/v3/shopify-v3.md index a8d7b5b48..ee3b918c1 100644 --- a/_saas-integrations/shopify/v3/shopify-v3.md +++ b/_saas-integrations/shopify/v3/shopify-v3.md @@ -125,22 +125,22 @@ setup-steps: 7. In the **Configuration** tab, click **Admin API access scopes**. 8. Select the following required scopes: - | Scope | Purpose | - |-------|---------| - | `read_orders` | Replicate order data | - | `read_all_orders` | Replicate historical order data | - | `read_customers` | Replicate customer information | - | `read_products` | Replicate product catalog | - | `read_checkouts` | Replicate checkout data | - | `read_inventory` | Replicate inventory levels | - | `read_locations` | Replicate store locations | - | `read_assigned_fulfillment_orders` | Replicate assigned fulfillment orders | - | `read_merchant_managed_fulfillment_orders` | Replicate merchant-managed fulfillment orders | - | `read_third_party_fulfillment_orders` | Replicate third-party fulfillment orders | + | Scope | Purpose | + |-------|---------| + | `read_orders` | Replicate order data | + | `read_all_orders` | Replicate historical order data | + | `read_customers` | Replicate customer information | + | `read_products` | Replicate product catalog | + | `read_checkouts` | Replicate checkout data | + | `read_inventory` | Replicate inventory levels | + | `read_locations` | Replicate store locations | + | `read_assigned_fulfillment_orders` | Replicate assigned fulfillment orders | + | `read_merchant_managed_fulfillment_orders` | Replicate merchant-managed fulfillment orders | + | `read_third_party_fulfillment_orders` | Replicate third-party fulfillment orders | 9. Click **Save**. - 10. In the **API credentials** tab, under **Admin API access token**, click **Reveal token once**. - 11. You'll see your **Client ID** and **Client Secret**. Store these securely—you'll need them in the next step. + 10. In the **API credentials** tab, under **Admin API access token**, click **Reveal token once**. You'll see your **Client ID** and **Client Secret**. + 11. Store these credentials securely. You need them in the next step. {% include warning.html content="Your Client Secret will only be visible once after initial creation. Store it securely before navigating away." %} From b76154880def9f653f3ae0fda8e83585890d02c3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A9lanie=20Vistry?= Date: Mon, 13 Apr 2026 11:05:45 +0200 Subject: [PATCH 6/8] Review --- _saas-integrations/shopify/v3/shopify-v3.md | 89 ++++++++------------- 1 file changed, 32 insertions(+), 57 deletions(-) diff --git a/_saas-integrations/shopify/v3/shopify-v3.md b/_saas-integrations/shopify/v3/shopify-v3.md index ee3b918c1..fb72a2cf6 100644 --- a/_saas-integrations/shopify/v3/shopify-v3.md +++ b/_saas-integrations/shopify/v3/shopify-v3.md @@ -99,16 +99,6 @@ setup-steps: content: | {% include integrations/shared-setup/connection-setup.html %} - - title: "Define the historical replication start date" - anchor: "define-historical-sync" - content: | - {% include integrations/saas/setup/historical-sync.html %} - - - title: "Create a replication schedule" - anchor: "define-rep-frequency" - content: | - {% include integrations/shared-setup/replication-frequency.html %} - - title: "Create a {{ integration.display_name }} custom app" anchor: "create-shopify-custom-app" content: | @@ -123,7 +113,8 @@ setup-steps: 5. Enter a name for your app (for example: `Stitch`). 6. Click **Create app**. 7. In the **Configuration** tab, click **Admin API access scopes**. - 8. Select the following required scopes: + 8. Select or copy-paste the following required scopes: + `read_orders`,`read_all_orders`,`read_customers`,`read_products`,`read_checkouts`,`read_inventory`,`read_locations`,`read_assigned_fulfillment_orders`,`read_merchant_managed_fulfillment_orders`,`read_third_party_fulfillment_orders`. | Scope | Purpose | |-------|---------| @@ -140,63 +131,47 @@ setup-steps: 9. Click **Save**. 10. In the **API credentials** tab, under **Admin API access token**, click **Reveal token once**. You'll see your **Client ID** and **Client Secret**. - 11. Store these credentials securely. You need them in the next step. - - {% include warning.html content="Your Client Secret will only be visible once after initial creation. Store it securely before navigating away." %} - + 11. Store these credentials securely. You need them in the next step. Your Client Secret will only be visible once after initial creation. Store it securely before navigating away. 12. Click **Install app**. - - title: "Authorize Stitch to access {{ integration.display_name }}" - anchor: "grant-stitch-authorization" + - title: "Request access from Shopify" + anchor: "request-access-from-shopify" content: | - Next, you'll enter your {{ integration.display_name }} credentials into Stitch. You'll use the credentials from the custom app you created in the previous step. + To access certain {{ integration.display_name }} API scopes, you must request access from {{ integration.display_name }} before installing your custom app. The following scopes require explicit approval: - **Choose the setup path that matches your situation:** + ##### `read_all_orders` scope - - [For individual store owners](#for-individual-store-owners) - - [For multiple stores in the same organization ({{ integration.display_name }} Plus)](#for-multiple-stores) - - [For {{ integration.display_name }} Partners](#for-shopify-partners) + By default, you only have access to the last 60 days of orders. To access all historical orders, you must request the `read_all_orders` scope in the {{ integration.display_name }} Partners dashboard. - #### For individual store owners {#for-individual-store-owners} + **To request the `read_all_orders` scope:** - **When to use this path:** You own a single {{ integration.display_name }} store and are connecting it directly to Stitch. + 1. Go to the [{{ integration.display_name }} Partners dashboard](https://partners.shopify.com/){:target="new"}. + 2. Navigate to **Apps** and select your app. + 3. Open the **API access requests** section. + 4. In the **Read all orders** section, click **Request access**. + 5. In the access request justification, specify that the app needs full read-only access to historical orders for long-term analytics, reconciliation, and reporting. + 6. Submit the request and wait for {{ integration.display_name }} approval. - 1. In Stitch, enter the following information from your custom app: - - **Shop:** Your store name without the domain. For example, if your store URL is `stitch-data.shopify.com`, enter `stitch-data`. - - **Client ID:** Paste your Client ID from the custom app's **API credentials** section. - - **Client Secret:** Paste your Client Secret from the custom app's **API credentials** section. - 2. Click {{ app.buttons.finish-int-setup }}. + After {{ integration.display_name }} approves the request, you can add the `read_all_orders` scope to your app scope list. If the app was already installed before this permission was granted, you must uninstall and reinstall the app for the new scope to take effect. - #### For multiple stores in the same organization ({{ integration.display_name }} Plus) {#for-multiple-stores} + ##### `read_users` scope - **When to use this path:** You have multiple {{ integration.display_name }} stores within your organization (Shopify Plus plan) and want to use a single app for all of them. + To use the `read_users` scope, one of the following conditions must be true: - **Important:** The app is organization-scoped. Stores outside your organization will require a separate app. + - The app must be a finance embedded app. + - The app must be installed on a {{ integration.display_name }} Plus or Advanced store. - 1. Follow the steps in [Create a {{ integration.display_name }} custom app](#create-shopify-custom-app) to create a single app. - 2. In your {{ integration.display_name }} Admin Dashboard, go to **Settings** > **Apps and integrations** > **Develop apps**. - 3. For each store you want to connect: - - Switch to that store's Admin Dashboard context (if not already there). - - Note the store's handle (shop name). - 4. In Stitch, create a separate connection for each store, entering: - - **Shop:** The store's handle (shop name). - - **Client ID:** Paste your Client ID from the shared custom app. - - **Client Secret:** Paste your Client Secret from the shared custom app. - 5. Click {{ app.buttons.finish-int-setup }} for each connection. + Contact {{ integration.display_name }} Support to enable this scope if required. - #### For {{ integration.display_name }} Partners {#for-shopify-partners} - - **When to use this path:** You're a {{ integration.display_name }} Partner creating apps for your clients' stores, or you're a client of a partner agency. - - 1. As a partner, create your custom app via [partners.shopify.com](https://partners.shopify.com){:target="new"} with **Custom distribution** selected. - 2. Generate an installation link for your client (the link expires after 7 days). - 3. The client accesses the installation link and installs the app to their store. - 4. Provide the client with the **Client ID** and **Client Secret** from the app's **API credentials** section. - 5. The client enters the following information in Stitch: - - **Shop:** Their store handle (shop name). - - **Client ID:** The Client ID provided by their partner. - - **Client Secret:** The Client Secret provided by their partner. - 6. Click {{ app.buttons.finish-int-setup }}. + - title: "Define the historical replication start date" + anchor: "define-historical-sync" + content: | + {% include integrations/saas/setup/historical-sync.html %} + + - title: "Create a replication schedule" + anchor: "define-rep-frequency" + content: | + {% include integrations/shared-setup/replication-frequency.html %} - title: "Set objects to replicate" anchor: "setting-data-to-replicate" @@ -209,8 +184,8 @@ setup-steps: replication-sections: - title: "Replicating order refunds" - - anchor: "order-refunds" - - content: | + anchor: "order-refunds" + content: | To extract order refund data, Stitch queries every order in your account. If you have the `order_refunds` table selected for replication, the process can potentially be very slow depending on how many orders and refunds exist in your {{ integration.display_name }} account. As tables are extracted one at a time, this could cause extraction to not proceed for days at a time. To ensure timely replication of your other selected tables, consider creating a separate integration for only the `order_refunds` table. **Note**: Creating a separate integration for your `order_refunds` table may negatively affect your {{ integration.display_name }} API quota. From 5af339598fd811cb89e6f623216b1b393550e504 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A9lanie=20Vistry?= Date: Mon, 13 Apr 2026 11:16:25 +0200 Subject: [PATCH 7/8] Syntax --- _saas-integrations/shopify/v3/shopify-v3.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/_saas-integrations/shopify/v3/shopify-v3.md b/_saas-integrations/shopify/v3/shopify-v3.md index fb72a2cf6..9cb463461 100644 --- a/_saas-integrations/shopify/v3/shopify-v3.md +++ b/_saas-integrations/shopify/v3/shopify-v3.md @@ -114,7 +114,8 @@ setup-steps: 6. Click **Create app**. 7. In the **Configuration** tab, click **Admin API access scopes**. 8. Select or copy-paste the following required scopes: - `read_orders`,`read_all_orders`,`read_customers`,`read_products`,`read_checkouts`,`read_inventory`,`read_locations`,`read_assigned_fulfillment_orders`,`read_merchant_managed_fulfillment_orders`,`read_third_party_fulfillment_orders`. + `read_orders`,`read_all_orders`,`read_customers`,`read_products`,`read_checkouts`,`read_inventory`,`read_locations`, + `read_assigned_fulfillment_orders`,`read_merchant_managed_fulfillment_orders`,`read_third_party_fulfillment_orders`. | Scope | Purpose | |-------|---------| From c130dbf4adee9499d1d71230b0bdf4fcc8f23ea8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A9lanie=20Vistry?= Date: Mon, 13 Apr 2026 13:49:15 +0200 Subject: [PATCH 8/8] Rearranged steps --- _saas-integrations/shopify/v3/shopify-v3.md | 58 ++++++++++----------- 1 file changed, 29 insertions(+), 29 deletions(-) diff --git a/_saas-integrations/shopify/v3/shopify-v3.md b/_saas-integrations/shopify/v3/shopify-v3.md index 9cb463461..096884b1a 100644 --- a/_saas-integrations/shopify/v3/shopify-v3.md +++ b/_saas-integrations/shopify/v3/shopify-v3.md @@ -99,6 +99,35 @@ setup-steps: content: | {% include integrations/shared-setup/connection-setup.html %} + - title: "Request access from Shopify" + anchor: "request-access-from-shopify" + content: | + To access certain {{ integration.display_name }} API scopes, you must request access from {{ integration.display_name }} before installing your custom app. The following scopes require explicit approval: + + ##### `read_all_orders` scope + + By default, you only have access to the last 60 days of orders. To access all historical orders, you must request the `read_all_orders` scope in the {{ integration.display_name }} Partners dashboard. + + **To request the `read_all_orders` scope:** + + 1. Go to the [{{ integration.display_name }} Partners dashboard](https://partners.shopify.com/){:target="new"}. + 2. Navigate to **Apps** and select your app. + 3. Open the **API access requests** section. + 4. In the **Read all orders** section, click **Request access**. + 5. In the access request justification, specify that the app needs full read-only access to historical orders for long-term analytics, reconciliation, and reporting. + 6. Submit the request and wait for {{ integration.display_name }} approval. + + After {{ integration.display_name }} approves the request, you can add the `read_all_orders` scope to your app scope list. If the app was already installed before this permission was granted, you must uninstall and reinstall the app for the new scope to take effect. + + ##### `read_users` scope + + To use the `read_users` scope, one of the following conditions must be true: + + - The app must be a finance embedded app. + - The app must be installed on a {{ integration.display_name }} Plus or Advanced store. + + Contact {{ integration.display_name }} Support to enable this scope if required. + - title: "Create a {{ integration.display_name }} custom app" anchor: "create-shopify-custom-app" content: | @@ -135,35 +164,6 @@ setup-steps: 11. Store these credentials securely. You need them in the next step. Your Client Secret will only be visible once after initial creation. Store it securely before navigating away. 12. Click **Install app**. - - title: "Request access from Shopify" - anchor: "request-access-from-shopify" - content: | - To access certain {{ integration.display_name }} API scopes, you must request access from {{ integration.display_name }} before installing your custom app. The following scopes require explicit approval: - - ##### `read_all_orders` scope - - By default, you only have access to the last 60 days of orders. To access all historical orders, you must request the `read_all_orders` scope in the {{ integration.display_name }} Partners dashboard. - - **To request the `read_all_orders` scope:** - - 1. Go to the [{{ integration.display_name }} Partners dashboard](https://partners.shopify.com/){:target="new"}. - 2. Navigate to **Apps** and select your app. - 3. Open the **API access requests** section. - 4. In the **Read all orders** section, click **Request access**. - 5. In the access request justification, specify that the app needs full read-only access to historical orders for long-term analytics, reconciliation, and reporting. - 6. Submit the request and wait for {{ integration.display_name }} approval. - - After {{ integration.display_name }} approves the request, you can add the `read_all_orders` scope to your app scope list. If the app was already installed before this permission was granted, you must uninstall and reinstall the app for the new scope to take effect. - - ##### `read_users` scope - - To use the `read_users` scope, one of the following conditions must be true: - - - The app must be a finance embedded app. - - The app must be installed on a {{ integration.display_name }} Plus or Advanced store. - - Contact {{ integration.display_name }} Support to enable this scope if required. - - title: "Define the historical replication start date" anchor: "define-historical-sync" content: |