Schema
Surcharge Request
On edit, omitted top-level properties retain their existing values.
Overview
Properties
name
1
255
tags
UUIDs of tags to associate with the surcharge.
All of
All of 1
References Catalog UUID List.
calculation
Defines a fixed or percentage catalog calculation.
Nested properties
type
Allowed values
fixedpercentagefixed_value
All of
All of 1
References Money.
All of 2
Nested properties
amount
The amount in the currency's lowest denomination. Zero is not permitted.
1
4294967295
currency
Must match the merchant's ISO 4217 currency code.
percentage
A percentage between 0.1 and 100 inclusive, with at most one decimal place.
^((0\.[1-9])|([1-9]([0-9])?(\.[0-9])?)|100)$
percentage_cap
Yes
One of
One of 1
One of 2
All of
All of 1
References Money.
All of 2
Nested properties
amount
The amount in the currency's lowest denomination. Zero is not permitted.
1
4294967295
currency
Must match the merchant's ISO 4217 currency code.
One of
One of 1
Nested properties
type
fixed
One of 2
Nested properties
type
percentage
product_group
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.
uuid
Yes
availability
References Availability Request.
auto_apply
apply_to_free_items
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
Used by
Raw YAML
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