Surcharges

A shop can charge more on chosen days of the week or dates - a weekend rate, a holiday rate. Each surcharge is one rule: on <days or dates> add <amount>, shown as <label>.

How they apply. A booking that falls on a surcharge day gets a surcharge line of its own, inside the pre-tax subtotal, so it is taxed and discounted like the items. Days are the shop's own calendar days, in its time zone.

• percent - that percent of each matching item's price. A hire that runs over several days pays it on the share of its days that fall on surcharge days: a Friday-to-Monday hire covering Friday, Saturday, Sunday and Monday pays a weekend rate on half its price.
• per_booking - once, when anything in the booking falls on a surcharge day.
• per_person - per person on the sessions that fall on a surcharge day (the largest party of any one session), or per unit of gear on a surcharge day, whichever is more.

When two rules match, both apply, each as its own line. A booking keeps the rule it was sold with - rate, unit and days or dates: changing or deleting a rule later never reprices a booking already taken. A rule added later reaches an existing booking only when its dates or items are edited. Staff can waive a surcharge on a single booking (below).

You do not have to read these rules to get the right total: POST /v1/bookings applies them, and POST /v1/pricing/calculate quotes them. These endpoints are for integrations that manage the rules themselves.

Endpoints

GET    /v1/settings/surcharges
GET    /v1/settings/surcharges/{id}
POST   /v1/settings/surcharges
PUT    /v1/settings/surcharges/{id}
DELETE /v1/settings/surcharges/{id}

Authentication

GET requires the settings:read scope. POST, PUT and DELETE require settings:write.

The shape of a surcharge

Field	Type	Description
id	integer	Read-only.
label	string	What customers see on the booking, up to 80 characters.
applies_on	string	days or dates.
days	array of integers	For days: 0 Sunday to 6 Saturday. A weekend is [6, 0].
dates	array	For dates: {"start": "YYYY-MM-DD", "end": "YYYY-MM-DD"} ranges, both ends included. A single day has the same start and end. Up to 100 per surcharge.
amount	number or null	The surcharge. null or 0 switches it off. A percent can be at most 100.
unit	string	percent, per_booking or per_person.
active	boolean	Read-only: true when it has an amount and at least one day or date.
when	string	Read-only: the days or dates in words, e.g. Sat, Sun.

Create a surcharge

curl -X POST "https://app.equipdash.com/api/v1/settings/surcharges" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Weekend surcharge",
    "applies_on": "days",
    "days": [6, 0],
    "amount": 15,
    "unit": "percent"
  }'

Success (201 Created)

{
  "data": {
    "id": 4,
    "label": "Weekend surcharge",
    "applies_on": "days",
    "days": [0, 6],
    "dates": [],
    "amount": 15,
    "unit": "percent",
    "active": true,
    "when": "Sat, Sun"
  },
  "meta": { "request_id": "...", "timestamp": "..." }
}

Refused (422)

{
  "error": { "code": "validation_error", "message": "A percent surcharge can be at most 100%.", "details": [] },
  "meta": { "request_id": "...", "timestamp": "..." }
}

Update and delete

PUT /v1/settings/surcharges/{id} takes any of the fields above and leaves the rest as they are. DELETE returns 204. A rule from another shop answers 404.

On a booking

Every booking carries the surcharges it was charged:

"surcharges": [
  { "id": 31, "label": "Weekend surcharge", "unit": "percent", "rate": 15, "amount": 12.00, "waived": false }
],
"surcharge_total": 12.00

amount is what the line adds to the booking; a waived line reads 0. POST /v1/pricing/calculate returns the same lines under surcharges, and summary.surcharge_total, and includes them in summary.subtotal_with_delivery.

Waive a surcharge on one booking

POST /v1/bookings/{id}/surcharges/{lineId}/waive

Requires bookings:write. lineId is the id from the booking's surcharges. Send {"waived": false} to put it back; the default is true. The booking is re-totaled and the change noted in its history, and the updated booking is returned. A cancelled booking answers 422; another shop's booking answers 404.