> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.quivo.co/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/api-reference/authentication) to learn how to obtain one.
* **Order ID:** The unique integer `orderId` returned when you created the order. Use the [`GET /orders endpoint`](/api-reference/#tag/orders) to find it.
* **Existing order:** You should have created at least one order. See the [Create a Fulfillment Order guide](/docs/quickstart/create-order) if you haven't created orders yet.

<Note>
  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](/api-reference/environments).
</Note>

## Update order details

Update details of a processing order using the [`PATCH /orders/{orderId} endpoint`](/api-reference/#tag/orders). 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:

<Tabs>
  <Tab title="Request">
    Use this request to update order details:

    ```bash theme={null}
    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"
        }
      }'
    ```
  </Tab>

  <Tab title="Response">
    A successful request returns a `200 OK` status code with an empty response body.
  </Tab>
</Tabs>

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](#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`](/api-reference/#tag/orders). 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`.

<Tabs>
  <Tab title="Request">
    Use this request to update the delivery address:

    ```bash theme={null}
    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>"
      }'
    ```
  </Tab>

  <Tab title="Response">
    A successful request returns a `200 OK` status code with an empty response body.
  </Tab>
</Tabs>

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`](/api-reference/#tag/orders). Once you cancel an order, fulfillment can't proceed.

<Tabs>
  <Tab title="Request">
    Use this request to cancel an order:

    ```bash theme={null}
    curl -X POST "${BASE_URL}/orders/<YOUR_ORDER_ID>/cancelRequest" \
      -H "X-Api-Key: <YOUR_STATIC_API_KEY>" \
      -H "Authorization: <YOUR_SESSION_TOKEN>"
    ```
  </Tab>

  <Tab title="Response">
    A successful request returns a `200 OK` status code with an empty response body.
  </Tab>
</Tabs>

## 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.

<Note>
  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.
</Note>

## Where to go next

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

<CardGroup cols={2}>
  <Card icon="location-dot" href="/docs/quickstart/track-order" title="Track an Order">
    Monitor order status and retrieve tracking information when Quivo ships orders.
  </Card>

  <Card icon="rotate-left" href="/docs/quickstart/manage-returns" title="Manage Returns">
    Generate return labels and track returned items when customers need to send products back.
  </Card>
</CardGroup>