Altering a business
Altering a business
Contents
- Overview
- Version-specific information
- Permissions and Authentication
- Headers
- HTTP Parameters
- Example response JSON
Overview
- Call name: alter-business
- Endpoint URL: https://{API hostname}/internal/alter-business
- Request methods: PUT
- Request Content-Type: multipart/form-data or application/x-www-form-urlencoded or application/json
- Response Content-Type: application/json
- Auth required: yes
In Spaaza terminology, a "business" is a branch of a retailer (a "chain"). This API call updates an existing business.
Note it is also possible to update an existing business by passing the update_if_exists parameter to the add-business endpoint.
Version-specific information
The following version-specific changes apply to this endpoint. See the versioning page for more details.
| Version | Change details |
|---|---|
| N/A | N/A |
Permissions and Authentication
This API call requires a valid Spaaza session. See the authentication page for more details. The session can be as follows:
- Admin authentication: The performing user needs to be logged in and have
write accessto the chain to which the user is connected.
Headers
Standard headers are used for this endpoint. No special headers are required.
HTTP Parameters
The following HTTP parameters can be passed to the API:
| Parameter | Description |
|---|---|
| business_id | (integer, mandatory) The ID of the business whose details are to be altered |
| address_1 | (string, optional, max=255) The first line of the business address |
| address_2 | (string, optional, max=255) The second line of the business address |
| address_3 | (string, optional, max=255) The third line of the business address |
| countrycode | (string, optional, length=2) The ISO ALPHA-2 2-letter country code of the business (e.g., "NL", "BE", "DE") |
| description | (string, optional, max=512) A description of the business |
| email_address | (string, optional, max=255) The email address for the business. Must be a valid email format |
| facebook_url | (string, optional, max=255) The Facebook URL for the business |
| fax_number | (string, optional, max=56) The fax number for the business |
| format | (string, optional, max=64) The store format of the business (e.g., "Metro", "Express") |
| google_place_id | (string, optional, max=1024) The Google Place ID of the store/business |
| image_url | (string, optional, max=512) The URL link to the business's image/logo |
| is_shut_down | (boolean, optional) Whether the business is administratively shut down (true/false). Default: false |
| latitude | (float, optional) The latitude of the business in decimal degrees. Must be between -90 and +90 |
| linkedin_url | (string, optional, max=255) The LinkedIn URL for the business |
| longitude | (float, optional) The longitude of the business in decimal degrees. Must be between -180 and +180 |
| name | (string, optional, max=255) The name of the business |
| opening_times | (string, optional, max=2048) The opening times of the business in JSON format. See example response for format |
| owner_code | (string, optional, max=64) The retailer owner_code for the store. Must be unique within the chain |
| phone_number | (string, optional, max=32) The phone number for the business |
| postalcode | (string, optional, max=20) The postal code of the business. Format validation applies for: - NL: "1234 AB" format - DE: "12345" or "D-12345" format - BE: "1234" or "1234 BE" format |
| programme_opted_in | (boolean, optional) Whether the business participates in the loyalty programme (true/false). Default: true |
| region | (string, optional, max=255) The region or state of the business |
| review_url | (string, optional, max=512) The URL link to the review business page |
| towncity | (string, optional, max=255) The postal city of the business |
| twitter_username | (string, optional, max=15) The Twitter username for the business (without @ symbol) |
| website_url | (string, optional, max=255) The website URL for the business |
Possible error responses
| Code | Name | Description | HTTP Status |
|---|---|---|---|
| 3 | http_vars_missing | Required parameter business_id is missing | 400 |
| 6 | no_valid_session | No valid session key provided or session has expired | 401 |
| 13 | http_request_method_non_PUT_not_allowed | Only HTTP PUT allowed for this API call | 405 |
| 15 | business_id_invalid | The business_id passed must be an integer | 400 |
| 68 | permission_denied_or_non_existent | User has insufficient permissions or the referenced business does not exist | 403 |
| 98 | lat_long_both_required | Both decimal latitude and longitude must be supplied when specifying location | 400 |
| 99 | lat_long_invalid | Latitude must be between -90 and +90, longitude between -180 and +180 | 400 |
| 124 | business_name_invalid | The business name must be 255 characters or less | 400 |
| 125 | business_description_invalid | The business description must be 512 characters or less | 400 |
| 126 | business_address_1_invalid | The business_address_1 value must be 128 characters or less | 400 |
| 127 | business_address_2_invalid | The business_address_2 value must be 128 characters or less | 400 |
| 128 | business_address_3_invalid | The business_address_3 value must be 128 characters or less | 400 |
| 129 | business_towncity_invalid | The business_towncity value must be 56 characters or less | 400 |
| 130 | business_region_invalid | The business_region value must be 56 characters or less | 400 |
| 131 | business_postalcode_invalid | The business_postalcode value must be 20 characters or less | 400 |
| 132 | business_country_code_invalid | The business_country_code value must be 2 characters | 400 |
| 133 | business_latitude_invalid | The business_latitude must be a decimal degree value, max +/- 90 | 400 |
| 134 | business_longitude_invalid | The business_longitude must be a decimal degree value, max +/- 180 | 400 |
| 135 | business_email_address_invalid | The business_email_address value must be a valid email address | 400 |
| 136 | business_phone_number_invalid | The business_phone_number value must be a valid phone number | 400 |
| 137 | business_fax_number_invalid | The business_fax_number value must be a valid fax number | 400 |
| 138 | business_website_url_invalid | The business_website_url value must be a valid URL | 400 |
| 139 | business_facebook_url_invalid | The business_facebook_url value must be a valid URL | 400 |
| 140 | business_twitter_username_invalid | The business_twitter_username value must be a valid Twitter username | 400 |
| 141 | business_linkedin_url_invalid | The business_linkedin_url value must be a valid URL | 400 |
| 143 | business_owner_code_invalid | The business_owner_code must be 32 characters or less | 400 |
| 316 | parameter_supplied_not_boolean | Boolean parameter (is_shut_down, programme_opted_in) contains invalid value | 400 |
| 420 | country_code_invalid | The country code must be in ISO ALPHA-2 two-letter format | 400 |
| 435 | latitude_value_error | The latitude value must be between -90 and +90 degrees | 400 |
| 436 | longitude_value_error | The longitude value must be between -180 and +180 degrees | 400 |
| 441 | parameter_missing | A required parameter is missing | 400 |
| 482 | string_parameter_too_long | One or more string parameters exceeds maximum length | 400 |
Example response JSON
The endpoint returns JSON showing the details associated with the business. An example response is shown below:
{
"result": {
"code": 1,
"status": "ok"
},
"results": {
"business": {
"address_1": "Herengracht 504",
"address_2": null,
"address_3": null,
"business_format": "Metro",
"chain_id": 1743,
"countrycode": "NL",
"created_date": "2024-04-01T11:21:14+00:00",
"email_address": "ops@spaaza.com",
"id": 1383,
"image_url": "https://media.licdn.com/dms/image/C4D0BAQEN6wx-nP_Crg/company-logo_400_400/0?e=1578528000&v=beta&t=1qKTWg0qbIJMydHHG02YPhD8N4LONyW5Rp06wn5DvN0",
"last_modified_date": "2024-04-03T12:43:54+00:00",
"latitude": "52.37021570",
"longitude": "1.89516789",
"name": "ACME Inc",
"opening_times": "{\"monday\": {\"open\": \"11:00\",\"close\": \"18:00\" }, \"tuesday\": { \"open\": \"09:30\", \"close\": \"18:00\" }, \"wednesday\": { \"open\": \"09:30\", \"close\": \"18:00\" }, \"thursday\": { \"open\": \"09:30\", \"close\": \"18:00\" }, \"friday\": { \"open\": \"09:30\", \"close\": \"21:00\" }, \"saturday\": { \"open\": \"09:30\", \"close\": \"17:00\" }, \"sunday\": { \"open\": \"Elke laatste zondag van de maand\", \"close\": \"12:00-17:00\" }, \"special_hours\": [ { \"date\": \"23\\/02\\/2020\", \"open\": \"12:00\", \"close\": \"17:00\", \"reason\": \"Laatste zondag van de maand\" }, { \"date\": \"23\\/02\\/2020\", \"open\": \"-\", \"close\": \"-\", \"reason\": \"Carnaval\" } ] }",
"owner_code": "10001",
"postalcode": "1017 CB",
"region": "Noord Holland",
"review_url": "https://g.page/spaaza/review",
"towncity": "Amsterdam",
"type": "business",
"website_url": "https://www.spaaza.com"
},
"result_type": "alter-business"
}
}