---
agentTools:
  projectIndex: https://kosmo.readme.io/llms.txt
---

# Set tips to order

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "contact": {
      "email": "developer@kosmo.delivery",
      "name": "Kosmo API Support"
    },
    "description": "Kosmo API Reference v2",
    "termsOfService": "https://www.kosmo.delivery/",
    "title": "Kosmo API Reference v2",
    "version": "2.0"
  },
  "paths": {
    "/v2/orders/{orderId}/tips": {
      "put": {
        "operationId": "setTipsOrder",
        "parameters": [
          {
            "in": "path",
            "name": "orderId",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SetTipsRequest"
              }
            }
          },
          "description": "Set tips body",
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/kosmoerr.ErrorPayloadDTO"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/kosmoerr.ErrorPayloadDTO"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/kosmoerr.ErrorPayloadDTO"
                }
              }
            }
          }
        },
        "summary": "Set tips to order",
        "tags": [
          "Orders"
        ]
      }
    }
  },
  "servers": [
    {
      "url": "https://api.kosmo.delivery",
      "description": "Kosmo API URL"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "token"
      }
    },
    "schemas": {
      "OptimizationPriority": {
        "description": "The optimization priority of the stop.",
        "type": "string",
        "enum": [
          "",
          "first",
          "last"
        ],
        "default": ""
      },
      "OrderResponse": {
        "required": [
          "order"
        ],
        "properties": {
          "order": {
            "$ref": "#/components/schemas/OrderModel"
          },
          "pickupLocationId": {
            "description": "This represents the pick up location object which will be stored in our system. You can use it in feature to retrieve orders related to this particular location. The pick up locations are defined by a combination of coordinates, phone number and organization.",
            "type": "string",
            "example": "1aa3ce25-fb22-4f49-861e-118a500a26f2"
          }
        },
        "type": "object"
      },
      "CreatedOrderModel": {
        "required": [
          "id"
        ],
        "properties": {
          "id": {
            "description": "This is the Kosmo order id.",
            "type": "string",
            "example": "SG-1234567890"
          },
          "deliveryId": {
            "description": "This represents the delivery id provided by the delivery provider.",
            "type": "string",
            "example": "PANDAGO123456789"
          },
          "status": {
            "$ref": "#/components/schemas/OrderStatus"
          },
          "quoteId": {
            "description": "The quote used to create the order for reference.",
            "type": "string",
            "format": "uuid",
            "example": "1aa3ce25-fb22-4f49-861e-118a500a26f2"
          },
          "pickupStartEta": {
            "description": "Estimated time of pick up provided in RFC3339. This is the earliest time the order can be picked up. Can be empty.",
            "type": "string",
            "format": "RFC3339",
            "example": "2020-01-01T00:00:00.000Z"
          },
          "pickupEta": {
            "description": "Estimated time of pick up provided in RFC3339. This is the latest time the order can be picked up. Can be empty.",
            "type": "string",
            "format": "RFC3339",
            "example": "2020-01-01T00:00:00.000Z"
          },
          "dropoffEta": {
            "description": "The estimated time of arrival for the dropoff.",
            "type": "string",
            "format": "RFC3339",
            "example": "2022-12-30T23:30:00.000Z"
          },
          "autoReassign": {
            "description": "If automatic reassignment was enabled.",
            "type": "boolean"
          },
          "trackingURL": {
            "description": "URL to track the order.",
            "type": "string",
            "example": "https://tracking.kosmo.delivery/tracking/demo/"
          },
          "vehicleType": {
            "$ref": "#/components/schemas/VehicleType"
          },
          "deliveryType": {
            "$ref": "#/components/schemas/DeliveryType"
          },
          "services": {
            "$ref": "#/components/schemas/Services"
          },
          "merchantId": {
            "description": "This represents the merchant which we placed the order for.",
            "type": "string",
            "example": "your-merchant-id"
          }
        }
      },
      "OrderModel": {
        "allOf": [
          {
            "$ref": "#/components/schemas/CreatedOrderModel"
          },
          {
            "required": [
              "pickup",
              "dropoffs",
              "totalAmount",
              "provider"
            ],
            "properties": {
              "driver": {
                "$ref": "#/components/schemas/DriverModel"
              },
              "pickup": {
                "$ref": "#/components/schemas/PickupResponse"
              },
              "dropoffs": {
                "description": "The list of dropoffs.",
                "items": {
                  "$ref": "#/components/schemas/DropoffResponse"
                },
                "type": "array"
              },
              "pricing": {
                "$ref": "#/components/schemas/PricingModel"
              },
              "totalAmount": {
                "$ref": "#/components/schemas/Money"
              },
              "autoReassign": {
                "description": "If automatic reassignment was enabled.",
                "type": "boolean"
              },
              "provider": {
                "description": "Provider delivering the order.",
                "type": "string",
                "example": "PANDAGO"
              }
            }
          }
        ]
      },
      "DriverModel": {
        "required": [
          "fullname",
          "phone"
        ],
        "properties": {
          "id": {
            "description": "The id of the driver.",
            "type": "string",
            "example": "driver_123456"
          },
          "fullname": {
            "description": "The name of the driver if available.",
            "type": "string",
            "example": "John Doe"
          },
          "phone": {
            "description": "The phone number of the driver if available.",
            "type": "string",
            "example": "+6512345678"
          },
          "email": {
            "description": "The email of the driver if available.",
            "type": "string"
          },
          "plateNumber": {
            "description": "The plate number of the vehicle if available.",
            "type": "string",
            "example": "SG123456789"
          },
          "photoURL": {
            "description": "The photo URL of the driver if available.",
            "type": "string",
            "example": "https://example.com/driver.jpg"
          },
          "location": {
            "description": "Current driver's location.",
            "$ref": "#/components/schemas/Coordinates"
          }
        }
      },
      "PricingModel": {
        "description": "The pricing details of the order in cents.",
        "required": [
          "base",
          "currency",
          "total",
          "chargeTotal"
        ],
        "properties": {
          "base": {
            "description": "Base price of the order in cents. This is the price of the order without any discounts or taxes.",
            "type": "integer",
            "example": 1200
          },
          "discount": {
            "description": "The discount applied to the order in cents.",
            "type": "integer",
            "example": 100
          },
          "tax1": {
            "description": "The first tax applied to the order in cents.",
            "type": "integer",
            "example": 130
          },
          "platform_fee": {
            "description": "The platform fee applied to the order in cents. This is the fee that you pay to Kosmo.",
            "type": "integer",
            "example": 50
          },
          "currency": {
            "description": "The currency of the order.",
            "type": "string",
            "example": "SGD"
          },
          "partnerFee": {
            "description": "The partner fee applied to the order in cents. This is the fee that you charge the customer.",
            "type": "integer",
            "example": 50
          },
          "cashOnDeliveryFee": {
            "description": "The COD service fee applied to the order in cents. This is the fee that you charge the customer.",
            "type": "integer",
            "example": 0
          },
          "total": {
            "description": "The total price of the order in cents. This is the price that the customer will pay.",
            "type": "integer",
            "example": 1330
          },
          "chargeTotal": {
            "description": "The total price of the order in cents. This is the price that you will pay.",
            "type": "integer",
            "example": 1280
          },
          "tips": {
            "description": "The tips applied to the order in cents.",
            "type": "integer",
            "example": 0
          }
        }
      },
      "OrderStatus": {
        "description": "This represents the order status. Read more about order statuses under the \"List Deliveries\" section.",
        "enum": [
          "submitted",
          "created",
          "to_pickup",
          "picked_up",
          "delivered",
          "failed",
          "cancelled",
          "returning",
          "returned",
          "at_hub",
          "to_dropoff"
        ],
        "type": "string"
      },
      "DeliveryType": {
        "description": "The delivery type. It's defined by the pick up and delivery time. Read more explanation under the \"Quotes\" section.",
        "enum": [
          "ASAP",
          "2H",
          "4H",
          "NEXT_DAY",
          "NEXT_3_DAYS"
        ],
        "type": "string"
      },
      "Location": {
        "description": "Details of location.",
        "required": [
          "address",
          "country"
        ],
        "properties": {
          "address": {
            "description": "The address including street number.",
            "type": "string",
            "example": "1 Parliament Pl",
            "x-oapi-codegen-extra-tags": {
              "validate": "required"
            }
          },
          "addressDetails": {
            "description": "Details such as unit number, floor, bulding name, etc. This will help the driver to know where to exactly go.",
            "type": "string",
            "example": "03-12"
          },
          "postalCode": {
            "description": "The postal code.",
            "type": "string",
            "example": "178880"
          },
          "country": {
            "description": "Country code of the location (ISO-3166)",
            "type": "string",
            "format": "ISO-3166",
            "example": "SG",
            "x-oapi-codegen-extra-tags": {
              "validate": "required"
            }
          },
          "lat": {
            "description": "Latitude",
            "type": "number",
            "example": 1.3222623,
            "x-go-type": "float64"
          },
          "lng": {
            "description": "Longitude",
            "type": "number",
            "example": 103.8704758,
            "x-go-type": "float64"
          },
          "instructions": {
            "description": "Specify any particular instructions you want the driver to be aware at pick up time.",
            "type": "string",
            "example": "Please call me when you arrive"
          }
        }
      },
      "Contact": {
        "description": "Details of contact (can be a store or a person).",
        "required": [
          "fullname",
          "phone"
        ],
        "properties": {
          "fullname": {
            "description": "Full name of the contact.",
            "type": "string",
            "example": "John Doe",
            "x-oapi-codegen-extra-tags": {
              "validate": "required"
            }
          },
          "phone": {
            "description": "The phone number of the contact.",
            "type": "string",
            "example": "+1234567890",
            "x-oapi-codegen-extra-tags": {
              "validate": "required,phone"
            }
          },
          "email": {
            "description": "The email of the contact.",
            "type": "string",
            "example": "contact-email@gmail.com",
            "x-oapi-codegen-extra-tags": {
              "validate": "omitempty,email"
            }
          }
        }
      },
      "PickupResponse": {
        "description": "The pick up point of origin for the delivery order.",
        "required": [
          "location",
          "sender"
        ],
        "properties": {
          "location_reference_id": {
            "description": "It's your reference id for the location. It can be used to identify the location in your system.",
            "type": "string",
            "example": "1aa3ce25-fb22-4f49-861e-118a500a26f2"
          },
          "name": {
            "description": "The name of the location. It's required if you provide a location_reference_id.",
            "type": "string",
            "example": "Bedok Flowers"
          },
          "location": {
            "$ref": "#/components/schemas/Location"
          },
          "sender": {
            "$ref": "#/components/schemas/Contact"
          },
          "proofs": {
            "description": "The list of proofs of pickup. Lasts for 7 days.",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "noteFromDriver": {
            "description": "The note from the driver if any.",
            "type": "string"
          }
        }
      },
      "DropoffResponse": {
        "description": "Details of dropoff.",
        "required": [
          "location",
          "receiver"
        ],
        "properties": {
          "location": {
            "$ref": "#/components/schemas/Location"
          },
          "receiver": {
            "$ref": "#/components/schemas/Contact"
          },
          "parcels": {
            "description": "The list of parcels.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Parcel"
            }
          },
          "orderReferenceId": {
            "description": "You can provide this field to identify this dropoff with a specific ID in your system. So you will be able to track your system order in a case if you want to create multi dropoff order.",
            "type": "string",
            "example": "1aa3ce25-fb22-4f49-861e-118a500a26f2"
          },
          "proofOfDeliveryURL": {
            "description": "Deprecated - use proofs instead. The URL of the proof of delivery image.",
            "type": "string",
            "example": "https://example.com/pod.jpg"
          },
          "proofs": {
            "description": "The list of proofs of dropoff. Lasts for 7 days.",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "trackingURL": {
            "description": "Tracking URL with complete information such as payment and all recipients.",
            "type": "string",
            "example": "https://tracking.kosmo.delivery/tracking/demo/"
          },
          "cashOnDeliveryAmount": {
            "description": "The amount of cash on delivery in cents. It's required to be greater than 0 if you want to collect cash on delivery.",
            "type": "integer",
            "example": {
              "amount": 6000
            }
          },
          "deliveryFee": {
            "description": "The client base delivery fee in cents.",
            "type": "integer",
            "example": 1000,
            "x-go-type": "int64"
          },
          "tips": {
            "description": "The client tips in cents.",
            "type": "integer",
            "example": 0,
            "x-go-type": "int64"
          },
          "clientId": {
            "description": "The client ID. You can manage your clients in the Kosmo dashboard.",
            "type": "string",
            "example": "client_123456"
          },
          "failureReason": {
            "$ref": "#/components/schemas/DropoffFailureReason"
          },
          "failureReasonNote": {
            "description": "The note of the failure reason if any.",
            "type": "string"
          },
          "status": {
            "$ref": "#/components/schemas/DropoffStatus"
          },
          "noteFromDriver": {
            "description": "The note from the driver if any.",
            "type": "string"
          },
          "tags": {
            "description": "Tags for the order.",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "priority": {
            "description": "The priority of the dropoff.",
            "$ref": "#/components/schemas/OptimizationPriority"
          },
          "timeAtLocation": {
            "description": "The time in seconds the driver will spend at the location.",
            "type": "integer",
            "example": 600
          },
          "arrivalTimeStart": {
            "description": "Expected arrival time to receive order.",
            "type": "string",
            "format": "date-time",
            "example": "2020-01-01T00:00:00.000Z"
          },
          "arrivalTimeEnd": {
            "description": "Expected dropoff time to receive order.",
            "type": "string",
            "format": "date-time",
            "example": "2020-01-01T00:00:00.000Z"
          }
        }
      },
      "Parcel": {
        "description": "Details of parcel.",
        "properties": {
          "description": {
            "description": "Description of the parcel.",
            "type": "string",
            "example": "1x iPhone 12 Pro Max"
          },
          "weight": {
            "description": "Weight of the parcel in kilograms.",
            "type": "number",
            "example": 0.1
          },
          "height": {
            "description": "Height of the parcel in centimeters.",
            "type": "integer",
            "example": 10
          },
          "width": {
            "description": "Width of the parcel in centimeters.",
            "type": "integer",
            "example": 10
          },
          "quantity": {
            "description": "Number of parcels.",
            "type": "integer",
            "example": 5
          },
          "length": {
            "description": "Length of the parcel in centimeters.",
            "type": "integer",
            "example": 10
          },
          "value": {
            "description": "Value of the parcel in cents",
            "example": {
              "amount": 75000,
              "currency": "SGD"
            },
            "$ref": "#/components/schemas/Money"
          },
          "reference": {
            "description": "Internal reference for parcel if any.",
            "type": "string",
            "example": "1234567890"
          },
          "handlingInstructions": {
            "$ref": "#/components/schemas/HandlingInstructions"
          },
          "waybillURL": {
            "description": "URL link to the waybills for printing. Each unique parcel will require one unique waybill label.",
            "type": "string",
            "example": "https://share.kosmo.delivery/waybill_staging/213d102c-3457-43e8-859e-a2933c0c9946.pdf"
          }
        }
      },
      "VehicleType": {
        "description": "The vehicle type. You can refer to the table provided under \"Quotes\" section to determine which vehicle type to choose.",
        "enum": [
          "motorcycle",
          "car",
          "van",
          "lorry"
        ],
        "type": "string"
      },
      "Money": {
        "description": "Details of money.",
        "properties": {
          "amount": {
            "description": "Amount of money in cents.",
            "type": "integer",
            "example": 1000
          },
          "currency": {
            "description": "Currency of the amount.",
            "type": "string",
            "example": "SGD"
          }
        },
        "required": [
          "amount",
          "currency"
        ],
        "example": {
          "amount": 1480,
          "currency": "SGD"
        }
      },
      "SetTipsRequest": {
        "description": "Set tips to a delivery.",
        "properties": {
          "amount": {
            "description": "Amount of tips in cents.",
            "type": "integer"
          }
        },
        "type": "object"
      },
      "Coordinates": {
        "type": "object",
        "required": [
          "lat",
          "lng"
        ],
        "properties": {
          "lat": {
            "description": "Latitude.",
            "type": "number",
            "example": 1.234567,
            "x-go-type": "float64"
          },
          "lng": {
            "description": "Longitude.",
            "type": "number",
            "example": 103.234567,
            "x-go-type": "float64"
          }
        }
      },
      "HandlingInstructions": {
        "description": "Specify any particular instructions you want the driver to be aware of when handling the parcel.",
        "type": "object",
        "properties": {
          "containsFluids": {
            "description": "Specify if the parcel contains any fluids.",
            "type": "boolean",
            "example": false
          },
          "fragile": {
            "description": "Specify if the parcel is fragile.",
            "type": "boolean",
            "example": false
          },
          "doNotRotate": {
            "description": "Specify if the parcel should not be rotated.",
            "type": "boolean",
            "example": false
          },
          "containsHotFood": {
            "description": "Specify if the parcel contains hot food.",
            "type": "boolean",
            "example": false
          }
        }
      },
      "Services": {
        "description": "What services 3PL providers will have for your order.",
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/Service"
        },
        "example": [
          {
            "name": "proofDelivery"
          },
          {
            "name": "insurance"
          },
          {
            "name": "door2door"
          },
          {
            "name": "cashOnDelivery"
          }
        ]
      },
      "Service": {
        "type": "object",
        "required": [
          "id"
        ],
        "properties": {
          "id": {
            "description": "The name of the service.",
            "type": "string",
            "enum": [
              "proofDelivery",
              "insurance",
              "door2door",
              "cashOnDelivery"
            ],
            "example": "proofDelivery"
          }
        }
      },
      "kosmoerr.ErrorPayloadDTO": {
        "properties": {
          "details": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/kosmoerr.ErrorDetailDTO"
            }
          },
          "key": {
            "description": "Error key.",
            "type": "string",
            "example": "invalid_request_error"
          },
          "message": {
            "description": "Error message.",
            "type": "string"
          }
        },
        "type": "object"
      },
      "kosmoerr.ErrorDetailDTO": {
        "properties": {
          "key": {
            "description": "Error key.",
            "type": "string",
            "example": "invalid_phone_number"
          },
          "message": {
            "description": "Error message.",
            "type": "string",
            "example": "invalid phone number: Phone"
          },
          "field": {
            "description": "Error field.",
            "type": "string",
            "example": "CreateQuotesRequest.Dropoffs[0].Receiver.Phone"
          }
        },
        "type": "object"
      },
      "DropoffStatus": {
        "type": "string",
        "description": "The status of the dropoff.",
        "enum": [
          "delivered",
          "canceled",
          "to_dropoff",
          "returning",
          "returned"
        ],
        "example": "delivered"
      },
      "DropoffFailureReason": {
        "type": "string",
        "description": "Failure reason if any.",
        "enum": [
          "incorrect_missing_item",
          "deliver_another_time",
          "destination_unreachable",
          "recipient_unavailable",
          "unable_to_find_customer",
          "other"
        ]
      }
    }
  },
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true,
    "samples-enabled": true
  },
  "_id": {
    "buffer": {
      "0": 99,
      "1": 136,
      "2": 86,
      "3": 191,
      "4": 139,
      "5": 245,
      "6": 189,
      "7": 0,
      "8": 16,
      "9": 17,
      "10": 176,
      "11": 113
    }
  }
}
```