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 currency, 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",
  "outboundEmail": "hello@acme.com",
  "aiInstructions": null,
  "omnibus": false
}

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.

Request Body

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

Response (200)

Returns the full settings object with the updated values.

{
  "name": "Acme Goods",
  "description": "Now shipping worldwide",
  "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",
  "outboundEmail": "hello@acme.com",
  "aiInstructions": null,
  "omnibus": false
}

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
}