Settings API

REST API endpoints for store settings and checkout consents.

Read and update general store settings, and manage the checkout consent checkboxes shown to customers. Sensitive configuration – API key hashes, Stripe credentials, and deploy config – is never exposed by these endpoints. Appearance, socials, brand kit, and loyalty have their own endpoints.

Get Settings

GET /api/v1/settings

Returns general store settings. The subdomain, domain, environment, email-domain fields, and inventory are read-only – they cannot be changed through this endpoint.

curl -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/settings

Response

{
  "name": "Acme Goods",
  "description": "Handmade home essentials",
  "currency": "USD",
  "subdomain": "acme",
  "domain": "shop.acme.com",
  "environment": "live",
  "emailDomain": "acme.com",
  "emailDomainVerified": true,
  "published": true,
  "defaultLanguage": "en-US",
  "enabledLanguages": { "en-US": true },
  "enabledCurrencies": ["USD"],
  "notificationEmail": "team@acme.com",
  "contactRoutingEmails": { "sales": "sales@acme.com", "support": "help@acme.com" },
  "outboundEmail": "hello@acme.com",
  "aiInstructions": null,
  "omnibus": false,
  "customerAccountSignUp": true,
  "taxBehavior": "exclusive",
  "logo": null,
  "welcomeOffer": null,
  "newsletterPopup": null,
  "newsletter": null,
  "stockHold": null,
  "invoiceSettings": null,
  "bankTransfer": null,
  "cashOnDelivery": null,
  "emailTracking": null,
  "blogSettings": null,
  "bookings": null,
  "cartRecommendations": null,
  "checkoutAppearance": null,
  "storeChat": null,
  "inventory": { "lowStockThreshold": 10 }
}

Read-only fields

inventory.lowStockThreshold is the merchant's own low-stock band, set in the dashboard under Settings → Notifications. It is always a number: the platform default of 10 when the merchant never chose one, and 0 when the band is switched off. It is the same number the dashboard, the low-stock email, and the platform storefront use, so a storefront rendering an "only N left" line should read it here instead of hard-coding a threshold:

const { inventory } = await getSettings();
const showLowStock =
  inventory.lowStockThreshold > 0 &&
  variant.stock !== null &&
  variant.stock <= inventory.lowStockThreshold;

Update Settings

PATCH /api/v1/settings

Partially updates general store settings. Only the fields you send are changed; the read-only fields listed above (subdomain, domain, environment, emailDomain, emailDomainVerified, inventory) are ignored if included, and any other unknown field is rejected with a 400. Module toggles are not settings – they live on PATCH /api/v1/modules. Returns the full, updated settings object.

Grouped settings merge rule

Every grouped setting (the object fields below) follows one rule: send only the fields you are changing; null on a field clears that field; null on the entire group removes the whole group. A write never requires a read first.

Request Body – Top-level Fields

Request Body – welcomeOffer

Newsletter welcome email: automatically email every new subscriber the newsletter_welcome email, with or without a discount code. With double opt-in on, it goes out once the subscriber confirms. Pass null to remove the group.

Request Body – newsletterPopup

Newsletter popup copy, image, and timing. Only renders when the newsletterPopup module is enabled via PATCH /api/v1/modules. Pass null to remove the group.

Request Body – newsletter

Newsletter signup mechanics.

Request Body – stockHold

Cart stock reservations at checkout, so two shoppers cannot buy the last unit.

Request Body – invoiceSettings

Invoicing for orders. Pass null to remove the group.

Request Body – bankTransfer

Manual bank transfer at checkout. It also covers any "send money to X" method such as Interac e-Transfer. The order is placed unpaid and the shopper is emailed the payment details. It works without Stripe. Pass null to remove the group.

Request Body – cashOnDelivery

Cash on delivery at checkout for carts with something to deliver. The order is placed unpaid and marked paid later. It works without Stripe. Pass null to remove the group.

Request Body – emailTracking

Open and click tracking on outgoing store emails.

Request Body – blogSettings

House style and model strength for AI blog generation. Requires the blog module.

Request Body – bookings

Defaults and rules for the Bookings module. Individual slots are managed at /api/v1/booking-slots. Requires the bookings module.

Request Body – cartRecommendations

Cart recommendation display. Requires the cartRecommendations module.

Request Body – checkoutAppearance

Branding of the YNS-hosted checkout page. This is checkout only – the rest of the storefront's look is the storefront's own code.

Import duties are not part of a Stripe Tax total, so showCustomsNotice lets the merchant warn shoppers that a parcel crossing a border may be charged on delivery. The note renders under the order total as soon as the shopper picks a shipping country other than the country on the store's address, and a store with no address on file never shows one.

curl -X PATCH \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "checkoutAppearance": {
      "showCustomsNotice": true,
      "customsNotice": "Orders shipped outside Germany may be charged import duties on delivery."
    }
  }' \
  https://your-store.yns.store/api/v1/settings

Request Body – storeChat

Shopper-facing AI assistant: its persona, its knowledge, and its spend caps. Requires the storeChat module on a plan that grants it.

Example

curl -X PATCH \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Now shipping worldwide",
    "published": true,
    "stockHold": { "enabled": true, "holdMinutes": 15 },
    "checkoutAppearance": { "cornerRadius": "medium" }
  }' \
  https://your-store.yns.store/api/v1/settings

Response (200)

Returns the full settings object with the updated values.

Errors

List Checkout Consents

GET /api/v1/settings/checkout-consents

Returns the consent checkboxes shown at checkout, ordered by their position. Each consent includes both the stored TipTap content document and a rendered contentHtml string.

curl -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/settings/checkout-consents

Response

{
  "data": [
    {
      "id": "0191abc0-1234-7def-8000-000000000001",
      "required": true,
      "type": "general",
      "content": {
        "type": "doc",
        "content": [
          {
            "type": "paragraph",
            "content": [{ "type": "text", "text": "I accept the terms of service." }]
          }
        ]
      },
      "contentHtml": "<p>I accept the terms of service.</p>"
    }
  ],
  "meta": {
    "count": 1
  }
}

Create Checkout Consent

POST /api/v1/settings/checkout-consents

Adds a consent checkbox to checkout. Pass content as a plain string (auto-wrapped into a single paragraph) or a TipTap JSON document (type: "doc") for rich text such as links. Invalid TipTap documents are rejected with a 400.

Request Body

curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"content": "Subscribe me to the newsletter", "type": "newsletter"}' \
  https://your-store.yns.store/api/v1/settings/checkout-consents

Response (201)

{
  "id": "0191abc0-1234-7def-8000-000000000002",
  "required": false,
  "type": "newsletter",
  "content": {
    "type": "doc",
    "content": [
      {
        "type": "paragraph",
        "content": [{ "type": "text", "text": "Subscribe me to the newsletter" }]
      }
    ]
  },
  "contentHtml": "<p>Subscribe me to the newsletter</p>"
}

Get Checkout Consent

GET /api/v1/settings/checkout-consents/:id

Returns a single consent by ID. Returns 404 if the consent does not exist in this store.

curl -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/settings/checkout-consents/0191abc0-1234-7def-8000-000000000001

Update Checkout Consent

PATCH /api/v1/settings/checkout-consents/:id

Updates an existing consent. Send only the fields you want to change. Use position to reorder a consent relative to its neighbors.

Request Body

curl -X PATCH \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"required": true}' \
  https://your-store.yns.store/api/v1/settings/checkout-consents/0191abc0-1234-7def-8000-000000000001

Response (200)

Returns the updated consent with content and contentHtml.

Delete Checkout Consent

DELETE /api/v1/settings/checkout-consents/:id

Removes a consent from checkout. Returns 404 if it does not exist.

curl -X DELETE \
  -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/settings/checkout-consents/0191abc0-1234-7def-8000-000000000001

Response (200)

{
  "ok": true,
  "deleted": 1
}