/settings

Overview

Retrieves the current business configuration: branding URLs, feature flags, payment settings, tier configuration, and the default accumulation rate. No member lookup is performed; only standard authentication headers are required.

When to Use This Endpoint

Use this endpoint to:

• Retrieve business configuration at startup or when settings change
• Display business-specific branding and URLs to customers
• Access tier and payment settings for transaction processing
• Fetch active location list for multi-branch operations
• Retrieve registration form field configuration

Key Considerations

• Settings are cached by the business; changes may take a few minutes to propagate
• The locationList is only included when includeLocations: true is passed
• The registrationFormFields are only included when includeRegFormFields: true is passed
• All URLs must be validated and may contain trailing slashes

Request Details

Method & URL

POST /settings

See API Servers for the base URL to use in place of {{server}}.

Headers

Header	Type	Required	Description
x-api-key	string	Yes	Business API key
x-source-type	string	Yes	Source type (e.g., POS, KIOSK)
x-source-name	string	Yes	Source name (e.g., MyPOS)
x-pos-id	string	Yes	POS terminal identifier
x-branch-id	string	Yes	Branch identifier

Request Body

Field	Type	Required	Default	Description
includeLocations	boolean	No	false	When true, includes the full active location list
includeRegFormFields	boolean	No	false	When true, includes the registration form field configuration

Request Example

With Options

{
  "includeLocations": true,
  "includeRegFormFields": false
}

Minimal

{}

cURL Example

curl --location --request POST 'https://{{server}}/v1/settings' \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: {{api-key}}' \
--header 'X-Source-Type: POS' \
--header 'X-Source-Name: MyPOS' \
--header 'X-Pos-Id: POS001' \
--header 'X-Branch-Id: BR001' \
--data-raw '{
  "includeLocations": true,
  "includeRegFormFields": false
}'

Success Response

200 OK

{
  "status": "active",
  "id": "business-id",
  "name": "My Business",
  "businessPlan": "Custom",
  "activeLocations": 3,
  "mainURL": "https://example.com",
  "fallbackURL": "https://fallback.example.com",
  "settings": {
    "timezone": "Europe/Istanbul",
    "currency": "TRY",
    "termsLink": "https://example.com/terms",
    "GDPRLink": "https://example.com/gdpr",
    "logoURL": "https://example.com/logo.png",
    "faviconURL": "https://example.com/favicon.ico",
    "allowedIdentifiers": [
      "phoneNumber",
      "email",
      "appClientId",
      "cardNumber",
      "commonExtId",
      "customIdentifier"
    ],
    "autoRegistration": false,
    "paymentSettings": {
      "paymentWallet": "credits",
      "paymentMethod": "meanOfPayment",
      "paymentRate": 1
    },
    "defaultAccumulationRate": {
      "rate": 0.05,
      "percentage": 5
    },
    "tierSettings": {}
  },
  "locationList": [
    {
      "status": "active",
      "branchId": "BRANCH-01",
      "name": "BRANCH-01"
    }
  ]
}

Response Fields

Field	Type	Description
status	string	Status of the business (e.g., active or pipeline)
id	string	Business ID
name	string	Business display name
businessPlan	string	Subscription plan name; defaults to "Custom"
activeLocations	number	Count of active locations
mainURL	string	Primary business URL
fallbackURL	string	Fallback URL
settings.timezone	string	IANA timezone (e.g., Europe/Istanbul)
settings.currency	string	Currency code (e.g., TRY, EUR)
settings.termsLink	string	URL to terms of use
settings.GDPRLink	string	URL to GDPR policy
settings.logoURL	string	Business logo URL
settings.faviconURL	string	Favicon URL
settings.allowedIdentifiers	string[]	Member identifier types accepted by this business
settings.autoRegistration	boolean	Whether auto-registration on first purchase is enabled
settings.paymentSettings.paymentWallet	string	credits or points
settings.paymentSettings.paymentMethod	string	e.g., meanOfPayment
settings.paymentSettings.paymentRate	number	Payment rate multiplier
settings.defaultAccumulationRate	object	(Conditional) Present only when accumulationRuleId is configured
settings.defaultAccumulationRate.rate	number	Rate as a decimal (e.g., 0.05 = 5%)
settings.defaultAccumulationRate.percentage	number	Rate as a whole percentage (e.g., 5)
settings.tierSettings	object	(Conditional) Present only when tier feature is enabled
locationList	array	(Conditional) Present only when includeLocations: true
locationList[].status	string	Location status
locationList[].branchId	string	Branch identifier
locationList[].name	string	Branch display name
registrationFormFields	array	(Conditional) Present only when includeRegFormFields: true

info

The following fields are conditionally present in the response:

• settings.defaultAccumulationRate — Only included when an accumulation rule is configured for the business
• settings.tierSettings — Only included when tier features are enabled and tiers are configured
• locationList — Only included when includeLocations: true
• registrationFormFields — Only included when includeRegFormFields: true

Error Response Examples

Missing API Key

{
  "status": "error",
  "error": {
    "code": "101",
    "message": "X-Api-Key is required"
  }
}

Business Not Found

{
  "status": "error",
  "error": {
    "code": "001",
    "message": "Business not found for the given API key"
  }
}

Missing Required Header

{
  "status": "error",
  "error": {
    "code": "102",
    "message": "X-Source-Type is required"
  }
}

Error Codes

HTTP Status	Code	Description
400	001	Business not found for the given API key
400	101	Missing X-Api-Key header
400	102	Missing X-Source-Type header
400	103	Missing X-Source-Name header
400	104	Missing X-Pos-Id header
400	105	Missing X-Branch-Id header

Field Reference

Field	Type	Description
timezone	string	IANA timezone identifier (e.g., Europe/Istanbul, America/New_York)
currency	string	ISO 4217 currency code (e.g., TRY, EUR, USD)
paymentWallet	string	Payment asset type: credits or points
paymentRate	number	Multiplier for payment calculations
defaultAccumulationRate	object	Default rate configuration for earning loyalty currency
allowedIdentifiers	string[]	List of member identifier fields accepted by the business
autoRegistration	boolean	Flag for automatic member registration on first purchase

Related Use Cases

• Initializing POS systems with business configuration at startup
• Displaying business branding and URLs in customer-facing interfaces
• Fetching location list for multi-branch checkout workflows
• Retrieving payment and accumulation settings for transaction processing
• Building dynamic registration forms with business-specific fields
• Displaying terms and GDPR links to customers before registration