CreateOrderDeposit

Create Deposit

  • API: createOrderDeposit

  • Purpose & Use Cases: This API is used to define and collect non-rent-related charges (such as deposits or additional service fees) associated with a payment plan. It allows landlords or administrators to configure custom fee items that tenants need to pay upfront.

  • Validation Rule: The currency of the deposit must match the currency defined in the associated payment plan.

  • Request:

Attribute Name Data Type Required Details
paymentPlanId ID Yes The ID of the payment plan this deposit is linked to
depositOrFeeName NonEmptyString Yes A custom name for the deposit or fee (e.g., “Security Deposit”)
amountType DepositFeeType Yes Type of the deposit or fee; Possible values: FIXED_AMOUNT PER_BILLING_CYCLE
amount NonEmptyString Yes The value of the deposit. Set as a string to avoid floating-point precision issues
currency CurrencyUnit Yes The currency code (e.g., USD, GBP). Must match the currency of the payment plan
description String No Optional description or explanation for the deposit 
  QUERY
mutation createOrderDeposit($input: CreateOrderDepositInput) {
    createOrderDeposit(input: $input) {
        orderDeposit {
          amount
          currency
          description
          id
          name
          paymentPlanId
          paymentType
        }
    }
}


GRAPHQL VARIABLES
{
    "input": {
        "depositOrFeeName": "Test deposit Open API",
        "amountType": "FIXED_AMOUNT",
        "amount": "30.5",
        "currency": "GBP",
        "paymentPlanId": "eyJ0eXBlIjoiUGF5bWVudFBsYW4iLCJpZCI6MTMzfQ"
    }
}
  • Response:
  {
    "data": {
        "createOrderDeposit": {
            "orderDeposit": {
                "amount": "30.50",
                "currency": "GBP",
                "description": null,
                "id": "eyJ0eXBlIjoiT3JkZXJEZXBvc2l0IiwiaWQiOjEzMH0=",
                "name": "Test deposit Open API",
                "paymentPlanId": "eyJ0eXBlIjoiUGF5bWVudFBsYW4iLCJpZCI6MTMzfQ==",
                "paymentType": "FIXED_AMOUNT",
            }
        }
    }
}
  • Error Message:
Error Message Description
permission rule cannot execute with invalid id Unable to create an order deposit because the input.paymentPlanId does not exist
INVALID_LANDLORD Unable to create an order deposit because the landlord’s properties do not include any with booking journeys [BOOK, CONNECT]
PAYMENT_PLAN_NOT_FOUND Unable to create an order deposit because the payment plan data could not be found
INVALID_LANDLORD_PAYMENT_PLAN Unable to proceed because paymentPlan.landlordId does not match the token.landlord
INPUT_PAY_NOW_TO_SCOM_IS_ERROR Unable to create an order deposit because input.payNowToStcom is false
INVALID_CURRENCY Unable to create an order deposit because the paymentPlan.currency does not match the specified currency
PaymentPlan.paymentOnline is No, deposit payNowToStcom must be No Unable to create an order deposit because paymentPlan.paymentOnline is false and payNowToStcom is true

UpdateOrderDeposit

  • API: updateOrderDeposit

  • Purpose & Use Cases: This API is used to update an existing deposit or fee item that was previously added to a payment plan. You can modify fields such as name, amount, currency, or payment behavior.

  • Request:

Attribute Name Data Type Required Details
id ID Yes The unique ID of the deposit to be updated
depositOrFeeName NonEmptyString No A custom name for the deposit or fee (e.g., “Security Deposit”)
amountType DepositFeeType No Type of the deposit or fee; Possible values: FIXED_AMOUNT PER_BILLING_CYCLE
amount NonEmptyString No The value of the deposit. Set as a string to avoid floating-point precision issues
currency CurrencyUnit No The currency code (e.g., USD, GBP). Must match the currency of the payment plan
description String No Optional description or explanation for the deposit 
  QUERY
mutation UpdateOrderDeposit($input: UpdateOrderDepositInput) {
  updateOrderDeposit(input: $input) {
        orderDeposit {
            id
            paymentPlanId
            name
            paymentType
            amount
            price
            currency
            description
            createdAt
            updatedAt
        }
    }
}

GRAPHQL VARIABLES
{
  "input": {
    "id": "eyJ0eXBlIjoiT3JkZXJEZXBvc2l0IiwiaWQiOjEzMH0=",
    "description": "updated desc"
  }
}
  • Response:
  {
    "data": {
        "updateOrderDeposit": {
            "orderDeposit": {
                "id": "eyJ0eXBlIjoiT3JkZXJEZXBvc2l0IiwiaWQiOjEzMH0=",
                "paymentPlanId": "eyJ0eXBlIjoiUGF5bWVudFBsYW4iLCJpZCI6MTMzfQ==",
                "name": "Test deposit Open API",
                "paymentType": "FIXED_AMOUNT",
                "amount": "30.50",
                "price": null,
                "currency": "GBP",
                "description": "updated desc",
                "createdAt": "2025-06-16T10:29:10+00:00",
                "updatedAt": "2025-06-16T10:34:07+00:00"
            }
        }
    }
}
  • Error Message:
Error Message Description
INVALID_LANDLORD Unable to update an order deposit because the landlord’s properties do not include any with booking journeys [BOOK, CONNECT]
PAYMENT_PLAN_NOT_FOUND Unable to update an order deposit because the payment plan data could not be found
INVALID_LANDLORD_PAYMENT_PLAN Unable to proceed because paymentPlan.landlordId does not match the token.landlord
ORDER_DEPOSIT_NOT_FOUND Unable to update the order deposit because the deposit could not be retrieved
INVALID_CURRENCY Unable to update an order deposit because the paymentPlan.currency does not match the specified currency
PaymentPlan.paymentOnline is No, deposit payNowToStcom must be No Unable to create an order deposit because paymentPlan.paymentOnline is false and payNowToStcom is true
INVALID_PAY_NOW_TO_SCOM Unable to update an order deposit because input.payNowToStcom is false

DeleteOrderDeposit

  • API: deleteOrderDeposit

  • Purpose & Use Cases: This API is used to delete a specific deposit or fee item that was previously created and linked to a payment plan. Use this API when you need to remove a deposit or fee from a payment plan — for example, if it was created by mistake or is no longer required for the booking or lease.

  • Validation Rule: If the category of the associated payment plan is set to deposit_is_required, you cannot delete the last remaining deposit.

  • Request:

Attribute Name Data Type Required Details
id ID Yes The unique ID of the deposit to be deleted. This ID is returned when the deposit is created 
  QUERY
mutation DeleteOrderDeposit($input: DeleteOrderDepositInput) {
  deleteOrderDeposit(input: $input) {
    result
  }
}

GRAPHQL VARIABLES
{
    "input": {
        "id": "eyJ0eXBlIjoiT3JkZXJEZXBvc2l0IiwiaWQiOjEyOX0"
    }
}
  • Response:
  {
    "data": {
        "deleteOrderDeposit": {
            "result": true
        }
    }
}
  • Error Message:
Error Message Description
INVALID_LANDLORD Unable to delete an order deposit because the landlord’s properties do not include any with booking journeys [BOOK, CONNECT]
ORDER_DEPOSIT_NOT_FOUND Unable to delete the order deposit because the deposit could not be retrieved
DEPOSIT_IS_REQUIRED
PaymentPlan cannot delete the last deposit		 Unable to delete the deposit because the paymentPlan.paymentPlan is DEPOSIT_IS_REQUIRED and only one deposit exists

Deposit object

Attribute Name Data Type Details
id ID The unique ID of the deposit
paymentPlanId ID The ID of the payment plan this deposit is linked to
name String A custom name for the deposit or fee (e.g., “Security Deposit”)
paymentType DepositFeeType Type of the deposit or fee; Possible values: FIXED_AMOUNT PER_BILLING_CYCLE
amount NonEmptyString The value of the deposit. Set as a string to avoid floating-point precision issues
price NonEmptyString The price of the deposit
currency CurrencyUnit The currency code (e.g., USD, GBP). Must match the currency of the payment plan
description String Optional description or explanation for the deposit
createdAt Datetime The created time of the deposit in format (YYYY-MM-DDTHH:mm:ssZ)
updatedAt Datetime The updated time of the deposit in format (YYYY-MM-DDTHH:mm:ssZ)