> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.suby.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# Update checkout branding

> Partial update. At least one field is required.



## OpenAPI

````yaml /v3-beta/api-reference/openapi.yaml patch /v3/checkout-settings
openapi: 3.1.0
info:
  title: Suby.fi Merchant API
  version: 3.0.0-beta
  description: >
    The **v3** public merchant API for Suby.fi. RESTful (plural,
    resource-oriented

    endpoints under the `/v3` prefix). Authenticate every request

    with your secret API key in the `X-Suby-Api-Key` header.


    - `sk_live_…` keys operate in **production** (real funds).

    - `sk_sandbox_…` keys operate in a fully simulated **sandbox** (test cards,
      Base Sepolia crypto, no real money). The environment is derived from the
      key prefix.

    All monetary amounts are **integer cents** (except `priceCents` on some

    read shapes, which is a string) — token amounts are strings in the smallest

    unit (sats / lamports / wei). Fees are basis points.
  contact:
    email: dev@suby.fi
    url: https://suby.fi
servers:
  - url: https://api.beta.suby.fi
    description: Production + sandbox (environment selected by API key prefix)
security:
  - ApiKeyAuth: []
tags:
  - name: Products
    description: Manage your product catalog (one-time and recurring).
  - name: Checkout
    description: >-
      Hosted checkout — signed session tokens (`cs_…`) plus branding and
      appearance settings.
  - name: Payments
    description: >-
      Create, capture, void, and retrieve one-time & off-session payments (card,
      APM, and crypto).
  - name: Subscriptions
    description: Start and cancel recurring subscriptions.
  - name: Customers
    description: First-class customer records with billing address.
  - name: Payment Methods
    description: >-
      Save a payment method to a customer and manage saved instruments for
      off-session charges.
  - name: Webhook Endpoints
    description: Register outbound webhook destinations and rotate signing secrets.
  - name: Analytics
    description: Org-wide revenue analytics.
  - name: Health
    description: Unauthenticated liveness probe.
paths:
  /v3/checkout-settings:
    patch:
      tags:
        - Checkout
      summary: Update checkout branding
      description: Partial update. At least one field is required.
      operationId: updateCheckoutSettings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                logoUrl:
                  type: string
                  format: uri
                  maxLength: 2048
                  nullable: true
                headline:
                  type: string
                  maxLength: 120
                  nullable: true
                payButtonLabel:
                  type: string
                  maxLength: 40
                  nullable: true
                supportEmail:
                  type: string
                  format: email
                  maxLength: 320
                  nullable: true
                termsUrl:
                  type: string
                  format: uri
                  maxLength: 2048
                  nullable: true
                privacyUrl:
                  type: string
                  format: uri
                  maxLength: 2048
                  nullable: true
                showSubyBadge:
                  type: boolean
                appearance:
                  type: object
                  nullable: true
                  additionalProperties: true
                  description: >-
                    Theme overrides (validated allowlist). `null` resets to
                    defaults.
                layout:
                  type: object
                  nullable: true
                  additionalProperties: true
                  description: Layout config (validated allowlist).
      responses:
        '200':
          description: Settings updated
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessEnvelope'
                  - properties:
                      data:
                        $ref: '#/components/schemas/CheckoutSettings'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
components:
  schemas:
    SuccessEnvelope:
      type: object
      required:
        - success
        - data
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
        data:
          description: Endpoint-specific payload.
    CheckoutSettings:
      type: object
      properties:
        organizationId:
          type: string
        logoUrl:
          type: string
          nullable: true
        headline:
          type: string
          nullable: true
        payButtonLabel:
          type: string
          nullable: true
        supportEmail:
          type: string
          nullable: true
        termsUrl:
          type: string
          nullable: true
        privacyUrl:
          type: string
          nullable: true
        showSubyBadge:
          type: boolean
        appearance:
          type: object
          nullable: true
          additionalProperties: true
        layout:
          type: object
          nullable: true
          additionalProperties: true
        updatedAt:
          type: string
          format: date-time
    Error:
      type: object
      required:
        - success
        - error
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          description: Machine-readable error code.
          example: NOT_FOUND
        message:
          type: string
          example: Resource not found
        data:
          description: Optional error detail.
    ValidationErrorEnvelope:
      allOf:
        - $ref: '#/components/schemas/Error'
        - type: object
          properties:
            data:
              type: object
              properties:
                fieldErrors:
                  type: array
                  items:
                    type: object
                    properties:
                      field:
                        type: string
                      message:
                        type: string
  responses:
    Unauthorized:
      description: Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error: UNAUTHORIZED
            message: Invalid or missing API key
    ValidationError:
      description: Request failed schema validation
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationErrorEnvelope'
          example:
            success: false
            error: VALIDATION_ERROR
            message: Validation failed
            data:
              fieldErrors:
                - field: method
                  message: method is a required field
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Suby-Api-Key
      description: Secret API key. `sk_live_…` (production) or `sk_sandbox_…` (sandbox).

````