Manage Orders

This guide shows you how to update order details, cancel orders, modify delivery addresses, and understand order status transitions. After creating an order, you may need to modify its details or cancel it before fulfillment completes.

Prerequisites

Before you start, make sure you have:

Session token: A valid session token. See the Authentication guide to learn how to obtain one.
Order ID: The unique integer orderId returned when you created the order. Use the GET /orders endpoint to find it.
Existing order: You should have created at least one order. See the Create a Fulfillment Order guide if you haven’t created orders yet.

All API examples in this guide use ${BASE_URL} as a placeholder. Replace it with the correct base URL configured for the correct environment. For more information see Environments page.

Update order details

Update details of a processing order using the PATCH /orders/{orderId} endpoint. You can update the order comment, enable or disable tracking, modify the delivery address, and add custom attributes. The following example shows how to update an order’s comment and custom attributes:

Request
Response

Use this request to update order details:

curl -X PATCH "${BASE_URL}/orders/<YOUR_ORDER_ID>" \
  -H "X-Api-Key: <YOUR_STATIC_API_KEY>" \
  -H "Authorization: <YOUR_SESSION_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "comment": "Please handle with care",
    "trackingEnabled": true,
    "customAttributes": {
      "priority": "high",
      "specialInstructions": "gift wrapping"
    }
  }'

A successful request returns a 200 OK status code with an empty response body.

You can update the following fields:

comment: Optional text (max 250 characters) containing fulfillment instructions that the warehouse receives.
trackingEnabled: Boolean value to turn tracking on or off. Additional charges apply when set to true.
address: Delivery address object. See the Modify delivery addresses section for details.
customAttributes: Object for custom key-value pairs that you can use to store additional order metadata.

Modify delivery addresses

Update the delivery address or invoice address of an order using the PUT /orders/{orderId}/address endpoint. You can update the delivery address, invoice address, or both. Use the type query parameter to specify which address to update: DELIVERY, INVOICE, or DELIVERY_AND_INVOICE.

Request
Response

Use this request to update the delivery address:

curl -X PUT "${BASE_URL}/orders/<YOUR_ORDER_ID>/address?type=DELIVERY" \
  -H "X-Api-Key: <YOUR_STATIC_API_KEY>" \
  -H "Authorization: <YOUR_SESSION_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "<RECIPIENT_NAME>",
    "email": "<RECIPIENT_EMAIL>",
    "phone": "<RECIPIENT_PHONE>",
    "street": "<STREET_ADDRESS>",
    "street2": "<ADDRESS_LINE_2>",
    "city": "<CITY>",
    "zip": "<ZIP_CODE>",
    "state": "<STATE>",
    "countryIso2": "<COUNTRY_CODE>"
  }'

A successful request returns a 200 OK status code with an empty response body.

The type query parameter accepts the following values:

DELIVERY: Updates only the delivery address.
INVOICE: Updates only the invoice address.
DELIVERY_AND_INVOICE: Updates both addresses to the same value.

The following table describes the address fields you can include in the request:

Field	Description
`name` or `company`	String. Either the recipient’s name or company name.
`email`	String. Email address of the recipient.
`phone`	String. Phone number.
`street`	String. Street address (Address Line 1). Required unless you provide latitude and longitude coordinates.
`street2`	String. Address Line 2. Optional.
`city`	String. City. Required unless you provide latitude and longitude coordinates.
`zip`	String. ZIP or postal code. Required for most countries unless you provide latitude and longitude coordinates.
`state`	String. State or province. Required for some countries (for example, United States).
`countryIso2`	String. Two-letter ISO (International Organization for Standardization) country code. Required unless you provide latitude and longitude coordinates.
`latitude`	Number. Latitude coordinate for location-based services. For invoice addresses, the system ignores this if provided.
`longitude`	Number. Longitude coordinate for location-based services. For invoice addresses, the system ignores this if provided.

Cancel orders

Request cancellation of an order using the POST /orders/{orderId}/cancelRequest endpoint. Once you cancel an order, fulfillment can’t proceed.

Request
Response

Use this request to cancel an order:

curl -X POST "${BASE_URL}/orders/<YOUR_ORDER_ID>/cancelRequest" \
  -H "X-Api-Key: <YOUR_STATIC_API_KEY>" \
  -H "Authorization: <YOUR_SESSION_TOKEN>"

A successful request returns a 200 OK status code with an empty response body.

Order status transitions

Orders progress through several statuses during the fulfillment lifecycle. Understanding these statuses helps you determine when you can modify or cancel an order. The following table describes each order status:

Status	Description	Can Update?	Can Cancel?
`PENDING`	The order has been received; however, we cannot start processing it due to missing information.	No	Yes
`PROCESSING`	The warehouse is currently picking and packing the items.	Yes	Yes
`COMPLETED`	The warehouse has packed the order and handed it over to the carrier.	No	No
`CANCELLED`	The system cancelled the order before fulfillment.	No	No

Status flow

Orders typically follow this flow:

PENDING: Quivo receives the order, but processing does not begin because required information is missing.
PROCESSING: Warehouse begins picking and packing items. You can still update order details at this stage.
COMPLETED: Warehouse packs the order and hands it over to the carrier. Tracking information becomes available.
CANCELLED: You request cancellation and the system processes it. This can happen from PENDING or PROCESSING status.

Once an order reaches COMPLETED or CANCELLED status, you can’t modify or cancel it. Make sure to update order details or request cancellation before the order reaches these final states.

Where to go next

Now that you can manage orders, continue with these guides:

Track an Order

Monitor order status and retrieve tracking information when Quivo ships orders.

Manage Returns

Generate return labels and track returned items when customers need to send products back.

Introduction

Quickstart

Quivo Flows

Webhooks

Prerequisites

Update order details

Modify delivery addresses

Cancel orders

Order status transitions

Status flow

Where to go next

Track an Order

Manage Returns

​Prerequisites

​Update order details

​Modify delivery addresses

​Cancel orders

​Order status transitions

​Status flow

​Where to go next

Track an Order

Manage Returns

Prerequisites

Update order details

Modify delivery addresses

Cancel orders

Order status transitions

Status flow

Where to go next