YQueue DocsDevelopers

Schema

Surcharge

Defines a surcharge that is levied by a merchant against an order, line items or selected modifiers.

  • Catalog

Overview

object · 11 properties · 11 required

Properties

uuid

string Required

The surcharge's unique identifier.

Format uuid
Read only Yes

model_type

enum Required
Read only Yes

Allowed values

surcharge

name

string Required

The surcharge's display name.

Example Weekend Surcharge
Min length 1
Max length 255

tags

array Required

The surcharge's tags.

Unique items Yes
Array items

Items

string
Format uuid

calculation

allOf Required

The surcharge's calculation. Surcharges may use `fixed` or `percentage` calculations. With a product group, fixed surcharges independently match parent items and explicitly listed direct and meal modifiers. Each eligible parent match contributes the fixed amount multiplied by the parent quantity. Each eligible modifier occurrence contributes the fixed amount multiplied by its selected quantity and the parent quantity. Matches are additive, including repeated occurrences of the same modifier. Contributions are combined into one item-scoped allocation per source surcharge per parent line, retaining the surcharge's name, source UUID and tax-exempt status. For percentage surcharges, product groups continue to match parent items only. Their existing bundled-value calculations and order-scoped calculations are unchanged.

All of

All of 1

reference

References Calculation.

All of 2

object
Nested properties
type
enum Required

Allowed values

fixedpercentage

product_group

string | null Required

The UUID of the product group used for matching, or null for an order-scoped surcharge.

Format uuid
Nullable Yes

availability

reference Required

References Availability.

auto_apply

boolean Required

Indicates if this surcharge will automatically apply, assuming all other conditions are met.

apply_to_free_items

boolean Required

Controls free-item eligibility for fixed surcharges with a product group. When false, skip a line if its bundled subtotal minus all discounts is zero, and skip individual zero-priced modifiers, including selections within a paid bundle. When true, those lines and modifiers remain eligible. Free status excludes existing surcharges and taxes. Stored for every calculation type, but ignored by percentage surcharges and fixed order-scoped surcharges.

Default false

tax_exempt

boolean Required

Indicates if this surcharge is exempt from tax calculations.

Default false

created_at

string Required

The date-time that the surcharge was created.

Format date-time
Read only Yes

Used by

Raw YAML
Download source
title: Surcharge
x-tags:
  - Catalog
type: object
description: Defines a surcharge that is levied by a merchant against an order, line items or selected modifiers.
required:
  - uuid
  - model_type
  - name
  - tags
  - calculation
  - product_group
  - availability
  - auto_apply
  - apply_to_free_items
  - tax_exempt
  - created_at
properties:
  uuid:
    type: string
    format: uuid
    description: The surcharge's unique identifier.
    readOnly: true
  model_type:
    enum:
      - surcharge
    readOnly: true
  name:
    type: string
    description: The surcharge's display name.
    minLength: 1
    maxLength: 255
    example: Weekend Surcharge
  tags:
    type: array
    uniqueItems: true
    description: The surcharge's tags.
    items:
      type: string
      format: uuid
  calculation:
    allOf:
      - $ref: ./Calculation.yaml
      - type: object
        required:
          - type
          - fixed_value
          - percentage
          - percentage_cap
          - price_override
        properties:
          type:
            enum:
              - fixed
              - percentage
    description: |-
      The surcharge's calculation.

      Surcharges may use `fixed` or `percentage` calculations.

      With a product group, fixed surcharges independently match parent items and explicitly listed direct and meal modifiers. Each eligible parent match contributes the fixed amount multiplied by the parent quantity. Each eligible modifier occurrence contributes the fixed amount multiplied by its selected quantity and the parent quantity. Matches are additive, including repeated occurrences of the same modifier.

      Contributions are combined into one item-scoped allocation per source surcharge per parent line, retaining the surcharge's name, source UUID and tax-exempt status.

      For percentage surcharges, product groups continue to match parent items only. Their existing bundled-value calculations and order-scoped calculations are unchanged.
  product_group:
    type:
      - string
      - 'null'
    format: uuid
    description: The UUID of the product group used for matching, or null for an order-scoped surcharge.
  availability:
    $ref: ./Availability.yaml
  auto_apply:
    type: boolean
    description: 'Indicates if this surcharge will automatically apply, assuming all other conditions are met.'
  apply_to_free_items:
    type: boolean
    default: false
    description: |-
      Controls free-item eligibility for fixed surcharges with a product group.

      When false, skip a line if its bundled subtotal minus all discounts is zero, and skip individual zero-priced modifiers, including selections within a paid bundle. When true, those lines and modifiers remain eligible. Free status excludes existing surcharges and taxes.

      Stored for every calculation type, but ignored by percentage surcharges and fixed order-scoped surcharges.
  tax_exempt:
    type: boolean
    default: false
    description: Indicates if this surcharge is exempt from tax calculations.
  created_at:
    type: string
    format: date-time
    description: The date-time that the surcharge was created.
    readOnly: true

Search documentation

Search across this documentation site.