Deposit Rules

A shop can hold a different security deposit in specific situations - a long rental, or a customer a long way from them. Each rule is one sentence: when <situation> the deposit is <amount>.

How they resolve. Every rule is evaluated against the booking and the highest matching amount wins. A percentage rule is resolved against the pre-tax subtotal before that comparison, so amounts and percentages can sit in the same list. A product carrying its own deposit amount still beats every rule. Nothing matching means the shop's flat deposit, and a shop whose deposit switch is off takes no deposit at all - a rule does not override that switch.

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

Endpoints

GET    /v1/settings/deposit-rules
POST   /v1/settings/deposit-rules
PATCH  /v1/settings/deposit-rules/{id}
DELETE /v1/settings/deposit-rules/{id}

Authentication

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

The shape of a rule

The same flat shape the in-app assistant uses, so a rule reads the same way whichever wrote it.

Field	Type	Description
id	integer	Read-only.
sort	integer	Position in the list, lowest first. Does not affect which rule wins.
situation	string	rental_length, outside_home_area or specific_places.
longer_than_minutes	integer or null	For rental_length: the shortest booking this applies to. 28 days is 40320. A booking of exactly that length matches.
places	array	For specific_places: "COUNTRY-SUBDIVISION" codes from the shop's own country, e.g. ["US-TX", "US-NY"]. A code outside that list is rejected, so a typo is an error rather than a rule that never matches. Up to 200.
postcodes	array	For specific_places: postcode starts, e.g. ["302"], matching anything beginning with them. These add to places rather than replacing them - a rule matches a customer in either. Up to 200.
and_situation	string or null	An optional second condition that must ALSO be true.
and_longer_than_minutes, and_places, and_postcodes		The second condition's values.
amount	number	The deposit this rule asks for. Must be more than zero.
amount_type	string	fixed or percentage. A percentage cannot be more than 500 - deliberately generous, since a deposit above the booking value is normal. A fixed amount is not capped.
reads_as	string	Read-only: the sentence the rule reads as, and what a booking it sets keeps as its security_deposit_basis.

Create a rule

curl -X POST "https://app.equipdash.com/api/v1/settings/deposit-rules" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "situation": "specific_places",
    "places": ["US-TX", "US-NY"],
    "postcodes": ["302"],
    "amount": 2000
  }'

Success (201 Created)

{
  "data": {
    "id": 7,
    "sort": 0,
    "situation": "specific_places",
    "longer_than_minutes": null,
    "places": ["US-TX", "US-NY"],
    "postcodes": ["302"],
    "and_situation": null,
    "amount": 2000,
    "amount_type": "fixed",
    "reads_as": "In Texas, New York or postcode 302"
  },
  "meta": { "request_id": "...", "timestamp": "..." }
}

Change a rule

Fields you leave out keep their current value, so changing an amount does not mean resending the whole rule.

curl -X PATCH "https://app.equipdash.com/api/v1/settings/deposit-rules/7" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 1500 }'

Errors

Status	When
404	No rule with that id on your account.
422	situation names a situation with no value to test (no length, and no places or postcodes); the amount is zero or less; a percentage amount is over 500; amount_type is not fixed/percentage; or a place is not one of the shop's own country's subdivisions.