title: Surcharge Request
x-tags:
  - Catalog
type: object
description: On edit, omitted top-level properties retain their existing values.
properties:
  name:
    type: string
    minLength: 1
    maxLength: 255
  tags:
    allOf:
      - $ref: ./CatalogUuidList.yaml
    description: UUIDs of tags to associate with the surcharge.
  calculation:
    type: object
    description: Defines a fixed or percentage catalog calculation.
    required:
      - type
    properties:
      type:
        type: string
        enum:
          - fixed
          - percentage
      fixed_value:
        allOf:
          - $ref: ./Money.yaml
          - type: object
            properties:
              amount:
                minimum: 1
                maximum: 4294967295
                description: The amount in the currency's lowest denomination. Zero is not permitted.
              currency:
                description: Must match the merchant's ISO 4217 currency code.
      percentage:
        type: string
        pattern: '^((0\.[1-9])|([1-9]([0-9])?(\.[0-9])?)|100)$'
        description: A percentage between 0.1 and 100 inclusive, with at most one decimal place.
      percentage_cap:
        default: null
        oneOf:
          - type: 'null'
          - allOf:
              - $ref: ./Money.yaml
              - type: object
                properties:
                  amount:
                    minimum: 1
                    maximum: 4294967295
                    description: The amount in the currency's lowest denomination. Zero is not permitted.
                  currency:
                    description: Must match the merchant's ISO 4217 currency code.
    oneOf:
      - properties:
          type:
            const: fixed
        required:
          - fixed_value
      - properties:
          type:
            const: percentage
        required:
          - percentage
  product_group:
    type:
      - string
      - 'null'
    format: uuid
    description: The UUID of a product group owned by the merchant. On edit, omit this property to retain the existing product group or supply `null` to remove it.
  availability:
    $ref: ./AvailabilityRequest.yaml
  auto_apply:
    type: boolean
  apply_to_free_items:
    type: boolean
    description: Controls free-item eligibility for fixed product-group surcharges. When true, zero-priced modifier selections and fully discounted lines can contribute. Stored for every calculation type, but ignored by percentage and fixed order-scoped calculations. On edit, omission retains the current value and false explicitly disables the policy.
  tax_exempt:
    type: boolean
