Appstore

1. Overview

The Appstore tool provides an interface to the Apple App Store Connect API, allowing developers to programmatically manage their app's customer reviews. It enables direct interaction with review data, facilitating automated monitoring, analysis, and response workflows.

With the GoInsight Appstore node, you can integrate customer feedback management directly into your automated processes. This includes:

• Fetching and Listing Reviews: Retrieve a list of all customer reviews for your app, with powerful filtering and sorting capabilities. You can also fetch the complete details of a single, specific review by its ID.
• Responding to Reviews: Engage with your users by programmatically posting developer responses to their reviews.

2. Prerequisites

Before using this node, you need to have a valid Apple Developer account with access to App Store Connect. You will also need appropriate permissions (such as Admin or App Manager) to generate the necessary API keys for authentication.

3. Credentials

For a detailed guide on how to obtain and configure credentials, please refer to our official documentation: Credentials Configuration Guide.

4. Supported Operations

Summary

This node primarily operates on the Review resource, allowing you to manage and interact with customer feedback on the Apple App Store.

Operation Details

Get a Review

Retrieve detailed information for a specific customer review from Apple App Store Connect using API Key authentication. This tool allows you to fetch complete review details including rating, content, reviewer information, and optional developer response for a single review by its ID.

Input Parameters:

• ReviewId: The unique identifier of the customer review to retrieve. How to get ReviewId: Call the List Reviews action (appstore_review_list tool) to retrieve all review IDs for your app. The review ID is returned in the 'Id' field of each review. Example: '12345abcdef67890'.

Options:

• IncludeResponse: Whether to include the developer's reply to this review in the result (default: true). When true, response fields (ResponseId, ResponseBody, ResponseState, ResponseLastModifiedDate) will be populated if a developer reply exists.

Output:

• Id (string): Unique identifier for the review
• Title (string): Title/headline of the review
• Body (string): Full text content of the customer's review
• Rating (number): Star rating given by the reviewer (1-5 stars)
• CreatedDate (string): ISO 8601 timestamp when the review was created
• Territory (string): Country/territory code where the review was submitted
• ReviewerNickname (string): Display name chosen by the reviewer
• AppStoreVersionId (string): Unique identifier of the app version being reviewed
• ResponseId (string): Unique identifier for the developer response
• ResponseBody (string): Text content of the developer's reply to the review
• ResponseLastModifiedDate (string): ISO 8601 timestamp when the response was last modified
• ResponseState (string): Current publication state of the developer response. Possible values: PUBLISHED (response is publicly visible to all users on the App Store), PENDING_PUBLISH (response has been submitted but is awaiting Apple's review before becoming visible, typically takes 24-48 hours), DELETED (response has been removed by the developer). Empty string if no developer response exists.
• OriginalStatusCode (number): The original HTTP status code returned by the Apple App Store Connect API. Default 0 means the request did not reach upstream (e.g., timeout or exception). Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (network timeout/connection failure).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

List Reviews

Retrieve a list of customer reviews for a specific app from Apple App Store Connect using API Key authentication. This tool allows you to fetch customer reviews including ratings, review content, reviewer information, and optional developer responses with filtering, sorting, and pagination capabilities.

Input Parameters:

• AppId: The Apple numeric app ID (required). This is the unique numeric identifier for your app in the App Store. How to find: 1) In App Store Connect, go to your app's General > App Information page, the Apple ID is shown at the top. 2) On the App Store URL: apps.apple.com/app/id — the number after 'id' is the AppId. Example: '1234567890'.

Options:

• Limit: Maximum number of reviews to return per request (1-200, default: 50). Use with NextLink for pagination to retrieve all reviews.
• FilterRating: Filter reviews by a specific star rating (optional). Accepts a single integer value from 1 to 5. Examples: '5' (only 5-star reviews), '1' (only 1-star reviews). Leave empty to return reviews of all ratings.
• FilterTerritory: Filter reviews by country/territory code (optional). Uses ISO 3166-1 alpha-2 two-letter country codes. Common codes: US (United States), CN (China), GB (United Kingdom), JP (Japan), DE (Germany), FR (France), KR (South Korea), AU (Australia). Leave empty to return reviews from all territories.
• Sort: Sort order for reviews (optional). Supported values: 'createdDate' (newest first, default), '-createdDate' (oldest first), 'rating' (highest rating first), '-rating' (lowest rating first). Leave empty for default sorting (newest first).
• IncludeResponse: Whether to include the developer's reply to each review in the results (default: true). When true, each review's Response field will contain the developer's reply details (Id, ResponseBody, LastModifiedDate, State) if a reply exists.
• NextLink: Pagination URL for fetching the next page of reviews. Leave empty for the first request. Use the NextLink value from a previous response to get the next page. When using NextLink, other filter parameters (FilterRating, FilterTerritory, Sort) are ignored as they are already encoded in the URL.

Output:

• Reviews (object-array): Array of customer review objects. Each review contains: Id (string, unique review identifier), Title (string, review headline), Body (string, full review text), Rating (number, 1-5 stars), CreatedDate (string, ISO 8601 timestamp), Territory (string, two-letter country code e.g. 'US'), ReviewerNickname (string, reviewer's display name), AppStoreVersionId (string, associated app version ID), Response (object, developer's reply — contains Id, ResponseBody, LastModifiedDate, State fields; empty object {} if no reply exists or IncludeResponse is false).
• TotalCount (number): Number of reviews returned in this response. May be less than the total available if pagination is needed (check NextLink).
• NextLink (string): Pagination URL for fetching the next page of reviews. Empty string if there are no more pages. Pass this value as the NextLink input parameter in the next request to retrieve subsequent reviews.
• OriginalStatusCode (number): The original HTTP status code returned by the Apple App Store Connect API. Default 0 means the request did not reach upstream (e.g., timeout or exception). Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (network timeout/connection failure).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Reply a Review

Create a developer response to a specific customer review in Apple App Store Connect using API Key authentication. This is a write action: the reply will be submitted to App Store Connect for publishing. Always verify the target review and set Confirm=true only when you really want to post the reply.

Input Parameters:

• ReviewId: The unique identifier of the customer review to reply to (required). You can obtain this ID by calling the List Reviews action (appstore_review_list) or from the Apple App Store Connect dashboard. Example: 'abc123def456'.
• ResponseBody: The text content of your response to the customer review (required). This is the developer's reply that will be publicly visible on the App Store. Keep it professional, address the user's concerns, and optionally provide contact information for further support.
• Confirm: Safety gate for this write action. Must be true to send a real developer reply to App Store Connect. Use false to block accidental writes in automation or testing.

Output:

• ReplyId (string): Unique identifier of the created response. Use this ID to reference or manage the reply later. Empty string if the reply was not created.
• ResponseBody (string): Text content of the developer's response as confirmed by the API. Should match the input ResponseBody. Empty string if the reply was not created.
• LastModifiedDate (string): Last modification date of the response in ISO 8601 format (e.g. '2024-01-16T14:30:00.000Z'). Empty string if the reply was not created.
• State (string): Current state of the response. Possible values: PENDING_PUBLISH (response created but not yet visible on the App Store, pending Apple's review), PUBLISHED (response is live and visible to users on the App Store). Empty string if the reply was not created.
• OriginalStatusCode (number): The original HTTP status code returned by the Apple App Store Connect API. 201 means the reply was created successfully. Default 0 means the request did not reach upstream (e.g., timeout or exception). Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (network timeout/connection failure).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

5. Example Usage

This section will guide you through creating a simple workflow to retrieve the latest reviews for one of your apps.

The workflow will consist of three nodes: Start -> Appstore: List Reviews -> Answer.

1. Add the Appstore Node
   • In the workflow canvas, click the "+" icon to add a new node.
   • In the pop-up panel, select the "Tools" tab.
   • Find and select "Appstore" from the list of tools.
   • From the list of supported operations for Appstore, click on "List Reviews" to add the node to your canvas.
2. Configure the Node
   • Click on the newly added "List Reviews" node to open its configuration panel on the right.
   • Credentials Configuration: At the top of the panel, find the credentials field. Click the dropdown menu and select your pre-configured Appstore credential.
   • Parameter Configuration: Fill in the input parameters to specify which reviews to fetch.
   • AppId: Enter the unique Apple ID for your application. For example, 1234567890. This is a required field.
   • Limit: You can optionally specify the maximum number of reviews to return in a single run. The default is 50.
   • FilterRating: To see only 1-star reviews, you could enter 1 here.
   • Sort: You can sort the results. For example, enter -createdDate to get the newest reviews first.
3. Run and Verify
   • Once all required parameters are correctly filled, any error indicators on the workflow canvas will disappear.
   • Click the "Run" button in the top-right corner of the canvas to execute the workflow.
   • After a successful execution, you can click the logs icon in the top-right corner to view the detailed inputs and outputs of the node, verifying that the reviews were retrieved successfully.

After completing these steps, your workflow is fully configured. When executed, it will fetch a list of reviews from the App Store Connect API based on your criteria.

6. FAQs

Q: Why am I getting a 401 Unauthorized or 403 Forbidden error?

A: This typically indicates an issue with your API credentials. Please check the following:

• API Key: Ensure your API Key ID and the private key file are correct and have not expired.
• Issuer ID: Verify that the Issuer ID in your credential configuration is correct.
• Permissions: Confirm that the API key has the necessary roles and permissions (e.g., "Customer Support" or "App Manager") in App Store Connect to access review data.

Q: How do I find my App's Apple ID?

A: You can find the Apple ID in the URL of your app's page on the App Store. It is the number that follows "id" in the URL. For example, in https://apps.apple.com/us/app/your-app-name/id1234567890, the App ID is 1234567890.

Q: The List Reviews operation returned an empty list, but I know there are reviews. What's wrong?

A: This could be due to overly restrictive filters. Double-check the values you've provided for FilterRating and FilterTerritory. Also, confirm that the AppId is correct and does not contain any typos.

7. Official Documentation

For more in-depth information about the capabilities and technical details of the API, please refer to the Appstore Official API Documentation.