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, and email-domain fields 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,
  "taxBehavior": "exclusive",
  "logo": null,
  "welcomeOffer": null,
  "newsletterPopup": null,
  "newsletter": null,
  "stockHold": null,
  "invoiceSettings": null,
  "emailTracking": null,
  "blogSettings": null,
  "bookings": null,
  "cartRecommendations": null,
  "checkoutAppearance": null,
  "storeChat": null
}

Update Settings

PATCH /api/v1/settings

Partially updates general store settings. Only the fields you send are changed; read-only fields are ignored if included. 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 discount: automatically email a discount code to every new subscriber. 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 – 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.

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
}