GraphQL API reference: Refundable Security Deposits

The GraphQL operations of SI Refundable Deposits. They use the same address, keys and rules as all our apps: see GraphQL API reference: Rentals & Bookings for how to send a request, and the API overview for keys, limits and errors. The same operations are in REST: REST API reference: Refundable Security Deposits.

Needs the Refundable Security Deposits app. It works on a store without Rentals & Bookings. Make the key in the app under Settings › API access; a key made in any of our apps works too, because keys belong to the store. On a store without the app, its operations are refused before anything runs, with errors[].extensions.code: "app_not_installed" and data.app: "deposits". Every operation needs a secret key; mutations need Allow changes (write).

Refunds go to the original payment method. The app sends Shopify an idempotency key built from the order, the deposits and what they had refunded before, so a retried request can’t refund twice; a deposit already refunded answers nothing_to_refund. Amounts are decimal strings.

Operations #

Operation	Arguments	What it does
rentalOrderDeposits query · secret key returns RentalOrderDeposits!	orderId: ID! refresh: Boolean = false	An order’s deposits: held, refunded, remaining, and when the rest is refunded automatically.
rentalDepositProducts query · secret key returns [RentalProductDepositRule!]!	–	The products with their own deposit rule (the others use the store default).
rentalProductDepositRule query · secret key returns RentalProductDepositRule!	productId: ID!	A product’s deposit rule: its own, or the store default (source).
refundRentalDeposits mutation · secret key returns RentalDepositRefundPayload!	input: RentalDepositRefundInput!	Refund deposits to the original payment method: all of the order’s, or part of one (amount), or all but an amount you keep (keep).
setRentalDepositAutoRefund mutation · secret key returns RentalOrderDepositsPayload!	orderId: ID! enabled: Boolean	Refund this order’s deposits automatically after the return (true / false), or follow the store setting (null).
setRentalProductDepositRule mutation · secret key returns RentalProductDepositRulePayload!	productId: ID! input: RentalDepositRuleInput!	Give a product its own deposit rule.
removeRentalProductDepositRule mutation · secret key returns RentalProductDepositRuleRemovePayload!	productId: ID!	Put a product back on the store default rule.

mutation Refund {
  refundRentalDeposits(input: {orderId: "5550001", depositIds: ["gid://sirentals/Deposit/17"], keep: "50.00", reason: "Scratched frame"}) {
    refund { refundId amount }
    order { status totals { total refunded remaining } deposits { title status remaining } }
    userErrors { code field message }   # bad_keep, nothing_to_refund, no_payment, refund_failed …
  }
}

RentalDepositRefundInput

Field	Type	Notes
orderId	ID!
depositIds	[ID!]	The deposits to refund; none = every deposit of the order.
amount	String	Refund this much of ONE deposit (decimal string, e.g. “150.00”).
keep	String	Or keep this much of ONE deposit and refund the rest.
reason	String	Shown on the refund in Shopify.

RentalDepositRuleInput

Field	Type	Notes
mode	RentalDepositMode!
amount	String	Required unless mode is OFF or per is ORDER; a percentage is at most 100.
per	RentalDepositPer = LINE
title	String	The product’s title, for the list.

Enum	Values
RentalDepositMode	OFF – No deposit. FIXED – A fixed amount. PERCENT – A percentage of the rental’s unit price.
RentalDepositPer	UNIT – Per unit (times the quantity). LINE – Once per cart line. ORDER – Joins the one deposit per order.

Type	Fields
RentalOrderDeposits An order’s deposits.	orderId: ID!, orderName: String, currency: String, deposits: [RentalDeposit!]!, totals: RentalDepositTotals!, status: RentalDepositStatus, statusLabel: String, canRefund: Boolean!, autoRefund: RentalDepositAutoRefund!
RentalDeposit One deposit line of an order.	id: ID!, legacyResourceId: Int!, lineItemId: ID, title: String!, kind: String, quantity: Int, amount: String, tax: String, total: String!, refunded: String!, remaining: String!, currency: String, status: RentalDepositStatus!, statusLabel: String, autoRefund: Boolean!, returnedAt: String, releaseAfter: String, refundedAt: String, autoError: String, log: [RentalDepositLogEntry!]!
RentalDepositLogEntry	at: String, amount: String, kept: String, reason: String, automatic: Boolean!
RentalDepositTotals	total: String!, refunded: String!, remaining: String!
RentalDepositAutoRefund	store: Boolean!, override: Boolean, effective: Boolean!, days: Int!, releaseAfter: String, returned: Boolean!
RentalProductDepositRule A product’s deposit rule.	productId: ID!, title: String, source: String!, rule: RentalDepositRule!
RentalDepositRule	mode: RentalDepositMode!, amount: String!, per: RentalDepositPer!
RentalDepositRefundPayload	refund: RentalDepositRefund, order: RentalOrderDeposits, userErrors: [RentalUserError!]!
RentalDepositRefund	refundId: ID, amount: String!, depositIds: [ID!]!
RentalOrderDepositsPayload	order: RentalOrderDeposits, userErrors: [RentalUserError!]!
RentalProductDepositRulePayload	depositRule: RentalProductDepositRule, warning: String, userErrors: [RentalUserError!]!
RentalProductDepositRuleRemovePayload	removed: Boolean, userErrors: [RentalUserError!]!

Enum	Values
RentalDepositStatus	NOT_REFUNDED PARTIALLY_REFUNDED FULLY_REFUNDED