Link Search Menu Expand Document

Altering a business

Contents

Overview

  • Call name: alter-business
  • Endpoint URL: https://api0.spaaza.com/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 access to 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"
    }
}