Link Search Menu Expand Document

Getting a chain

Contents

Overview

  • Call name: get-chain
  • Endpoint URL: https://api0.spaaza.com/internal/get-chain
  • Request methods: GET
  • Response Content-Type: application/json
  • Auth required: yes

This API endpoint returns the details of a chain (retailer organisation), including its configuration settings, currency, authentication points, and member number range information.

Version-specific information

The following version-specific changes apply to this endpoint. See the versioning page for more details.

Version Change details
>= 2.0.0 The response uses the standard schema format. Member number range fields are returned as nested properties under the app object: app.max_custom_entity_code (upper bound of the reserved member number range) and app.user_entity_code_custom_current_max (current highest dynamically assigned member number). Other fields such as currency and authentication points are also returned in the standard schema format. See the standard schema sample response below.
< 2.0.0 The response uses the legacy schema format. Member number range fields are returned as flat top-level properties on the chain object: max_custom_entity_code and entity_code_custom_current_max. See the legacy schema sample response below.

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 read access to the chain.
  • Privileged authentication: the use of privileged authentication is permitted for this endpoint.

Headers

The following headers can/must be passed to the API call:

Parameter Description
N/A N/A

HTTP Parameters

The following HTTP parameters can be passed to the API:

Parameter Description
chain_id (integer, mandatory) The ID of the chain for which the information is being requested. Can also be identified by business_id.
business_id (integer, conditional) The ID of a business belonging to the chain. Can be used instead of chain_id to identify the chain.

Member number ranges

The get-chain response includes two fields that describe the member number range configuration for the chain’s app. These fields are useful for understanding how member numbers are allocated.

max_custom_entity_code is the upper bound of the reserved member number range. Member numbers at or below this value are reserved for manual assignment, such as pre-printed physical loyalty cards or vanity member numbers.

entity_code_custom_current_max (legacy schema) or user_entity_code_custom_current_max (standard schema) is the current highest dynamically assigned member number. Dynamically assigned member numbers start at max_custom_entity_code + 1. If no dynamic member numbers have been assigned yet, this field resolves to the first dynamically assignable number above the reserved range.

For example, if max_custom_entity_code is 19999999999, member numbers up to and including 19999999999 are available for manual assignment. The first dynamically assigned member number will be 20000000000.

Sample response JSON (legacy schema)

The following is an example response when using API version < 2.0.0:

{
    "result": {
        "code": 1,
        "status": "ok"
    },
    "results": {
        "chain": {
            "id": 1,
            "name": "FOO Chain, inc.",
            "type": "chain",
            "email_address": null,
            "phone_number": null,
            "currency": {
                "currency_id": 2,
                "currency_code": "EUR",
                "currency_name_en": "Euro",
                "currency_symbol": "\u20ac"
            },
            "var_price_permitted": false,
            "var_price_round_up": false,
            "var_price_custom_entity_code": true,
            "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,
            "return_redeem_voucher_before_cash": false,
            "basket_voucher_always_redeem_full_value_in_store": false,
            "receipts_service_active": false,
            "regenerated_rewards_redeem_immediately": false,
            "exclude_rewards_on_basket_campaign_discounted_items": false,
            "expired_vouchers_regenerate_on_return": false,
            "image_url": null,
            "password_reset_url": null,
            "google_wallet_issuer_id": null,
            "myprice_app_hostname": "myprice.acme.com",
            "entity_code_custom_current_max": 20000000000,
            "max_custom_entity_code": 19999999999,
            "non_payment_state": false,
            "redemption_grace_period": 0,
            "claim_basket_user_rate_limit_unit": "hour",
            "claim_basket_user_rate_limit_quantity": 5,
            "competition_win_rate_multiplier": 1.0
        },
        "result_type": "get-chain"
    }
}

Sample response JSON (standard schema)

The following is an example response when using API version >= 2.0.0. In the standard schema, member number range fields are nested under the app object:

{
    "result": {
        "code": 1,
        "status": "ok"
    },
    "results": {
        "chain": {
            "name": "FOO Chain, inc.",
            "currency": {
                "id": 2,
                "code": "EUR",
                "name_en": "Euro",
                "symbol": "\u20ac"
            },
            "app": {
                "hostname": "myprice.acme.com",
                "max_custom_entity_code": 19999999999,
                "user_entity_code_custom_current_max": 20000000000
            },
            "businesses": [],
            "allows_double_discounting": false,
            "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,
            "exclude_rewards_on_basket_campaign_discounted_items": false,
            "expired_vouchers_regenerate_on_return": false,
            "regenerated_rewards_redeem_immediately": false,
            "return_redeem_voucher_before_cash": false,
            "receipts_service_active": false,
            "business_group_enabled": false,
            "geo_codes_user_address_info": false,
            "uses_user_address_two_field_for_shopify": false,
            "uses_third_party_voucher_id": false,
            "dummy_email_domain": null,
            "google_wallet_issuer_id": null,
            "image_url": null,
            "password_reset_url": null,
            "competition_win_rate_multiplier": 1.0,
            "created_date": "2026-01-15T10:00:00+00:00",
            "last_modified_date": "2026-03-20T14:30:00+00:00",
            "webhooks": []
        },
        "result_type": "get-chain"
    }
}

Possible error responses

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

Code Name and Description HTTP Status Code
3 http_vars_missing
Required parameter chain_id or business_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
266 access_token_invalid
The given access token is invalid		 401
424 access_denied
Access is denied		 403