Settings

GET   /v1/settings
PATCH /v1/settings

One curated resource for the venue's configuration. GET returns the current values; PATCH is a partial update — send only the fields you want to change. Available on every plan with an active subscription.

Fields#

All fields are optional in PATCH. Unknown fields are rejected with a 400 validation error naming the property — secrets and internal fields (payment/delivery-provider credentials, cached data, ids) are not part of this resource in either direction.

GET additionally returns read-only agent context:

• logoUrl — set it via the logo ingest;
• publicMenuUrl — the venue's live menu link (https://<slug>.duck-hub.com/menu) to report back when the build is done;
• lastPublishedAt — timestamp of the latest POST /v1/publish (null = never published), so you can tell whether draft changes have gone live.

Money fields (minimumOrderAmount, deliveryFee, freeDeliveryThreshold) are integers in minor currency units. defaultLanguage is always kept inside enabledLanguages automatically. Notification chat changes are audit-logged server-side.

Example#

curl -X PATCH https://api.duck-hub.com/v1/settings \
  -H "Authorization: Bearer dk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Trattoria Roma",
    "cuisineType": "Italian",
    "defaultCurrency": "EUR",
    "timezone": "Europe/Rome",
    "enabledLanguages": ["en", "it", "de"],
    "schedule": [
      { "day": "monday", "isOpen": true, "openTime": "10:00", "closeTime": "22:00" },
      { "day": "sunday", "isOpen": false }
    ]
  }'

const response = await fetch('https://api.duck-hub.com/v1/settings', {
  method: 'PATCH',
  headers: {
    Authorization: 'Bearer dk_live_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Trattoria Roma',
    cuisineType: 'Italian',
    defaultCurrency: 'EUR',
    timezone: 'Europe/Rome',
    enabledLanguages: ['en', 'it', 'de'],
  }),
})
const settings = await response.json() // the updated curated view

PATCH responds 200 with the same curated view GET returns.

Concurrency (ETag / If-Match)#

Settings can also be edited in the DuckHub app — to avoid silently overwriting a concurrent change, use optimistic concurrency:

1. GET /v1/settings returns an ETag response header.
2. Send it back on PATCH as If-Match. If the settings changed since your read (e.g. the owner edited them in the app), the PATCH fails with 412 and code STALE_RESOURCE — re-read, re-apply your change, retry.
3. Omitting If-Match keeps the old unconditional behavior.

ETAG=$(curl -si https://api.duck-hub.com/v1/settings \
  -H "Authorization: Bearer dk_live_your_api_key" \
  | grep -i '^etag:' | cut -d' ' -f2 | tr -d '\r')
 
curl -X PATCH https://api.duck-hub.com/v1/settings \
  -H "Authorization: Bearer dk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -H "If-Match: $ETAG" \
  -d '{"name": "Trattoria Roma"}'

Every PATCH response also carries the fresh ETag, so chained conditional updates don't need an extra GET. (The same pattern will apply to other single-resource endpoints as they gain conditional writes; bulk sync has no single version to match and stays unconditional.)

Errors#

• 400 Validation failed — invalid value (unsupported currency/locale, bad timezone, malformed schedule) or an unknown/secret field
• 403 DELIVERY_NOT_AVAILABLE — order-config field on a plan without the delivery feature
• 412 STALE_RESOURCE — your If-Match no longer matches (settings changed since you read them)
• 401 / 403 SUBSCRIPTION_INACTIVE — see Errors