Altering a chain

Overview
Version-specific information
Permissions and Authentication
Headers
HTTP Parameters
Nullable URL field behaviour
Sample response JSON
Possible error responses

Overview

Call name: alter-chain
Endpoint URL: https://{API hostname}/internal/alter-chain
Request methods: POST, PUT
Request Content-Type: multipart/form-data or application/x-www-form-urlencoded or application/json
Response Content-Type: application/json
Auth required: yes

This API call updates an existing chain (retailer organisation) and its configuration settings.

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 super user access to the chain.

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
chain_id	(integer, mandatory) The ID of the chain to update.
email_address	(string, optional) The email address of the chain.
phone_number	(string, optional) The phone number of the chain.
language	(string, optional) The language of the chain.
image_url	(string, optional) The main image URL for the chain. Nullable (see Nullable URL field behaviour).
receipt_logo_url	(string, optional) The logo URL shown on receipts for the chain. Nullable (see Nullable URL field behaviour).
password_reset_url	(string, optional) The password reset URL for the chain. This value is set when a chain uses an alternative to the Console to reset the password of a user. Nullable (see Nullable URL field behaviour).
uses_third_party_voucher_id	(boolean, optional) Set to `true` if the chain uses a third-party voucher ID which will be set when the voucher is created.
non_payment_state	(boolean, optional) Set to `true` if the chain is in non-payment state, meaning the organisation has outstanding invoices. If set to `true`, the chain will not be able to make API calls except for `alter-chain` (to reset this flag). Default is `false`.
redemption_grace_period	(integer, optional) An optional parameter (in hours) that allows vouchers for a campaign to be redeemed after the `campaign_active_date_until` has passed. Must be greater than or equal to 0. Default is `0`.
claim_basket_user_rate_limit_unit	(string, optional) The unit of measurement for the claim basket user rate limit. Allowed values: `second`, `minute`, `hour`, `day`, `week`, `month`, `year`.
claim_basket_user_rate_limit_quantity	(integer, optional) The time interval during which a user cannot claim another basket after the last previous claim. For example, a value of `5` with a unit of `month` means the basket can be claimed once every 5 months.
chain_image	(file, optional, POST only) The image of the brand.
receipt_image	(file, optional, POST only) The image of the brand that appears on a customer's receipt.
allows_double_discounting	(boolean, optional) Controls whether percentage discount campaigns and vouchers can be applied simultaneously with other basket campaigns. Default is `false`. When `false`, the system evaluates all percentage vouchers and basket campaigns together and applies only the best discount for each basket item. When `true`, the best percentage voucher can be applied in addition to any BasketCampaign discounts.
exclude_rewards_on_basket_campaign_discounted_items	(boolean, optional) Controls whether basket items that have been discounted by a BasketCampaign are excluded from earning rewards (wallet contributions, cashback, purchase progress, matching item counts). Default is `false`. When `true`, items discounted by a BasketCampaign will not contribute to reward earning.
allowed_business_formats	(string, optional) A JSON-encoded array of allowed business formats for this chain. When set, this restricts which business formats are permitted for businesses within this chain. An empty array can be provided to clear the field. Example: `["retail", "food,beverage", "service.1"]`.
outlier_analysis_enabled	(boolean, optional) Whether outlier analysis is enabled for the chain. Default is `false`.
basket_campaign_require_barcode_assignment	(boolean, optional) Whether the chain requires every active BasketCampaign to have at least one barcode assignment. Default is `false`. When `true`, `add-campaign` and `alter-campaign` will reject an active BasketCampaign that has no barcode (earn or spend) assignment. Inactive campaigns are not affected.
basket_campaign_require_format_assignment	(boolean, optional) Whether the chain requires every active BasketCampaign to have at least one Business Format assignment. Default is `false`. When `true`, `add-campaign` and `alter-campaign` will reject an active BasketCampaign that has no Business Format assignment. Inactive campaigns are not affected.
basket_campaign_require_region_or_store_assignment	(boolean, optional) Whether the chain requires every active BasketCampaign to have at least one Business Region OR Business (store) assignment. Default is `false`. When `true`, `add-campaign` and `alter-campaign` will reject an active BasketCampaign that has neither a Business Region nor a Business (store) assignment; either one on its own satisfies the requirement. Inactive campaigns are not affected.
verify_phone_numbers	(boolean, optional) Set to `true` if the chain requires phone number verification for users. When `true`, users will be required to verify their phone number via an OTP code sent by SMS during signup and when changing their phone number. Default is `false`.

Nullable URL field behaviour

The following URL fields are nullable:

image_url
receipt_logo_url
password_reset_url

For these fields:

Non-empty values must be valid URLs.
Form requests can clear a value by sending an empty string ('').
Form requests can also clear by sending string 'null' because non-JSON content types do not carry a native null type.
JSON requests can clear a value by sending null.
If cleared, the stored value is null and get-chain returns null for that field.

Sample response JSON

{
    "result": {
        "code": 1,
        "status": "ok"
    },
    "results": {
        "chain": {
            "id": 1,
            "name": "FOO Chain, inc.",
            "type": "chain",
            "email_address": "something@else.com",
            "phone_number": "0124141",
            "currency": {
                "currency_id": 2,
                "currency_code": "EUR",
                "currency_name_en": "Euro",
                "currency_symbol": "\u20ac"
            },
            "deleted": false,
            "calculate_basket_on_total_value_online": false,
            "calculate_basket_on_total_value_in_store": false,
            "basket_voucher_always_redeem_full_value_online": false,
            "basket_voucher_always_redeem_full_value_in_store": false,
            "return_redeem_voucher_before_cash": false,
            "receipts_service_active": false,
            "regenerated_rewards_redeem_immediately": false,
            "expired_vouchers_regenerate_on_return": false,
            "allows_double_discounting": false,
            "exclude_rewards_on_basket_campaign_discounted_items": false,
            "allowed_business_formats": ["retail", "food,beverage", "service.1"],
            "outlier_analysis_enabled": false,
            "basket_campaign_require_barcode_assignment": false,
            "basket_campaign_require_format_assignment": false,
            "basket_campaign_require_region_or_store_assignment": false,
            "language": "en-UK",
            "image_url": null,
            "receipt_logo_url": null,
            "non_payment_state": false,
            "redemption_grace_period": 0,
            "verify_phone_numbers": false
        },
        "result_type": "alter-chain"
    }
}

Possible error responses

The following represents a list of possible error responses for the alter-chain endpoint:

Code	Name and Description	HTTP Status Code
3	http_vars_missing Required parameter `chain_id` is missing	400
6	no_valid_session No valid session key provided or session has expired	401
68	permission_denied_or_non_existent The user has insufficient permissions for this chain or the chain does not exist	403
76	chain_id_invalid The `chain_id` passed must be an integer	400
217	chain_id_not_found No record has been found for that `chain_id`	400
316	parameter_supplied_not_boolean A boolean parameter was supplied in a format that cannot be interpreted as boolean	400
419	parameter_invalid One of the parameters is invalid and should be in a different format	400

Altering a chain​

Contents​

Overview​

Version-specific information​

Permissions and Authentication​

Headers​

HTTP Parameters​

Nullable URL field behaviour​

Sample response JSON​

Possible error responses​