Create or update widget

Overview

Create a new widget, or update an existing one when you supply unique_id. Requires the location to have an active widget add-on; a new widget gets a hashid unique_id generated from its id after the first save.

Prerequisites

• A bearer token. Callable with Partner and Account tokens.

Base URL

Endpoint

POST /api/v1/account/widget/update

Authentication

• Requires a bearer token in the Authorization: Bearer <bearer-token> header.

• Who can call it: Partner and Account tokens.

• Authentication in the role-agnostic account/* group (route name api.brand.widget.update). No HiPages gate.

• store_id must sit inside your own account tree (auth user's company-hierarchy walk).

• Note: despite the controller's OpenAPI annotation listing company_id as an alternative, the endpoint makes store_id required for every role. company_id is NOT a request field here and is only set from $validated['company_id'] (always null in practice).

• Both roles use the same params. A partner can target stores anywhere in its tree, an account user only its own.

Rate limit

• No rate limit.

Request body

• Body:

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

Response

• data.message (string)
• data.status (string) — success
• data.data.unique_id (string) — the saved widget's hashid code

200 OK · 200

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

400 No active widget add-on · 400

{
  "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": []
}

422 Validation error · 422

{
  "message": "The widget type id field is required.",
  "errors": {
    "widget_type_id": ["The widget type id field is required."],
    "store_id": ["The store id field is required."]
  }
}

402 Feature limit reached · 402

{
  "status": "error",
  "message": "Review Widgets limit reached for this period.",
  "feature": "review_widgets",
  "remaining": 0,
  "hard_stop": true
}

Errors

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": 12, "widget_type_id": 1, "widget_title": "My Feed Widget", "widget_options": {"numberOfReviews": 3, "reviewSiteValue": {"value": 5}}}'