ResourceFeedback

Important

The ResourceFeedback API is for use only with the Sales Channel SDK.

The ResourceFeedback API allows your app to report the status of shops and their resources and display this information within Shopify admin. Once created, resource feedback is used to notify merchants about steps they need to take to set up your app on their store. If your app has optional or promotional setup steps offered to merchants, or makes recommendations, don't use ResourceFeedback to inform merchants of them. This API should only be used if there are required steps for a merchant to complete.

Send feedback on a Shop

You can send feedback on a shop to let merchants know what steps they need to take to make sure your app is set up correctly. Feedback can have one of two states: requires_action or success. You will need to send a requires_action feedback request for each step that the merchant is required to complete. If there are multiple setup steps requiring merchant action, send feedback with a state of requires_action as merchants complete prior steps. Send a success feedback request to remove the feedback message from Shopify admin.

Important

Sending feedback replaces previously sent feedback for the Shop. Unlike REST-style APIs, you don't need to make a PATCH or PUT request to update any previously sent feedback. Send a new POST request to push the latest state of a shop or its resources to Shopify.

Formatting the resource feedback message field

If feedback state is requires_action you can send a string message, which communicates the action to be taken by the merchant. The string must be a single message up to 100 characters long, must follow your app's name with [is/has], and must end with a period. You must adhere to the message formatting rules or your requests will fail:

  • [is/has] [explanation of the problem]. [Suggested action].

  • Examples:

  • [Your app name] is not connected. Connect your account to use this sales channel. [Learn more]
  • [Your app name] is not connected. Agree to the terms and conditions to use this sales channel. [Learn more]

  • Where both Your app name and Learn more (a button which directs merchants to your app) are automatically populated in the Shopify admin.

    What you can do with ResourceFeedback

    The Shopify API lets you do the following with the ResourceFeedback resource. More detailed versions of these general actions may be available:

    ResourceFeedback properties

    shop_id
    "shop_id": 123

    Unique numeric identifier of the Shop.

    created_at
    "created_at": 2017-08-28 19:10:10 UTC

    DateTime when the resource feedback record was stored by Shopify. Type: ISO 8601 UTC DateTime as string with year, month (or week), day, hour, minute, second, time zone.

    updated_at
    "updated_at": 2017-08-28 19:10:10 UTC

    DateTime when the resource feedback record was last updated by Shopify. Type: ISO 8601 UTC DateTime as string with year, month (or week), day, hour, minute, second, time zone.

    resource_id
    "resource_id": 321

    Unique id of the resource.

    resource_type
    "resource_type": "Shop"

    Type of resource for which feedback is returned. eg. Shop, Product.

    state
    "state": "requires_action"
    "state": "success"

    Indicates the state that the Shop or resource is in, from the perspective of your app. Valid values are requires_action, or success.

    messages
    "messages": ["is not connected. Connect your account to use this sales channel."]

    A concise set of copy strings to be displayed to merchants, to guide them in resolving problems your app encounters when trying to make use of their Shop and its resources.

    Required only when state is requires_action. Disallowed when state is success.

    Content restrictions for Shop feedback: one message up to 100 characters long.

    feedback_generated_at
    "feedback_generated_at": "2017-08-28T19:10:10.239547Z"

    The time at which the payload is constructed. Used to help determine whether incoming feedback is outdated compared to feedback already received, and if it should be ignored upon arrival. Type: ISO 8601 UTC datetime as string with year, month [or week], day, hour, minute, second, millisecond, and time zone.

    Note

    If you queue a Feedback API payload for delivery at a later time, do not update this value when the API call is actually made; ensure that the current time is set when building the payload.

    Endpoints

    POST /admin/resource_feedback.json
    Create shop resource feedback.
    state
    • requires_action - Indicates that your app requires the merchant to resolve an issue with their shop.
    • success - Indicates that the app does not have any outstanding issues with this shop.

    Sending outdated feedback (previous feedback payload has a greater resource_updated_at value) returns an error

    POST /admin/resource_feedback.json
    {
      "resource_feedback": {
        "state": "success",
        "feedback_generated_at": "2017-08-28T19:10:24.994985Z"
      }
    }
    View Response
    HTTP/1.1 409 Conflict
    {
      "errors": {
        "messages": [
          "Feedback request not delivered. Feedback request is older than a previously delivered feedback request."
        ]
      }
    }

    Create a shop feedback record indicating a problem specific to your app

    POST /admin/resource_feedback.json
    {
      "resource_feedback": {
        "state": "requires_action",
        "messages": [
          "is not connected. Connect your account to use this sales channel."
        ],
        "feedback_generated_at": "2017-08-28T19:10:26.865086Z"
      }
    }
    View Response
    HTTP/1.1 202 Accepted
    {
      "resource_feedback": {
        "shop_id": 690933842,
        "created_at": "2017-08-28T15:10:26-04:00",
        "updated_at": "2017-08-28T15:10:26-04:00",
        "resource_id": 690933842,
        "resource_type": "Shop",
        "resource_updated_at": null,
        "messages": [
          "is not connected. Connect your account to use this sales channel."
        ],
        "feedback_generated_at": "2017-08-28T15:10:26-04:00",
        "state": "requires_action"
      }
    }

    If the app is not configured as a Sales Channel, the API returns an error

    POST /admin/resource_feedback.json
    {
      "resource_feedback": {
        "state": "success",
        "feedback_generated_at": "2017-08-28T19:10:28.884789Z"
      }
    }
    View Response
    HTTP/1.1 403 Forbidden
    {
      "errors": {
        "message": "App must be configured as a Sales Channel."
      }
    }

    Create a shop feedback record indicating the Shop is usable by your app

    POST /admin/resource_feedback.json
    {
      "resource_feedback": {
        "state": "success",
        "feedback_generated_at": "2017-08-28T19:10:29.927046Z"
      }
    }
    View Response
    HTTP/1.1 202 Accepted
    {
      "resource_feedback": {
        "shop_id": 690933842,
        "created_at": "2017-08-28T15:10:30-04:00",
        "updated_at": "2017-08-28T15:10:30-04:00",
        "resource_id": 690933842,
        "resource_type": "Shop",
        "resource_updated_at": null,
        "messages": [
        ],
        "feedback_generated_at": "2017-08-28T15:10:29-04:00",
        "state": "success"
      }
    }

    Sending an invalid feedback payload returns an error

    POST /admin/resource_feedback.json
    {
      "resource_feedback": {
        "state": "foobar",
        "feedback_generated_at": "2017-08-28T19:10:30.959492Z"
      }
    }
    View Response
    HTTP/1.1 422 Unprocessable Entity
    {
      "errors": {
        "messages": [
          "Validation failed: State must be one of success and requires_action"
        ]
      }
    }
    GET /admin/resource_feedback.json
    Return a list (zero or one) of resource feedback objects.

    Important

    Note that ids are not returned as part of this request. Records are immutable except when POST replaces them.

    Get a list of resource feedback records for a specific shop

    GET /admin/resource_feedback.json
    View Response
    HTTP/1.1 200 OK
    {
      "resource_feedback": [
        {
          "shop_id": 690933842,
          "created_at": "2017-08-28T15:10:27-04:00",
          "updated_at": "2017-08-28T15:10:27-04:00",
          "resource_id": 690933842,
          "resource_type": "Shop",
          "resource_updated_at": null,
          "messages": [
            "is not connected. Connect your account to use this sales channel."
          ],
          "feedback_generated_at": "2017-08-28T14:10:27-04:00",
          "state": "requires_action"
        }
      ]
    }