Create or edit a review widget

Overview

Create a widget for a location, or change an existing one's title and settings.

Use this to set up a widget for a customer's website.

You'll need the store_id, a style (List widget styles), and display options; the widget's unique_id to edit.

Returns the widget's unique_id, which goes in the embed code.

ℹ️
Without unique_id, a new widget is created. With unique_id, that widget is edited: only widget_title and widget_options change, and its style stays as it was. Each save sets both widget_title and widget_options, so leaving one out clears it. Creating a widget counts toward your plan's widget limit; when the limit is reached you get 402. The location needs an active widget add-on, otherwise 400.

Prerequisites

A bearer token. See Authentication.
The location's id (store_id). The location needs an active widget add-on.
A style id (widget_type_id) from List widget styles.
To edit: the widget's unique_id, from List review widgets.

Base URL

Environment	URL
Production	`https://production-api.shoutaboutus.com`
Development	`https://development-api.shoutaboutus.com`

Endpoint

POST /api/v1/account/widget/update

Authentication

Partner or Account token

store_id must be inside your own account tree. A Partner token can use any location under the partner; an Account token only its own.
To edit, unique_id must be one of your widgets.
A location outside your tree, or one that doesn't exist, is rejected with 422.

Rate limit

This endpoint has no rate limit.

Request parameters

None.

Request body

Field	Type	Required	Description
`store_id`	integer	Yes	The widget's location. Must exist and be inside your account tree, and have an active widget add-on.
`widget_type_id`	integer	Yes	The style, from List widget styles. Must exist. Used when creating; an existing widget keeps its style.
`unique_id`	string	No	The widget to edit. Leave it out to create a new widget.
`widget_title`	string	No	The widget's title, up to 255 characters. Left out: cleared.
`widget_options`	object	No	The widget's display settings, saved as sent. Left out: cleared. The feed reads `numberOfReviews` (reviews per page) and `reviewSiteValue.value` (the review site to show).
`widget_options.numberOfReviews`	integer	No	Reviews per feed page. When not set, the feed shows 3.
`widget_options.reviewSiteValue`	object	No	The review site the feed shows.
`widget_options.reviewSiteValue.value`	integer	No	The review site id, e.g. `44` for Google.

Request payload

{
  "store_id": 3007,
  "widget_type_id": 1,
  "widget_title": "My Feed Widget",
  "widget_options": {
    "numberOfReviews": 3,
    "reviewSiteValue": {
      "value": 44
    }
  }
}

Response body

The payload is inside data. The response also carries X-Feature, X-Feature-Limit, X-Feature-Used, X-Feature-Remaining and X-Feature-Hard-Stop headers with your plan's widget usage.

Field	Type	Description
`message`	string	`Widget has been saved successfully`.
`status`	string	`success`.
`data`	object	The saved widget.
`data.unique_id`	string	The widget's unique id, for the embed code.

Response payload

{
  "data": {
    "message": "Widget has been saved successfully",
    "status": "success",
    "data": {
      "unique_id": "abc123"
    }
  }
}

Examples

Success payload

See Response payload.

Error payload

400 No active widget add-on

{
  "message": "You do not have any active widget add-ons. Please add an add-on to your location in order to access the widget features.",
  "status": "error",
  "errors": []
}

402 Widget limit reached

{
  "status": "error",
  "message": "Limit reached for 'Widgets': 3 of 3 units consumed this period.",
  "feature": "review_widgets",
  "remaining": 0,
  "hard_stop": true
}

422 Required fields missing

{
  "message": "The store id field is required. (and 1 more error)",
  "errors": {
    "store_id": [
      "The store id field is required."
    ],
    "widget_type_id": [
      "The widget type id field is required."
    ]
  }
}

422 unique_id doesn't match a widget

{
  "message": "Invalid widget unique code!",
  "errors": {
    "unique_id": [
      "Invalid widget unique code!"
    ]
  }
}

422 widget_type_id doesn't exist

{
  "message": "The selected widget type id is invalid.",
  "errors": {
    "widget_type_id": [
      "The selected widget type id is invalid."
    ]
  }
}

Status	Meaning
`200`	The widget was saved.
`400`	The location has no active widget add-on.
`401`	The token is missing, expired or invalid.
`402`	Creating a widget would go over your plan's widget limit (`X-Feature-*` headers give the details).
`422`	A required field is missing, `store_id` doesn't exist or is outside your tree, `unique_id` doesn't match a widget, or `widget_type_id` doesn't exist.
`500`	Unexpected server error.

Example request

curl --request POST \
  --url "https://production-api.shoutaboutus.com/api/v1/account/widget/update" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"store_id": 3007, "widget_type_id": 1, "widget_title": "My Feed Widget", "widget_options": {"numberOfReviews": 3, "reviewSiteValue": {"value": 44}}}'