CreateOrderFee

This API allows landlords to define additional non-rent charges (fees) that guests need to pay as part of a payment plan.

Create Order Fee Create Order Fee

  • API: createOrderFee

  • Purpose & Use Cases: Use this API to configure optional or mandatory non-rental charges that should be collected from guests during the booking or payment process. Examples include:

    • Admin Fee
    • Booking Fee
    • Utility Surcharge
    • One-time Processing Fee

These charges can be added to the payment plan and displayed clearly to guests before confirming their booking.

  • 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 ID of the payment plan to which this fee will be attached
depositOrFeeName NonEmptyString Yes Name of the fee item (e.g., “Admin Fee”)
amountType DepositFeeType Yes Type of the deposit or fee; Possible values: FIXED_AMOUNT PER_BILLING_CYCLE
amount NonEmptyString Yes Amount of the fee. Use string format to avoid float precision errors
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 CreateOrderFee($input: CreateOrderFeeInput) {
  createOrderFee(input: $input) {
    orderFee {
      id
      paymentPlanId
      name
      paymentType
      amount
      price
      currency
      description
      createdAt
      updatedAt
    }
  }
}

GRAPHQL VARIABLES
{
    "input": {
        "depositOrFeeName": "Test fee Open API",
        "amountType": "FIXED_AMOUNT",
        "amount": "30.5",
        "currency": "GBP",
        "paymentPlanId": "eyJ0eXBlIjoiUGF5bWVudFBsYW4iLCJpZCI6MTMzfQ"
    }
}
  • Response:
  {
    "data": {
        "createOrderFee": {
            "orderFee": {
                "id": "eyJ0eXBlIjoiT3JkZXJGZWUiLCJpZCI6MzR9",
                "paymentPlanId": "eyJ0eXBlIjoiUGF5bWVudFBsYW4iLCJpZCI6MTMzfQ==",
                "name": "Test deposit Open API",
                "paymentType": "FIXED_AMOUNT",
                "amount": "30.50",
                "price": null,
                "currency": "GBP",
                "description": null,
                "createdAt": "2025-06-17T08:22:31+00:00",
                "updatedAt": "2025-06-17T08:22:31+00:00"
            }
        }
    }
}
  • Error Message:
Error Message Description
INVALID_LANDLORD Unable to create an order fee because the landlord’s properties do not include any with booking journeys [BOOK, CONNECT]
INPUT_PAY_NOW_TO_SCOM_IS_ERROR Unable to create an order fee because input.payNowToStcom is true
PAYMENT_PLAN_NOT_FOUND Unable to create an order fee because the payment plan data could not be found
INVALID_PAY_NOW_TO_SCOM Unable to create an order fee because input.payNowToStcom is true

UpdateOrderFee

This API allows you to update an existing non-rent fee item associated with a payment plan. You can modify its name, amount, type, currency, or whether it should be paid to Student.com

  • API: updateOrderFee

  • Purpose & Use Cases: Use this API when you need to modify an existing fee — for example:

    • Rename the fee item (e.g., from “Service Fee” to “Processing Fee”)
    • Change the fee amount or amount type (fixed or percentage)
    • Switch the collection behavior (whether http://Student.com collects it or not)

This gives landlords and administrators flexibility in managing fee-related information without having to delete and recreate the fee object.

  • Request:
Attribute Name Data Type Required Details
id ID Yes ID of the payment plan to which this fee will be attached
depositOrFeeName NonEmptyString No Name of the fee item (e.g., “Admin Fee”)
amountType DepositFeeType No Type of the deposit or fee; Possible values: FIXED_AMOUNT PER_BILLING_CYCLE
amount NonEmptyString No Amount of the fee. Use string format to avoid float precision errors
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 UpdateOrderFee($input: UpdateOrderFeeInput) {
  updateOrderFee(input: $input) {
    orderFee {
      id
      paymentPlanId
      name
      paymentType
      amount
      price
      currency
      description
      createdAt
      updatedAt
    }
  }
}

GRAPHQL VARIABLES
{
  "input": {
    "id": "eyJ0eXBlIjoiT3JkZXJEZXBvc2l0IiwiaWQiOjEzMH0=",
    "description": "updated desc"
  }
}
  • Response:
  {
    "data": {
        "updateOrderFee": {
            "orderFee": {
                "id": "eyJ0eXBlIjoiT3JkZXJGZWUiLCJpZCI6MzR9",
                "paymentPlanId": "eyJ0eXBlIjoiUGF5bWVudFBsYW4iLCJpZCI6MTMzfQ==",
                "name": "Test deposit Open API",
                "paymentType": "FIXED_AMOUNT",
                "amount": "30.50",
                "price": null,
                "currency": "GBP",
                "description": "updated desc",
                "createdAt": "2025-06-17T08:22:31+00:00",
                "updatedAt": "2025-06-17T08:40:36+00:00"
            }
        }
    }
}

DeleteOrderFee

This API is used to delete an existing fee item that was previously added to a payment plan.

  • API: deleteOrderFee

  • Purpose & Use Cases: Use this API to remove a non-rental fee (such as admin fee or service charge) from a payment plan when it is no longer applicable or was added by mistake. This helps maintain accurate fee structures in your property’s payment configuration.

  • Request:

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

GRAPHQL VARIABLES
{
    "input": {
        "id": "eyJ0eXBlIjoiT3JkZXJGZWUiLCJpZCI6MzJ9"
    }
}
  • Response:
  {
    "data": {
        "deleteOrderFee": {
            "result": true
        }
    }
}

OrderFee Object

Attribute Name Data Type Details
id ID ID of the payment plan to which this fee will be attached
paymentPlanId ID The ID of the payment plan this order fee is linked to
name String Name of the fee item (e.g., “Admin Fee”)
paymentType DepositFeeType Type of the fee; Possible values: FIXED_AMOUNT PER_BILLING_CYCLE
amount NonEmptyString The value of the fee. Set as a string to avoid floating-point precision issues
price NonEmptyString The price of the fee
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 fee
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)