Update existing locations from a spreadsheet

Overview

Update details of locations you already have — name, label, address, city, postal code — from a spreadsheet, matched to each location by its id.

Use this to correct or refresh a lot of location records at once, for example after an address audit. It does not create new locations.

You'll need an account token and a spreadsheet where each row carries the location's id.

Matched locations are updated; the response lists any rows that were skipped.

🚧
Each matched row replaces the location's name, label (store_id column), address, city and postal code. A blank store_id or address cell clears that value.

Prerequisites

An Account token. See Authentication.
A spreadsheet with one row per location, using the columns below.

Base URL

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

Endpoint

POST /api/v1/store/import-locations-excel

Authentication

Account token

Only locations in your own account are matched. A location_id outside your account rejects the whole file with 400.
Any other token gets 403.

Rate limit

This endpoint has no rate limit.

Request parameters

None.

Request body

Send the body as multipart/form-data.

Field	Type	Required	Description
`excel_file`	file	Yes	The spreadsheet, as `.xlsx` or `.xls`, max 99 MB. Only the first worksheet is read.

Columns, one row per location:

Column	Required	Description
`location_id`	Yes	Which location to update: its code (e.g. `SAU178040716910`), its numeric id, or your `client_location_id`.
`store_name`	Yes	The location's name.
`store_id`	No	The location's display label.
`address`	No	Street address.
`city_name`	Yes	The city's name.
`state_code`	Yes	The state's code, e.g. `NSW`.
`zip_code`	Yes	Postal code.
`country_code`	Yes	A known country code, e.g. `AU`.

If any row is missing a required value, has an unknown country_code, or has a location_id that isn't one of your locations, nothing is updated and the response is 400 with every problem listed.

Request payload

Form field:

excel_file=@excel_file.xlsx

Response body

The payload is inside data.

Field	Type	Description
`status`	string	`success`.
`message`	string	`File has been uploaded.`
`errors`	array of strings	Rows that were skipped because their state or city wasn't found, e.g. `Row #3 - City name not found`. Empty when every row was applied.

Response payload

{
  "data": {
    "status": "success",
    "message": "File has been uploaded.",
    "errors": [
      "Row #3 - City name not found",
      "Row #7 - State code not found"
    ]
  }
}

Examples

Success payload

See Response payload.

Error payload

400 Rows rejected

{
  "message": "Bad Request",
  "status": "error",
  "errors": [
    "Row #4: XX - Country code not found",
    "Row #2: ABC-999 - Location ID not found"
  ]
}

400 Empty file

{
  "message": "Bad Request",
  "status": "error",
  "errors": {
    "excel_file": ["The uploaded file appears to be empty."]
  }
}

403 Not an Account token

{
  "message": "This action is unauthorized."
}

422 No file

{
  "message": "The excel file field is required.",
  "errors": {
    "excel_file": ["The excel file field is required."]
  }
}

Status	Meaning
`200`	The matched locations are updated. `errors` lists any skipped rows.
`400`	The file is empty, or rows failed the checks; nothing is updated.
`401`	The token is missing, expired or invalid.
`403`	The token isn't an Account token.
`422`	`excel_file` is missing, isn't an Excel file, or is too large.
`500`	Unexpected server error.

Example request

curl --request POST \
  --url "https://production-api.shoutaboutus.com/api/v1/store/import-locations-excel" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json' \
  --form 'excel_file=@excel_file.xlsx'

Updated 17 days ago

Did this page help you?