settings - BevvyTech/BrewskiDocs GitHub Wiki

Settings

Method Path Description
GET /settings Retrieve team profile plus billing/payment defaults.
PUT /settings Update team settings (owner/admin only).
PUT /settings/wizard/operating-mode Save the setup wizard operating mode step (owner/admin only).
PUT /settings/wizard/info Save the setup wizard info step (owner/admin only).
PUT /settings/wizard/shop Save the setup wizard shop step (owner/admin only).
PUT /settings/wizard/invoicing Save the setup wizard invoicing step (owner/admin only).
PUT /settings/wizard/terms Save the setup wizard payment terms step (owner/admin only).
GET /settings/storage/state Issue signed state for third-party storage integrations.
GET /settings/storage/dropbox/callback Dropbox OAuth callback handler.
GET /settings/storage/google-drive/callback Google Drive OAuth callback handler.

GET /settings

  • Query Parameters: teamId (uuid, required)
  • Response 200: 
    {
  "teamId": "d43c046a-10a1-4f52-bd0a-9bf16f828ab7",
  "teamName": "Lantern Brewery",
  "currencySymbol": "£",
  "temperatureUnit": "celsius",
  "locale": "en-GB",
  "obscureBatchCode": true,
  "obscureOrderNumber": true,
  "brewhouseCapacity": 1000,
  "defaultContainers": [
    { "id": "d7f82a16-dadf-4f76-8e4e-19449ac7e81e", "priceMinor": 450, "selected": true },
    { "id": "59ab0f91-2fbf-4d8d-913f-8a5678c2ce61", "selected": false }
  ],
  "billingName": "Lantern Brewery Ltd",
  "billingAddress": "1 Brew Street, London",
  "vatNumber": "GB123456789",
  "paymentDetails": "Bank transfer preferred",
  "invoiceTerms": "Payment due within 14 days",
  "defaultPaymentTermsAmount": 14,
  "defaultPaymentTermsUnit": "days",
  "deposits": {
    "keg": { "enabled": true, "amountMinor": 2500 },
    "cask": { "enabled": false, "amountMinor": null }
  },
  "dropboxConnected": false,
  "dropboxExpiresAt": null,
  "googleDriveConnected": false,
  "googleDriveExpiresAt": null,
  "location": {
    "town": "Bristol",
    "country": "GB"
  },
  "info": {
    "notes": "Reserved for future use",
    "publicDescription": "Wild-fermented saisons brewed in Bristol.",
    "publicEmail": "[email protected]",
    "publicTelephone": "+44 20 7946 0992",
    "publicWebsite": "https://lantern.example/",
    "soldByDisclaimer": "Sold and shipped by Lantern Brewery Ltd.",
    "socialLinks": {
      "instagram": "https://instagram.com/lanternbrew",
      "tiktok": "https://www.tiktok.com/@lanternbrew"
    }
  },
  "awrsUrn": "XAW12345678901",
  "awrsVerified": true,
  "hasOffLicenceShipping": true,
  "offLicenceApproved": true
}

PUT /settings

  • Body (partial updates allowed): 
    {
  "teamId": "d43c046a-10a1-4f52-bd0a-9bf16f828ab7",
  "currencySymbol": "€",
  "locale": "de-DE",
  "obscureBatchCode": true,
  "obscureOrderNumber": true,
  "defaultPaymentTermsAmount": 30,
  "defaultPaymentTermsUnit": "days",
  "deposits": {
    "keg": { "enabled": true, "amountMinor": 2500 },
    "cask": { "enabled": null, "amountMinor": null }
  },
  "awrsUrn": "XAW12345678901",
  "hasOffLicenceShipping": true,
  "offLicenceApproved": true,
  "info": {
    "publicDescription": "Wild-fermented saisons brewed in Bristol.",
    "publicEmail": "[email protected]",
    "publicTelephone": "+44 20 7946 0992",
    "publicWebsite": "https://lantern.example/",
    "soldByDisclaimer": "Sold and shipped by Lantern Brewery Ltd.",
    "socialLinks": {
      "instagram": "https://instagram.com/lanternbrew"
    }
  },
  "defaultContainers": [
    { "id": "d7f82a16-dadf-4f76-8e4e-19449ac7e81e", "priceMinor": 450, "selected": true }
  ]
}
  • Notes:
    • teamName can be updated here or via PATCH /teams/:teamId.
    • location expects ISO 3166-1 alpha-2 country codes (country) and freeform town/city names.
    • info controls the public shop profile. publicDescription (≤ 650 chars) and publicEmail must be supplied; publicTelephone, publicWebsite, and soldByDisclaimer are optional. Social links accept twitter, facebook, instagram, youtube, tiktok, threads keys and are only persisted when they validate as https:// URLs.
    • awrsUrn is required for trading teams; providing a new value resets awrsVerified to false. hasOffLicenceShipping combined with offLicenceApproved drives the storefront badge (“Can sell direct” vs “Ships to approved locations & wholesale”).
    • deposits customise keg/cask deposit defaults. Provide null for enabled or amountMinor to fall back to Brewski-wide defaults; otherwise supply explicit toggles and per-container prices in minor units.
  • Response 200: 
    {
  "settings": {
    "teamId": "d43c046a-10a1-4f52-bd0a-9bf16f828ab7",
    "teamName": "Lantern Brewery",
    "currencySymbol": "€",
    "locale": "de-DE",
    "obscureBatchCode": true,
    "obscureOrderNumber": true,
    "billingName": "Lantern Brewery Ltd",
    "billingAddress": "1 Brew Street, London",
    "vatNumber": "GB123456789",
    "paymentDetails": "Bank transfer preferred",
    "invoiceTerms": "Payment due within 14 days",
    "defaultPaymentTermsAmount": 30,
    "defaultPaymentTermsUnit": "days",
    "deposits": {
      "keg": { "enabled": true, "amountMinor": 2500 },
      "cask": { "enabled": null, "amountMinor": null }
    },
    "defaultContainers": [
      { "id": "d7f82a16-dadf-4f76-8e4e-19449ac7e81e", "priceMinor": 450, "selected": true }
    ],
    "dropboxConnected": false,
    "dropboxExpiresAt": null,
    "googleDriveConnected": false,
    "googleDriveExpiresAt": null,
    "location": {
      "town": "Bristol",
      "country": "GB"
    },
    "info": {
      "notes": "Reserved for future use",
      "publicDescription": "Wild-fermented saisons brewed in Bristol.",
      "publicEmail": "[email protected]",
      "publicTelephone": "+44 20 7946 0992",
      "publicWebsite": "https://lantern.example/",
      "soldByDisclaimer": "Sold and shipped by Lantern Brewery Ltd.",
      "socialLinks": {
        "instagram": "https://instagram.com/lanternbrew",
        "tiktok": "https://www.tiktok.com/@lanternbrew"
      }
    },
    "awrsUrn": "XAW12345678901",
    "awrsVerified": true,
    "hasOffLicenceShipping": true,
    "offLicenceApproved": true,
    "updatedAt": "2025-02-04T12:22:00.000Z"
  }
}
  • Errors: 403 if caller is not owner/admin, 404 if team missing.
  • Batch code preferences: Toggle obscureBatchCode to have the API generate five-character alphanumeric batch codes whenever batchCode is omitted during creation. New teams have this enabled by default; disabling it reverts to the BATCH-YYYYMMDD-XXXX pattern.
  • Order number preferences: Toggle obscureOrderNumber to randomise order numbers (ORD-YYYYMMDD-XXXX) whenever one isn’t supplied. New teams have this enabled by default; disabling it restores sequential ORD-00001 identifiers.

Setup Wizard Endpoints

All setup wizard endpoints include the same settings payload in their 200 OK responses as PUT /settings. Requests must originate from an owner or admin of the target team. These routes allow wizard sections to save independently so validation in one step doesn’t block others.

PUT /settings/wizard/operating-mode

  • Body: 
    {
  "teamId": "d43c046a-10a1-4f52-bd0a-9bf16f828ab7",
  "operatingMode": "strict"
}
  • Notes: operatingMode accepts strict, hybrid, or shop. Teams created without a choice remain on none until this endpoint succeeds.

PUT /settings/wizard/info

  • Body: 
    {
  "teamId": "d43c046a-10a1-4f52-bd0a-9bf16f828ab7",
  "currencySymbol": "£",
  "locale": "en-GB",
  "obscureBatchCode": true,
  "obscureOrderNumber": true,
  "location": { "town": "Bristol", "country": "GB" },
  "publicSite": {
    "enabled": false,
    "webTitle": "Lantern Brewery",
    "webSubtitle": "Wild-fermented saisons",
    "backgroundColor": "#ffffff",
    "textColor": "#000000",
    "useTeamLogo": true,
    "logoBackgroundColor": "#ffffff",
    "logoCornerRadius": 4,
    "showPrices": false,
    "pricebookId": null,
    "slug": "lantern-brewery"
  }
}
  • Notes: Public site payload mirrors the general settings endpoint—if the site is enabled, a unique slug is required. This call never mutates AWRS data.

PUT /settings/wizard/shop

  • Body: 
    {
  "teamId": "d43c046a-10a1-4f52-bd0a-9bf16f828ab7",
  "publicSite": { "enabled": true, "slug": "lantern-brewery", "webTitle": "Lantern Brewery", "webSubtitle": "Wild-fermented saisons", "backgroundColor": "#ffffff", "textColor": "#101828", "useTeamLogo": true, "logoBackgroundColor": "#ffffff", "logoCornerRadius": 4, "showPrices": true, "pricebookId": null },
  "info": {
    "notes": "",
    "publicDescription": "Wild-fermented saisons brewed in Bristol.",
    "publicEmail": "[email protected]",
    "publicTelephone": "+44 20 7946 0992",
    "publicWebsite": "https://lantern.example/",
    "soldByDisclaimer": "Sold and shipped by Lantern Brewery Ltd.",
    "socialLinks": { "instagram": "https://instagram.com/lanternbrew" }
  },
  "awrsUrn": "XAW12345678901",
  "hasOffLicenceShipping": true,
  "offLicenceApproved": false
}
  • Notes: AWRS numbers are normalised (XAW###########) and required on this step. Providing a new AWRS resets awrsVerified to false. Social links must be full https:// URLs.

PUT /settings/wizard/invoicing

  • Body: 
    {
  "teamId": "d43c046a-10a1-4f52-bd0a-9bf16f828ab7",
  "billingName": "Lantern Brewery Ltd",
  "billingAddress": "1 Brew Street, London",
  "vatNumber": "GB123456789",
  "paymentDetails": "Bank transfer preferred",
  "invoiceTerms": "Payment due within 14 days"
}
  • Notes: Blank strings are coerced to null so documents omit unset fields.

PUT /settings/wizard/terms

  • Body: 
    {
  "teamId": "d43c046a-10a1-4f52-bd0a-9bf16f828ab7",
  "defaultPaymentTermsAmount": 30,
  "defaultPaymentTermsUnit": "days"
}
  • Notes: Amount must be between 1 and 365. These defaults feed client and order creation flows.

GET /settings/storage/state

  • Auth: Bearer token (owner/admin).
  • Query Parameters: teamId (uuid, required)
  • Response 200: 
    {
  "state": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
    Use the signed state value when kicking off Dropbox/Google Drive OAuth flows.

GET /settings/storage/dropbox/callback

  • Auth: Public OAuth redirect; validated via state token.
  • Query Parameters (from Dropbox OAuth redirect):
    • state (required) – signed token produced by /settings/storage/state
    • access_token, refresh_token, expires_in (optional)
  • Behaviour: Stores tokens against the team and returns an HTML success message.
  • Errors: 400 invalid payload/state, 403 unauthorized state, 500 on storage failure.

GET /settings/storage/google-drive/callback

  • Same contract as the Dropbox callback but persists Google Drive tokens.
⚠️ **GitHub.com Fallback** ⚠️