Schema
Surcharge
Defines a surcharge that is levied by a merchant against an order, line items or selected modifiers.
Overview
Properties
uuid
The surcharge's unique identifier.
uuid
Yes
model_type
Yes
Allowed values
surchargename
The surcharge's display name.
Weekend Surcharge
1
255
tags
The surcharge's tags.
Yes
Array items
Items
uuid
calculation
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
References Calculation.
All of 2
Nested properties
type
Allowed values
fixedpercentageproduct_group
The UUID of the product group used for matching, or null for an order-scoped surcharge.
uuid
Yes
availability
References Availability.
auto_apply
Indicates if this surcharge will automatically apply, assuming all other conditions are met.
apply_to_free_items
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.
false
tax_exempt
Indicates if this surcharge is exempt from tax calculations.
false
created_at
The date-time that the surcharge was created.
date-time
Yes
Used by
Raw YAML
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