Assign or change an account's plan

Overview

Put an account on a plan, or move it to a different one. Every location under the account moves with it.

Use this when a customer signs up, upgrades, or downgrades. This is the same action as Assign or change an account's plan on the Accounts page; it's listed here so you can find it from either direction. This one takes several accounts at once.

You'll need the account's id and the plan_id.

All the account's locations are moved to the new plan immediately, with the new plan's sites, cadence, and capabilities. The previous plan is closed, and the new one runs to the end of the month. Accounts already on the plan are skipped.

Prerequisites

A Partner or Account token. See Authentication.
The accounts' ids (account_ids) and a plan_id set up for your partner. See List your plans.

Base URL

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

Endpoint

POST /api/v1/account/plan/update

Authentication

Partner or Account token

plan_id must be one of the plans set up for your partner; otherwise 422.
Each id in account_ids must be an existing account inside your own account tree; otherwise 422. A Partner token can target any account under the partner, an Account token only its own account.

Rate limit

This endpoint has no rate limit.

Request parameters

None.

Request body

Field	Type	Required	Description
`plan_id`	integer	Yes	The plan to assign. Must be one of the plans set up for your partner.
`account_ids`	array of integers	Yes	The accounts to move to the plan.

Request payload

{
  "plan_id": 36,
  "account_ids": [5994]
}

Response body

The payload is inside data.

Field	Type	Description
`status`	string	`success`.
`message`	string	How many accounts and locations were moved, e.g. `Plan updated successfully for 1 account(s) and 2 location(s). Charges will appear on next month's invoice.`

Response payload

{
  "data": {
    "status": "success",
    "message": "Plan updated successfully for 1 account(s) and 2 location(s). Charges will appear on next month's invoice."
  }
}

Examples

Success payload

See Response payload.

Error payload

422 Nothing to change

Every account is already on the plan, or has no active locations.

{
  "message": "No accounts were updated since the selected plan is already active for all specified accounts or no active stores were found under those accounts. If you expected accounts to be updated, please verify that the account IDs are correct and that the selected plan is different from the currently active plan for those accounts.",
  "status": "error",
  "errors": "No accounts were updated since the selected plan is already active for all specified accounts or no active stores were found under those accounts. If you expected accounts to be updated, please verify that the account IDs are correct and that the selected plan is different from the currently active plan for those accounts."
}

422 Plan or account not available

{
  "message": "The selected plan is not available for your account. (and 2 more errors)",
  "errors": {
    "plan_id": ["The selected plan is not available for your account."],
    "account_ids.0": [
      "The selected account_ids.0 is invalid.",
      "The selected account_ids.0 does not belong to your company hierarchy."
    ]
  }
}

422 Fields missing

{
  "message": "The plan id field is required. (and 1 more error)",
  "errors": {
    "plan_id": ["The plan id field is required."],
    "account_ids": ["The account ids field is required."]
  }
}

Status	Meaning
`200`	The accounts and their locations are on the new plan.
`401`	The token is missing, expired or invalid.
`422`	Nothing to change, or the plan or an account isn't available to you, or a field is missing.
`500`	Unexpected server error.

Example request

curl --request POST \
  --url "https://production-api.shoutaboutus.com/api/v1/account/plan/update" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"plan_id": 36, "account_ids": [5994]}'

Updated 17 days ago

Did this page help you?