Settings
Almost every "why did it behave that way" question in this section ends at a setting. The commerce apps put policy in settings.json rather than in code, so a merchant changes it and no release happens — and one gateway route reads the resolved answer.
Read an app's effective settings
curl "https://api.revenexx.com/v1/settings/apps/inventories?market=de" \
-H "X-Revenexx-Tenant: <TENANT_SLUG>" \
-H "X-Revenexx-Api-Key: rvxk_..."
| Response key | Is |
|---|---|
app | The app these settings belong to. |
settings | Setting key → effective value. |
market | The market the values were resolved for; absent or null when tenant-level. |
masked | The keys of sensitive settings: present here but omitted from settings. |
The market query parameter resolves market-scoped settings for that market code and falls back to the tenant value. Omit it for the tenant-level answer.
settings.json generates. If your integration needs to change one, that is a Cockpit action, not an API call you make.The precedence
per-market value → tenant value → the schema's declared default
Three consequences worth planning for:
- A setting always has a value. Every declared setting carries a default, so a fresh tenant that has configured nothing still behaves.
- A market-scoped setting falls back, it does not disappear. Reading one for a market nobody configured gives the tenant value.
- A tenant-scoped setting ignores
market. Passing a market code to a setting declaredscope: "tenant"changes nothing.
Sensitive settings are masked
A setting declared sensitive is stored encrypted and never returned in settings — its key appears in masked instead. That is how a form can show "a value is set" without reading it back, and it is the same rule PSP credentials follow in the payments app.
To rotate one, write the new value. There is no way to read the current one.
What a setting looks like
A setting is declared in the owning app's settings.json, which is an App Studio file — see App model. The shape matters here because it is what the route answers about:
{
"$schema": "https://schemas.revenexx.com/settings.schema.json",
"settings": {
"allocation_strategy": {
"title": { "en": "Allocation strategy", "de": "Zuteilungsstrategie" },
"description": { "en": "How a reservation picks its location." },
"type": "enum",
"scope": "market",
"default": "priority",
"enum_values": ["priority", "nearest", "single_location"],
"group": "allocation"
}
}
}
| Field | Note |
|---|---|
type | string, number, boolean, enum or json. It picks the Cockpit form input. |
scope | tenant (one value globally) or market (per market, with tenant fallback). |
default | Required in practice — it is what makes a fresh tenant work. |
vocabulary | A qualified {app}.{name} id supplying the options, instead of retyping them. Use it whenever the owning app lets a tenant edit those values. |
enum_values | The fallback when vocabulary is also set — used only while the owning app cannot answer. |
sensitive | Stored encrypted, masked on read. |
group | Settings sharing a group render under one collapsible section. |
A market-scoped setting requires the markets app as a dependency.
X-Revenexx-Market — what it actually does
This is the header most worth getting right, and its effect on a write and a read are not the same thing.
On a write it assigns
Creating a row with the header records that row against that market, and it is then visible only there. Creating one without leaves it unassigned.
On a read it is normally a no-op
The market filter lives in the scoped database views, and capability routes read the underlying tables — so a list or a get returns the same rows whether or not you send the header. Omitting it does not restrict you to global rows.
Two exceptions
POST /v1/prices/resolve and POST /v1/shipping/rates do read through scoped views. There the header restricts the candidate price lists and shipping methods to this market plus the unassigned ones.
It is never a security boundary
The tenant is fixed by the credential. A market is a business context, not an access control.
See Market concept for making your own app's entities market-scoped, and Markets for what a market holds.
Settings named in this section
A partial index, to save you hunting. Read the live definitions from the route above; these are the ones this section's pages refer to.
| App | Settings |
|---|---|
| products | new_products_enabled_by_default, default_product_family, default_label_attribute, default_asset_family, allow_external_media, external_media_allowed_hosts |
| customers | registration_mode, registration_reason_disclosed, organization_vat_id_required, primary_contact_required, blocked_contact_behavior, custom_roles_enabled |
| carts | multi_cart_enabled, cart_merge_strategy, price_snapshot_mode, convert_reserves_stock, abandon_after_minutes, cart_ttl_days, guest_cart_ttl_days |
| orderlists | default_kind, max_items_per_list, max_lists_per_owner, cart_merge_mode |
| orders | order_number_range_code, delivery_number_range_code, return_number_range_code, auto_complete_on, on_hold_blocks, cancel_requires_reason, allow_modification_after_acknowledge, require_approval_above_value, max_items_per_order, default_comment_visibility, default_currency |
| inventories | default_location_code, allocation_strategy, backorder_policy, reservation_ttl_minutes, movement_reason_required, restock_on_return_default, reorder_point_default, reorder_alert_enabled |
| prices | default_price_list_code, price_list_priority_tiebreak |
| payments | default_provider, auto_capture_policy, capture_expiry_days, refund_window_days, payment_reminder_after_days, overdue_after_days, webhook_stale_after_minutes, fee_display |
| shipping | shipping_tax_class |
| markets | fallback_locale, prices_include_tax, locale_granularity, locale_fallback |
| channels | unassigned_channel_visibility |
Where to go next
- Markets — what a market is, and its readiness.
- Market concept — declaring your own entities market-scoped.
- App model — where
settings.jsonsits among an app's files. - Value lists — the other configuration surface, which is data rather than settings.