# API Overview Source: https://api-docs.quivo.co/api-reference/api-overview This reference provides an overview of the API structure and navigation. Welcome to the Quivo API Developer Portal. The REST (Representational State Transfer) API provides seamless integration with the logistics and fulfillment platform. This documentation is structured to support your integration journey, from initial setup to detailed implementation. For step-by-step guides, see our [Tutorial](/docs/introduction/first-api-call) and [How-To](/docs/quickstart/send-inventory) sections. ## Your Path to Integration Follow these steps for a smooth integration experience: 1. **Start with Authentication** to understand how to authenticate your requests. This is the essential first step before making any API calls. 2. **Follow the Quickstart Guides** to learn the main workflows for managing inventory, orders, and shipments. 3. **Explore the API Reference** to find the specific endpoints you need for your app. **Start here if you are new.** This section covers the essential first steps for a successful integration, including the authentication process and how to obtain session tokens. **Go into the technical details.** Explore all available endpoints, detailing required parameters, request and response examples, and error codes. Use this when you are ready to build. ## Quickstart Guides The following guides walk you through the main workflows for integrating with Quivo: Notify the Quivo warehouse that you are sending a shipment of products. Learn how to create inbound records and manage inventory shipments. Programmatically submit fulfillment orders to the Quivo Connector. Trigger the pick and pack process for your products. Retrieve current status and tracking information for orders. Monitor shipment progress and delivery status. Generate return labels and track returned items. Learn how to process customer returns through the API. Configure event subscriptions for real-time notifications. Set up webhooks to receive updates about order status changes and other events. ## Authentication All API requests require authentication using: 1. **Static API Key:** Obtained through the Quivo Dashboard. Include it in the `X-Api-Key` header. 2. **Session Token:** Obtained through the `POST /login` endpoint, valid for one hour. Include it in the `Authorization` header. See the [Authentication guide](/api-reference/authentication) for detailed instructions on obtaining and using session tokens. # Authentication Source: https://api-docs.quivo.co/api-reference/authentication This reference provides precise specifications for authenticating API requests. All requests to the Quivo API require authentication using a session token. This ensures that only authorized users can access your account data and perform operations on your behalf. For step-by-step instructions, see the [Make your first API call](/docs/introduction/first-api-call) tutorial. The authentication process consists of the following steps: 1. **Obtaining a session token:** Exchange your API credentials—API key, username, and password—for a temporary session token via the `POST /login` endpoint. 2. **Using the token:** Include the session token in the `Authorization` header of all subsequent API requests. Session tokens expire after one hour. When they expire, refresh them. See the Token expiration section below for handling token refresh automatically. ## Prerequisites Before you start, make sure you have the following: * **Static API Key:** Your static API key provided by Quivo. You can retrieve it from the Quivo Dashboard * **Username:** Your Quivo account username * **Password:** Your Quivo account password All API examples in this reference 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). ## Obtain a session token Exchange your credentials for a session token via the `POST /login` endpoint. Replace the placeholders with your actual data. Use this request to exchange your credentials for a session token: ```bash theme={null} curl -X POST "${BASE_URL}/login" \ -H "Content-Type: application/json" \ -H "X-Api-Key: " \ -d '{ "username": "", "password": "" }' ``` A successful request returns a `200 OK` status code. The API returns a token string in the response: ```json theme={null} { "Token": "" } ``` ## Use the token in requests Include the token in the `Authorization` header of all API requests. You must also include your API key in the `X-Api-Key` header. The following example shows how to make an authenticated request using the [`GET /orders endpoint`](/api-reference/#tag/orders). Replace the placeholders with your actual data. Use this request example to make an authenticated API call with your session token: ```bash theme={null} curl -X GET "${BASE_URL}/orders" \ -H "X-Api-Key: " \ -H "Authorization: " ``` A successful authenticated request returns the requested data. If authentication fails, you'll receive a `401 Unauthorized` error. ```json theme={null} { "orderId": , "orderStatus": "" } ``` ## Token expiration Session tokens expire after 1 hour. When a token expires, you receive a `401 Unauthorized` error response. ### Handling token expiration When you receive a 401 error, your integration should automatically: 1. **Retry authentication:** Call the `POST /login` endpoint again to obtain a new token 2. **Retry the original request:** Use the new token to retry the request that failed Implement automatic token refresh in your integration to handle expiration seamlessly. Monitor API responses for `401 Unauthorized` errors and trigger re-authentication as needed. ## Where to go next Now that you understand authentication, continue with these guides: Start the fulfillment process by creating orders for your customers. Send your products to Quivo warehouses to make them available for fulfillment. # Environments Source: https://api-docs.quivo.co/api-reference/environments This reference provides information about the available Quivo API environments, their base URLs, and when to use each environment. ## Overview The Quivo API is available in two environments: * **Production:** The live environment for handling real business operations * **Sandbox:** The testing environment for development and integration testing All API endpoints are available in both environments. The only difference is the base URL you use to make requests. ## Production Environment Use the production environment when you are ready to process real orders, need to access live inventory data, are handling actual customer fulfillment requests, and have completed testing in the sandbox environment. **Base URL:** `https://api.quivo.co` The production environment processes real orders and charges. Only use this environment when you are ready to handle live operations. ## Sandbox Environment Use the sandbox environment for development, integration testing, learning the Quivo API, validating features without affecting real data, and testing error handling and edge cases before deploying to production. **Base URL:** `https://api-sandbox.quivo.co` **Web App Sandbox:** [https://app-sandbox.quivo.co/](https://app-sandbox.quivo.co/) **API Key Requirement:** To access the Sandbox API, you still need an API Key provided by Quivo. The preceding credentials allow access to the Sandbox Web App, but the API requires an additional API Key in the `X-Api-Key` header. ## Using the Base URL In all API documentation examples, you'll see `${BASE_URL}` used as a placeholder. Replace this placeholder with the appropriate base URL of your environment: * **Production:** Replace `${BASE_URL}` with `https://api.quivo.co` * **Sandbox:** Replace `${BASE_URL}` with `https://api-sandbox.quivo.co` ### Example Here's an example of how to use the base URL in an API request: ```bash theme={null} curl -X GET "https://api.quivo.co/sellers" -H "X-Api-Key: " -H "Authorization: " ``` For sandbox: ```bash theme={null} curl -X GET "https://api-sandbox.quivo.co/sellers" -H "X-Api-Key: " -H "Authorization: " ``` ## Authentication Both environments require the same authentication method: 1. **API Key:** Include your API Key in the `X-Api-Key` header 2. **Session Token:** Obtain a session token via `POST /login` and include it in the `Authorization` header See the [Authentication reference](/api-reference/authentication) for detailed authentication instructions. To obtain API Keys for the environments you need to access, you can request them through The Connector web app (UI) or via the API. ## Where to go next Now that you understand the available environments, continue with these guides: Learn how to authenticate API requests with API keys and session tokens. Step-by-step tutorial for making your first API request to the Quivo API. # HTTP Response Codes Source: https://api-docs.quivo.co/api-reference/http-response-codes This reference documents HTTP response status codes used by the Quivo API and explains when each code is returned ## Overview The Quivo API uses standard HTTP status codes to indicate the result of API requests. All responses follow REST conventions, where status codes communicate the success or failure of operations. For detailed endpoint-specific response information, see the [API Reference endpoints](/api-reference/#tag) documentation. ## Success Codes (2xx) These codes indicate that a request was successfully received, understood, and processed. ### 200 OK The request succeeded. The response body contains the requested data or the result of the operation. **When returned:** * Successful GET requests that retrieve data * Successful PUT or PATCH requests that update resources * Successful POST requests that return the created or updated resource ### 204 No Content The request succeeded, but there is no content to return in the response body. **When returned:** * Some endpoints return `204 No Content` for successful operations that don't require a response body * DELETE operations that successfully remove a resource * Some PUT or PATCH operations that update resources without returning the updated resource ## Client Error Codes (4xx) These codes indicate that the client made an error in the request. ### 400 Bad Request The request was invalid or malformed. **When returned:** * Invalid request body or parameters * Validation errors (for example, required fields missing or invalid values) * Bad request body or parameters from AWS API Gateway **Example response:** ``` positions: must not be null ``` ### 401 Unauthorized Authentication failed or the request lacks valid authentication credentials. **When returned:** * Session tokens expire (after 1 hour) * Authentication fails or the request lacks valid authentication credentials * The incoming token has expired **Example response:** ```json theme={null} { "message": "The incoming token has expired" } ``` When you receive a `401 Unauthorized` error due to an expired token, obtain a new session token by calling the `POST /login` endpoint and retry your request. See the [Authentication reference](/api-reference/authentication) for detailed instructions. ### 403 Forbidden The request was valid, but the server is refusing to fulfill it due to insufficient permissions or other access restrictions. **When returned:** * Access denied * Expired token * Invalid API key * Invalid signature * Missing authentication token * WAF (Web Application Firewall) filtered request **Example responses:** ```json theme={null} { "message": "Forbidden" } ``` ```json theme={null} { "Message": "Access Denied" } ``` ### 404 Not Found The requested resource was not found. **When returned:** * The specified resource ID doesn't exist * The endpoint path is incorrect * Resource not found from AWS API Gateway **Example response:** ``` Order with ID 12311231 not found ``` ### 405 Method Not Allowed The HTTP method used is not allowed for the requested endpoint. **When returned:** * Using an unsupported HTTP method (for example, using PUT on an endpoint that only supports GET) **Example response:** ``` Method Not Allowed ``` ### 413 Request Entity Too Large The request body is too large. **When returned:** * Request too large from AWS API Gateway ### 415 Unsupported Media Type The request's Content-Type is not supported. **When returned:** * Unsupported media type from AWS API Gateway ### 429 Too Many Requests The client has exceeded the rate limit or quota. **When returned:** * Quota exceeded * Request throttled by AWS API Gateway ## Server Error Codes (5xx) These codes indicate that the server encountered an error while processing the request. ### 500 Internal Server Error The server encountered an unexpected error. **When returned:** * Unexpected server errors * API configuration error from AWS API Gateway * Authorizer configuration error from AWS API Gateway * Authorizer failure from AWS API Gateway ### 501 Not Implemented The requested functionality is not implemented. **When returned:** * The endpoint or feature is not yet available ### 504 Gateway Timeout The server, acting as a gateway, did not receive a timely response from an upstream server. **When returned:** * Integration failure from AWS API Gateway * Integration timeout from AWS API Gateway ## Error Response Format The Quivo API uses different error response formats depending on where the error occurs: ### Backend Errors Errors returned by the Quivo API backend are typically simple strings: ``` Order with ID 12311231 not found ``` ``` positions: must not be null ``` ### API Gateway Errors Errors returned by AWS API Gateway are formatted as JSON with a `message` (or `Message`) field: ```json theme={null} { "message": "The incoming token has expired" } ``` ```json theme={null} { "Message": "Access Denied" } ``` ## Additional Response Codes The Quivo API uses standard HTTP status codes. The codes documented above are the primary ones you'll encounter. AWS API Gateway may also return other standard HTTP status codes in specific scenarios. ## Where to go next Now that you understand HTTP response codes, continue with these guides: Learn about authentication and how to handle 401 Unauthorized errors. Understand production and sandbox environments for testing error scenarios. # Pagination & Idempotency Source: https://api-docs.quivo.co/api-reference/pagination-idempotency This reference explains how the Quivo API handles pagination and idempotency for API requests. ## Overview The Quivo API provides mechanisms for handling large result sets through pagination and for ensuring safe retries through idempotency. Understanding these features enables you to build reliable integrations that handle data efficiently and prevent duplicate operations. For detailed endpoint-specific information about pagination parameters and idempotency support, see the [API Reference endpoints](/api-reference/#tag) documentation. ## Pagination Pagination allows you to retrieve large datasets in manageable chunks. The Quivo API supports two pagination mechanisms: offset-based pagination and cursor-based pagination. ### Pagination Parameters The following query parameters control pagination for endpoints that support it: | Parameter | Type | Description | | ------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `page` | integer | The page number to retrieve when using offset-based pagination. Ignored if `searchAfter` is provided. | | `searchAfter` | string or array | Used for cursor-based pagination. Pass the `sort` key value from the last item of the previous page to retrieve the next set of results. When `sort` has multiple fields, use a JSON array with values for each field. Overrides `page`. | | `pageSize` | integer | The maximum number of items to return per page. Used for both offset and cursor-based pagination. Default is `25`. The maximum allowed value is `1000`. | | `sort` | string | Optional sorting criteria for the results. Format is typically `field:direction` (for example, `created:desc`). | The default `pageSize` is `25` when not specified. Do not use very large page sizes (for example, `10000`). Use `page` and `pageSize` pagination, and keep `pageSize` at or below the maximum allowed value of `1000`. ### Offset-Based Pagination Offset-based pagination uses page numbers to navigate through results. Use the `page` parameter to specify which page to retrieve. **Example:** ```bash theme={null} curl -X GET "${BASE_URL}/articles?page=1&pageSize=20" \ -H "X-Api-Key: " \ -H "Authorization: " ``` ### Cursor-Based Pagination Cursor-based pagination uses a cursor value from the last item of the previous page to retrieve the next set of results. This method is more efficient for large datasets and prevents issues with data changing between page requests. To use cursor-based pagination: 1. Include a `sort` parameter in your initial request to ensure consistent ordering 2. Use the `searchAfter` parameter with the `sort` key value from the last item of the previous page 3. The `page` parameter is ignored when `searchAfter` is provided When `sort` has multiple fields, pass `searchAfter` as a JSON array with values corresponding to each sort field. For example, if sorting by ID and date, use `["123", "2023-10-01T12:00:00Z"]`. **Example:** ```bash theme={null} # First page curl -X GET "${BASE_URL}/articles?sort=created:desc&pageSize=20" \ -H "X-Api-Key: " \ -H "Authorization: " # Next page (using searchAfter from last item of previous response) curl -X GET "${BASE_URL}/articles?sort=created:desc&pageSize=20&searchAfter=" \ -H "X-Api-Key: " \ -H "Authorization: " ``` Cursor-based pagination (`searchAfter`) overrides offset-based pagination (`page`). If you provide both parameters, only `searchAfter` is used. ### Response Structure Paginated responses are returned as arrays. The API doesn't include pagination metadata in the response body. **Response format:** * Responses are arrays of items (for example, `ArticleGetSummary[]`, `OrderSummary[]`) * No pagination metadata fields like `total`, `has_more`, `next_cursor`, or `page` are included * The response body is directly the array of items **Example response structure:** ```json theme={null} [ { "": "", "": "", "": "" } ] ``` The actual fields and structure depend on the endpoint and resource type. See the [OpenAPI specification](https://s3-eu-west-1.amazonaws.com/quivo-connector-prod-api-docs/swagger.json) for the exact schema of each endpoint's response. **Determining if more pages are available:** Since pagination metadata isn't included in responses, you may need to: * Check if the response contains fewer items than the requested `pageSize` * Make a request for the next page and check if it returns any results ### Finding Pagination Support Not all endpoints support pagination. To determine if an endpoint supports pagination, see the detailed endpoint documentation in the [API Reference](/api-reference/#tag) section ## Idempotency Idempotency ensures that making the same request multiple times produces the same result as making it once. This is important for handling network errors, retries, and preventing duplicate operations. ### Idempotency Support Currently, only one endpoint supports idempotency: * **`POST /shipments/book`** - Books a shipment ### How Idempotency Works The `/shipments/book` endpoint uses a `requestId` parameter to ensure idempotency: * Include a unique `requestId` in your request * If you make the same request with the same `requestId` multiple times, the endpoint will not create a duplicate shipment * Instead, it returns the existing shipment that was created with that `requestId` **Example:** ```bash theme={null} curl -X POST "${BASE_URL}/shipments/book" \ -H "X-Api-Key: " \ -H "Authorization: " \ -H "Content-Type: application/json" \ -d '{ "requestId": "unique-request-id-12345", "shipmentData": { ... } }' ``` If you make the same request with the same `requestId` again, you'll receive the existing shipment instead of creating a new one. This prevents duplicate shipments from being created due to network retries or other issues. ### Other Endpoints For other endpoints, idempotency is not currently supported. To determine if an endpoint supports idempotency, see the detailed endpoint documentation in the [API Reference](/api-reference/#tag) section. ## Where to go next Now that you understand pagination and idempotency concepts, continue with these guides: Understand API response codes, including errors that may occur during pagination. Learn about authentication required for API requests. # Create address Source: https://api-docs.quivo.co/connector-api-reference/addresses/create-address /openapi.json post /addresses/{sellerId} Create a new address for the specified seller. # Delete address Source: https://api-docs.quivo.co/connector-api-reference/addresses/delete-address /openapi.json delete /addresses/{sellerId}/{addressId} Delete an existing address for the specified seller. # Get address Source: https://api-docs.quivo.co/connector-api-reference/addresses/get-address /openapi.json get /addresses/{sellerId}/default/{defaultAddressType} Get seller's current default address for the given address type. # List addresses Source: https://api-docs.quivo.co/connector-api-reference/addresses/list-addresses /openapi.json get /addresses/{sellerId} List all saved addresses for the specified seller. # Remove default address Source: https://api-docs.quivo.co/connector-api-reference/addresses/remove-default-address /openapi.json delete /addresses/{sellerId}/default/{defaultAddressType} Remove the seller's default address assignment for the given address type. # Update address Source: https://api-docs.quivo.co/connector-api-reference/addresses/update-address /openapi.json put /addresses/{sellerId}/default/{defaultAddressType} Set or update the seller's default address for the given address type. # Update address Source: https://api-docs.quivo.co/connector-api-reference/addresses/update-address-1 /openapi.json put /addresses/{sellerId}/{addressId} Update an existing address for the specified seller. # Get API key request Source: https://api-docs.quivo.co/connector-api-reference/apikeyrequests/get-api-key-request /openapi.json get /apiKeyRequests Get API key request records. # Submit request Source: https://api-docs.quivo.co/connector-api-reference/apikeyrequests/submit-request /openapi.json post /apiKeyRequests/{sellerId} Submit an API key request for the specified seller. # Add image Source: https://api-docs.quivo.co/connector-api-reference/articles/add-image /openapi.json post /articles/{sellerId}/{articleId}/images Add image information and associate an image with the specified article. # Create article Source: https://api-docs.quivo.co/connector-api-reference/articles/create-article /openapi.json post /articles/{sellerId} Create a new article (product/SKU) for the specified seller. # Delete article Source: https://api-docs.quivo.co/connector-api-reference/articles/delete-article /openapi.json delete /articles/{sellerId}/{articleId} Delete an existing seller-scoped article. # Delete article Source: https://api-docs.quivo.co/connector-api-reference/articles/delete-article-1 /openapi.json delete /articles/{sellerId}/{articleId}/images/{uuid} Remove an image association from an article by image UUID. # Get article Source: https://api-docs.quivo.co/connector-api-reference/articles/get-article /openapi.json get /articles/{articleId} Get single article by its unique identifier. # Get article Source: https://api-docs.quivo.co/connector-api-reference/articles/get-article-1 /openapi.json get /articles/{sellerId}/{articleId} Get seller-scoped article by its ID. # List articles Source: https://api-docs.quivo.co/connector-api-reference/articles/list-articles /openapi.json get /articles List articles (products/SKUs) accessible to the authenticated account. # Lookup article Source: https://api-docs.quivo.co/connector-api-reference/articles/lookup-article /openapi.json get /articles/{sellerId}/identifier/{articleIdentifier} Look up up a seller-scoped article by an external identifier such as SKU. # Update article Source: https://api-docs.quivo.co/connector-api-reference/articles/update-article /openapi.json put /articles/{sellerId}/{articleId} Update an existing seller-scoped article. # Update article Source: https://api-docs.quivo.co/connector-api-reference/articles/update-article-1 /openapi.json put /articles/{sellerId}/{articleId}/validate Validate an article update payload without applying changes. # Upload image Source: https://api-docs.quivo.co/connector-api-reference/articles/upload-image /openapi.json post /articles/{sellerId}/{articleId}/images/upload Upload an image file and associate it with the specified article. # Validate payload Source: https://api-docs.quivo.co/connector-api-reference/articles/validate-payload /openapi.json post /articles/{sellerId}/validate Validate an article payload for a seller without creating it. # Get audits Source: https://api-docs.quivo.co/connector-api-reference/audits/get-audits /openapi.json get /audits Get audit log entries for recent actions and changes. # Create bundle Source: https://api-docs.quivo.co/connector-api-reference/bundles/create-bundle /openapi.json post /bundles/{sellerId} Create a new bundle for the specified seller. # Delete bundle Source: https://api-docs.quivo.co/connector-api-reference/bundles/delete-bundle /openapi.json delete /bundles/{sellerId}/{bundleId} Delete an existing seller-scoped bundle. # Get bundle Source: https://api-docs.quivo.co/connector-api-reference/bundles/get-bundle /openapi.json get /bundles/{sellerId}/{bundleId} Get seller-scoped bundle by its ID. # List bundles Source: https://api-docs.quivo.co/connector-api-reference/bundles/list-bundles /openapi.json get /bundles List bundles (grouped products) accessible to the account. # Update bundle Source: https://api-docs.quivo.co/connector-api-reference/bundles/update-bundle /openapi.json put /bundles/{sellerId}/{bundleId} Update an existing seller-scoped bundle. # List carrierss Source: https://api-docs.quivo.co/connector-api-reference/carriers/list-carrierss /openapi.json get /carriers List supported shipping carriers. # Create contact Source: https://api-docs.quivo.co/connector-api-reference/contacts/create-contact /openapi.json post /contacts/{sellerId} Create a new contact for the specified seller. # Delete contact Source: https://api-docs.quivo.co/connector-api-reference/contacts/delete-contact /openapi.json delete /contacts/{sellerId}/{contactId} Delete an existing contact for the specified seller. # List contacts Source: https://api-docs.quivo.co/connector-api-reference/contacts/list-contacts /openapi.json get /contacts/{sellerId} List contacts for the specified seller. # Update contact Source: https://api-docs.quivo.co/connector-api-reference/contacts/update-contact /openapi.json put /contacts/{sellerId}/{contactId} Update an existing contact for the specified seller. # List countriess Source: https://api-docs.quivo.co/connector-api-reference/countries/list-countriess /openapi.json get /countries List the list of supported countries. # Get exchange rates Source: https://api-docs.quivo.co/connector-api-reference/currencies/get-exchange-rates /openapi.json get /currencies/exchangeRates Get exchange rates used by the platform for currency conversions. # List currenciess Source: https://api-docs.quivo.co/connector-api-reference/currencies/list-currenciess /openapi.json get /currencies List the list of supported currencies. # Create customer inquiry Source: https://api-docs.quivo.co/connector-api-reference/customerinquiries/create-customer-inquiry /openapi.json post /customerInquiries Create a new customer inquiry. # Get customer inquiry Source: https://api-docs.quivo.co/connector-api-reference/customerinquiries/get-customer-inquiry /openapi.json get /customerInquiries/{customerInquiryId} Get single customer inquiry by its ID. # List customer inquirys Source: https://api-docs.quivo.co/connector-api-reference/customerinquiries/list-customer-inquirys /openapi.json get /customerInquiries List customer inquiries. # Post message Source: https://api-docs.quivo.co/connector-api-reference/customerinquiries/post-message /openapi.json post /customerInquiries/{customerInquiryId}/messages Post a message to an existing customer inquiry thread. # Resolve inquiry Source: https://api-docs.quivo.co/connector-api-reference/customerinquiries/resolve-inquiry /openapi.json post /customerInquiries/{customerInquiryId}/resolve Mark a customer inquiry as resolved. # Submit request Source: https://api-docs.quivo.co/connector-api-reference/customerinquiries/submit-request /openapi.json post /customerInquiries/{customerInquiryId}/ratings Submit a rating or feedback for a customer inquiry. # Upload file Source: https://api-docs.quivo.co/connector-api-reference/customerinquiries/upload-file /openapi.json post /customerInquiries/attachments Upload or attach files to a customer inquiry. # Create dashboards Source: https://api-docs.quivo.co/connector-api-reference/dashboards/create-dashboards /openapi.json post /dashboards Create a new dashboard configuration. # List dashboardss Source: https://api-docs.quivo.co/connector-api-reference/dashboards/list-dashboardss /openapi.json get /dashboards List dashboards available to the authenticated account. # Create files Source: https://api-docs.quivo.co/connector-api-reference/files/create-files /openapi.json post /files Upload a file and create a file resource for later linking or attachment. # Create fulfillment plan Source: https://api-docs.quivo.co/connector-api-reference/fulfillmentplans/create-fulfillment-plan /openapi.json post /fulfillmentPlans/{sellerId} Create a new fulfillment plan for the specified seller. # Create fulfillment plan Source: https://api-docs.quivo.co/connector-api-reference/fulfillmentplans/create-fulfillment-plan-1 /openapi.json post /fulfillmentPlans/{sellerId}/skuAddition Create a fulfillment plan request that adds SKUs for the specified seller. # Create fulfillment plan Source: https://api-docs.quivo.co/connector-api-reference/fulfillmentplans/create-fulfillment-plan-2 /openapi.json post /fulfillmentPlans/{sellerId}/skuFork Create a fulfillment plan request that forks or splits SKUs for the specified seller. # Create fulfillment plan Source: https://api-docs.quivo.co/connector-api-reference/fulfillmentplans/create-fulfillment-plan-3 /openapi.json post /fulfillmentPlans/{sellerId}/skuMapping Create a fulfillment plan request that maps seller SKUs to warehouse SKUs. # Create fulfillment plan Source: https://api-docs.quivo.co/connector-api-reference/fulfillmentplans/create-fulfillment-plan-4 /openapi.json post /fulfillmentPlans/{sellerId}/skuRemoval Create a fulfillment plan request that removes SKUs for the specified seller. # Delete fulfillment plan Source: https://api-docs.quivo.co/connector-api-reference/fulfillmentplans/delete-fulfillment-plan /openapi.json delete /fulfillmentPlans/{sellerId}/{planWhenId} Delete an existing fulfillment plan for the specified seller. # List fulfillment plans Source: https://api-docs.quivo.co/connector-api-reference/fulfillmentplans/list-fulfillment-plans /openapi.json get /fulfillmentPlans/{sellerId} List fulfillment plans configured for the specified seller. # Plan fulfillment Source: https://api-docs.quivo.co/connector-api-reference/fulfillmentplans/plan-fulfillment /openapi.json post /fulfillmentPlans/{sellerId}/preview Preview the effects of a fulfillment plan change without applying it. # Update fulfillment plan Source: https://api-docs.quivo.co/connector-api-reference/fulfillmentplans/update-fulfillment-plan /openapi.json put /fulfillmentPlans/{sellerId}/{planWhenId} Update an existing fulfillment plan for the specified seller. # Create inbound shipment Source: https://api-docs.quivo.co/connector-api-reference/inbounds/create-inbound-shipment /openapi.json post /inbounds Create a new inbound shipment or inbound delivery. # Delete inbound shipment Source: https://api-docs.quivo.co/connector-api-reference/inbounds/delete-inbound-shipment /openapi.json delete /inbounds/{inboundId} Delete an existing inbound shipment. # Get inbound shipment Source: https://api-docs.quivo.co/connector-api-reference/inbounds/get-inbound-shipment /openapi.json get /inbounds/{inboundId} Get single inbound shipment by its ID. # List inbound shipments Source: https://api-docs.quivo.co/connector-api-reference/inbounds/list-inbound-shipments /openapi.json get /inbounds List inbound shipments or inbound deliveries. # Update inbound shipment Source: https://api-docs.quivo.co/connector-api-reference/inbounds/update-inbound-shipment /openapi.json put /inbounds/{inboundId} Update an existing inbound shipment. # Validate update Source: https://api-docs.quivo.co/connector-api-reference/inbounds/validate-update /openapi.json put /inbounds/{inboundId}/validate Validate an inbound shipment payload or state before processing. # Get item Source: https://api-docs.quivo.co/connector-api-reference/items/get-item /openapi.json get /items/itemHistories/{warehouseId}/{sellerId} Get item history records for a specific warehouse and seller. # Get item Source: https://api-docs.quivo.co/connector-api-reference/items/get-item-1 /openapi.json get /items/{itemId} Get single inventory item by its ID. # Get item Source: https://api-docs.quivo.co/connector-api-reference/items/get-item-2 /openapi.json get /items/{itemId}/movements Get stock movement history for the specified item. # Get item Source: https://api-docs.quivo.co/connector-api-reference/items/get-item-3 /openapi.json get /items/{warehouseId}/{sellerId}/storages Get storage locations and quantities for a seller in the specified warehouse. # List items Source: https://api-docs.quivo.co/connector-api-reference/items/list-items /openapi.json get /items List inventory items. # List items Source: https://api-docs.quivo.co/connector-api-reference/items/list-items-1 /openapi.json get /items/{warehouseId}/{sellerId} List items for the specified seller within the specified warehouse. # Refresh data Source: https://api-docs.quivo.co/connector-api-reference/items/refresh-data /openapi.json post /items/seller/{sellerId}/refresh Trigger a refresh of inventory item data for the specified seller. # Refresh data Source: https://api-docs.quivo.co/connector-api-reference/items/refresh-data-1 /openapi.json post /items/{itemId}/refresh Trigger a refresh of the specified inventory item. # List languagess Source: https://api-docs.quivo.co/connector-api-reference/languages/list-languagess /openapi.json get /languages List the list of supported languages. # Create notification Source: https://api-docs.quivo.co/connector-api-reference/notifications/create-notification /openapi.json post /notifications/test-email Send a test notification email to verify email configuration. # Create notification Source: https://api-docs.quivo.co/connector-api-reference/notifications/create-notification-1 /openapi.json post /notifications/{notificationId}/seen Mark the specified notification as seen. # Delete notification Source: https://api-docs.quivo.co/connector-api-reference/notifications/delete-notification /openapi.json delete /notifications/id/{notificationId} Delete a notification by its ID. # Delete notification Source: https://api-docs.quivo.co/connector-api-reference/notifications/delete-notification-1 /openapi.json delete /notifications/{hash} Delete a notification using its access hash. # Get notification Source: https://api-docs.quivo.co/connector-api-reference/notifications/get-notification /openapi.json get /notifications/id/{notificationId} Get notification by its ID. # Get notification Source: https://api-docs.quivo.co/connector-api-reference/notifications/get-notification-1 /openapi.json get /notifications/{hash} Get notification using its access hash. # Get notification Source: https://api-docs.quivo.co/connector-api-reference/notifications/get-notification-2 /openapi.json get /notifications/{sellerId}/notificationTypes Get notification types configured or available for the specified seller. # List notifications Source: https://api-docs.quivo.co/connector-api-reference/notifications/list-notifications /openapi.json get /notifications List notifications for the authenticated user. # List notifications Source: https://api-docs.quivo.co/connector-api-reference/notifications/list-notifications-1 /openapi.json get /notifications/notificationTypes List the list of available notification types. # Update notification Source: https://api-docs.quivo.co/connector-api-reference/notifications/update-notification /openapi.json put /notifications/id/{notificationId} Update a notification by its ID. # Update notification Source: https://api-docs.quivo.co/connector-api-reference/notifications/update-notification-1 /openapi.json put /notifications/{hash} Update a notification using its access hash. # Cancel order Source: https://api-docs.quivo.co/connector-api-reference/orders/cancel-order /openapi.json post /orders/{orderId}/cancelRequest Request cancellation for an order that has not yet been completed. # Create order Source: https://api-docs.quivo.co/connector-api-reference/orders/create-order /openapi.json post /orders/extract Extract or export orders based on filters for reporting or integration use cases. # Create order Source: https://api-docs.quivo.co/connector-api-reference/orders/create-order-1 /openapi.json post /orders/{orderId}/planFulfillment Create a fulfillment plan for the specified order synchronously. # Delete order Source: https://api-docs.quivo.co/connector-api-reference/orders/delete-order /openapi.json delete /orders/{orderId}/attachments/{attachmentId} Remove a specific attachment from an order. # Delete order Source: https://api-docs.quivo.co/connector-api-reference/orders/delete-order-1 /openapi.json delete /orders/{orderId}/removePIIData Remove personally identifiable information from the specified order record. # Delete order Source: https://api-docs.quivo.co/connector-api-reference/orders/delete-order-2 /openapi.json delete /orders/{orderId}/removePIIDataAsync Start asynchronous removal of personally identifiable information from the specified order record. # Get order Source: https://api-docs.quivo.co/connector-api-reference/orders/get-order /openapi.json get /orders/entry/sellersWarehouses Get available seller and warehouse combinations for order entry. # Get order Source: https://api-docs.quivo.co/connector-api-reference/orders/get-order-1 /openapi.json get /orders/{orderId} Get full details for a single order by its ID. # List orders Source: https://api-docs.quivo.co/connector-api-reference/orders/list-orders /openapi.json get /orders Get a paginated list of orders that supports query, sorting, and pagination parameters to filter and structure the results. # List orders Source: https://api-docs.quivo.co/connector-api-reference/orders/list-orders-1 /openapi.json get /orders/entry/{sellerId}/countries List available destination countries for order entry for the specified seller. # List orders Source: https://api-docs.quivo.co/connector-api-reference/orders/list-orders-2 /openapi.json get /orders/entry/{sellerId}/{warehouseId}/countries List available destination countries for the specified seller from the specified warehouse. # Plan fulfillment Source: https://api-docs.quivo.co/connector-api-reference/orders/plan-fulfillment /openapi.json post /orders/{orderId}/planFulfillmentAsync Start fulfillment planning for the specified order asynchronously. # Refetch data Source: https://api-docs.quivo.co/connector-api-reference/orders/refetch-data /openapi.json post /orders/{orderId}/refetchOrderAttachments Refetch and synchronize order attachments from the source system. # Refetch data Source: https://api-docs.quivo.co/connector-api-reference/orders/refetch-data-1 /openapi.json post /orders/{orderId}/refetchOrderLines Refetch and synchronize order line items from the source system. # Refresh data Source: https://api-docs.quivo.co/connector-api-reference/orders/refresh-data /openapi.json post /orders/{orderId}/refetch Refetch and refresh the specified order from its source system. # Submit request Source: https://api-docs.quivo.co/connector-api-reference/orders/submit-request /openapi.json post /orders Submit a new order for processing, including essential details like delivery address, order identifier, and item positions. # Update order Source: https://api-docs.quivo.co/connector-api-reference/orders/update-order /openapi.json put /orders/{orderId}/address Update the delivery address for an existing order. # Update order Source: https://api-docs.quivo.co/connector-api-reference/orders/update-order-1 /openapi.json put /orders/{orderId}/attachments/{attachmentId} Update metadata for a specific attachment on an order. # Update resource Source: https://api-docs.quivo.co/connector-api-reference/orders/update-resource /openapi.json patch /orders/{orderId} Update an existing order by its ID. # Update resource Source: https://api-docs.quivo.co/connector-api-reference/orders/update-resource-1 /openapi.json patch /orders/{orderId}/confirmFulfillment Confirm fulfillment information for the specified order. # Upload file Source: https://api-docs.quivo.co/connector-api-reference/orders/upload-file /openapi.json post /orders/attachments/upload Upload a file that can be attached to an order. # Upload file Source: https://api-docs.quivo.co/connector-api-reference/orders/upload-file-1 /openapi.json post /orders/{orderId}/attachments Attach an existing uploaded file to the specified order. # Upload file Source: https://api-docs.quivo.co/connector-api-reference/orders/upload-file-2 /openapi.json post /orders/{orderId}/attachments/upload Upload and attach a file to the specified order in a single request. # Ping API Source: https://api-docs.quivo.co/connector-api-reference/ping/ping-api /openapi.json get /ping Check API health and verify the API is reachable. # Book shipment Source: https://api-docs.quivo.co/connector-api-reference/returnapp/book-shipment /openapi.json post /returnApp/book Book a return shipment through the returns application flow. # Get return app Source: https://api-docs.quivo.co/connector-api-reference/returnapp/get-return-app /openapi.json get /returnApp/{hash} Get return application data using the public return hash. # Create return link Source: https://api-docs.quivo.co/connector-api-reference/returnlinks/create-return-link /openapi.json post /returnLinks Create a new return link. # Delete return link Source: https://api-docs.quivo.co/connector-api-reference/returnlinks/delete-return-link /openapi.json delete /returnLinks/{returnLinkId} Delete an existing return link. # Get return link Source: https://api-docs.quivo.co/connector-api-reference/returnlinks/get-return-link /openapi.json get /returnLinks/{returnLinkId} Get single return link by its ID. # List return links Source: https://api-docs.quivo.co/connector-api-reference/returnlinks/list-return-links /openapi.json get /returnLinks List return links. # Update return link Source: https://api-docs.quivo.co/connector-api-reference/returnlinks/update-return-link /openapi.json put /returnLinks/{returnLinkId} Update an existing return link. # Get return shipment Source: https://api-docs.quivo.co/connector-api-reference/returns/get-return-shipment /openapi.json get /returns/{returnShipmentId} Get single return shipment by its ID. # List return shipments Source: https://api-docs.quivo.co/connector-api-reference/returns/list-return-shipments /openapi.json get /returns List returns and return shipments. # Update return shipment Source: https://api-docs.quivo.co/connector-api-reference/returns/update-return-shipment /openapi.json put /returns/{returnShipmentId} Update an existing return shipment. # Create seller Source: https://api-docs.quivo.co/connector-api-reference/sellers/create-seller /openapi.json post /sellers/{id}/logos Create or set the seller logo. # Get seller Source: https://api-docs.quivo.co/connector-api-reference/sellers/get-seller /openapi.json get /sellers/{id} Get details for a specific seller by ID. # List sellers Source: https://api-docs.quivo.co/connector-api-reference/sellers/list-sellers /openapi.json get /sellers List the list of sellers accessible to the authenticated account. # Upload file Source: https://api-docs.quivo.co/connector-api-reference/sellers/upload-file /openapi.json post /sellers/{id}/logos/upload Upload a logo file and associate it with the seller. # Book shipment Source: https://api-docs.quivo.co/connector-api-reference/shipments/book-shipment /openapi.json post /shipments/book Book a shipment and generate shipping labels or documents. # Book shipment Source: https://api-docs.quivo.co/connector-api-reference/shipments/book-shipment-1 /openapi.json post /shipments/bookBatchAsync Start booking multiple shipments asynchronously. # Book shipment Source: https://api-docs.quivo.co/connector-api-reference/shipments/book-shipment-2 /openapi.json post /shipments/bookShopAsync Start booking shipments for shop orders asynchronously. # Create shipment Source: https://api-docs.quivo.co/connector-api-reference/shipments/create-shipment /openapi.json post /shipments/estimate Get shipping cost and service estimates for a shipment request. # Create shipment Source: https://api-docs.quivo.co/connector-api-reference/shipments/create-shipment-1 /openapi.json post /shipments/pickups Schedule a new carrier pickup. # Delete shipment Source: https://api-docs.quivo.co/connector-api-reference/shipments/delete-shipment /openapi.json delete /shipments/{bookedShipmentId} Cancel or delete a booked shipment by its ID. # Get shipment Source: https://api-docs.quivo.co/connector-api-reference/shipments/get-shipment /openapi.json get /shipments/documentLink Get link to shipment documents such as labels or invoices. # Get shipment Source: https://api-docs.quivo.co/connector-api-reference/shipments/get-shipment-1 /openapi.json get /shipments/pickups Get scheduled carrier pickups. # Get shipment Source: https://api-docs.quivo.co/connector-api-reference/shipments/get-shipment-2 /openapi.json get /shipments/{bookedShipmentId} Get details for a booked shipment by its ID. # List shipments Source: https://api-docs.quivo.co/connector-api-reference/shipments/list-shipments /openapi.json get /shipments List shipments. # Upload file Source: https://api-docs.quivo.co/connector-api-reference/shipments/upload-file /openapi.json post /shipments/attachments/upload Upload a file that can be attached to a shipment. # Get countries Source: https://api-docs.quivo.co/connector-api-reference/shippingservicegroups/get-countries /openapi.json get /shippingServiceGroups/countries/{sellerId} Get countries covered by shipping service groups for the specified seller. # Get shipping service groups Source: https://api-docs.quivo.co/connector-api-reference/shippingservicegroups/get-shipping-service-groups /openapi.json get /shippingServiceGroups/{sellerId} Get shipping service groups configured for the specified seller. # List shipping service groupss Source: https://api-docs.quivo.co/connector-api-reference/shippingservicegroups/list-shipping-service-groupss /openapi.json get /shippingServiceGroups List shipping service groups. # List orders Source: https://api-docs.quivo.co/connector-api-reference/shoporders/list-orders /openapi.json get /shops/{shopId}/orders List orders imported from the specified shop. # Authorize shop Source: https://api-docs.quivo.co/connector-api-reference/shops/authorize-shop /openapi.json post /shops/authorize Authorize and connect a shop integration. # List shops Source: https://api-docs.quivo.co/connector-api-reference/shops/list-shops /openapi.json get /shops List connected shops and integrations. # Get status Source: https://api-docs.quivo.co/connector-api-reference/status/get-status /openapi.json get /status Get current system status and service availability indicators. # Get stored addresses Source: https://api-docs.quivo.co/connector-api-reference/storedaddresses/get-stored-addresses /openapi.json get /storedAddresses/{id} Get stored address by its ID. # List stored addresses Source: https://api-docs.quivo.co/connector-api-reference/storedaddresses/list-stored-addresses /openapi.json get /storedAddresses List the list of stored addresses available to the account. # Get subscription packages Source: https://api-docs.quivo.co/connector-api-reference/subscriptionpackages/get-subscription-packages /openapi.json get /subscriptionPackages/{sellerId} Get subscription package options for the specified seller. # List subscription packagess Source: https://api-docs.quivo.co/connector-api-reference/subscriptionpackages/list-subscription-packagess /openapi.json get /subscriptionPackages List available subscription packages. # Create subscription Source: https://api-docs.quivo.co/connector-api-reference/subscriptions/create-subscription /openapi.json post /subscriptions Create a new subscription. # Delete subscription Source: https://api-docs.quivo.co/connector-api-reference/subscriptions/delete-subscription /openapi.json delete /subscriptions/{uuid} Cancel and delete a subscription by its UUID. # Get subscription Source: https://api-docs.quivo.co/connector-api-reference/subscriptions/get-subscription /openapi.json get /subscriptions/{uuid} Get subscription by its UUID. # List subscriptions Source: https://api-docs.quivo.co/connector-api-reference/subscriptions/list-subscriptions /openapi.json get /subscriptions List subscriptions for the authenticated account. # Get shipsy Source: https://api-docs.quivo.co/connector-api-reference/track/get-shipsy /openapi.json get /track/gwc/shipsy/{trackingNumber} Get tracking status and events for the specified tracking number. # Create transport Source: https://api-docs.quivo.co/connector-api-reference/transports/create-transport /openapi.json post /transports Create a new transport record. # Get transport Source: https://api-docs.quivo.co/connector-api-reference/transports/get-transport /openapi.json get /transports/{transportId} Get transport record by its ID. # List transports Source: https://api-docs.quivo.co/connector-api-reference/transports/list-transports /openapi.json get /transports List transport records. # Create link Source: https://api-docs.quivo.co/connector-api-reference/users/create-link /openapi.json post /users/link Link a user account to a seller or organization. # Create reset password Source: https://api-docs.quivo.co/connector-api-reference/users/create-reset-password /openapi.json post /users/{username}/resetPassword Initiate a password reset for the specified user. # Update mfa Source: https://api-docs.quivo.co/connector-api-reference/users/update-mfa /openapi.json put /users/{username}/mfa Enable, disable, or update multi-factor authentication settings for the specified user. # Update sync Source: https://api-docs.quivo.co/connector-api-reference/users/update-sync /openapi.json put /users/{username}/sync Synchronize user details from the identity provider for the specified user. # List warehouses Source: https://api-docs.quivo.co/connector-api-reference/warehouses/list-warehouses /openapi.json get /warehouses List the list of warehouses available to the authenticated account. # Integrate with Quivo Source: https://api-docs.quivo.co/docs/introduction/integrating-with-quivo This concept page explains how to access The Connector, understand your credentials, find your Seller ID, and choose the right environment before building with the Quivo API. For step-by-step authentication, see the [Make your first API call](/docs/introduction/first-api-call) tutorial. ## Prerequisites Before you start, make sure you have: * **Merchant account:** Provisioned by Quivo. * **Connector Web App access:** Ability to sign in to The Connector. * **API credentials:** Static API key, username, and password issued by Quivo. * **Seller ID:** Your merchant identifier needed for API operations. If you need a merchant account or Connector access, contact Quivo support. ## Access The Connector * Sign in to The Connector Web App with your Quivo credentials: * **Production:** [https://app.quivo.co/](https://app.quivo.co/) * **Sandbox:** [https://app-sandbox.quivo.co/](https://app-sandbox.quivo.co/) * Manage logistics operations and, when provided, retrieve your API key from the web app. ## Credential model * **Static API key:** Provided by Quivo; send in the `X-Api-Key` header. * **Username and password:** Your Quivo login; used with the API key to obtain a session token. * **Session token:** Obtained via `POST /login`; send in the `Authorization` header for API calls. For authentication flows and header examples, see the [Authentication guide](/api-reference/authentication). ## Getting an API key * Quivo issues your static API key during onboarding or via The Connector. * The separate How-To guide, [Request an API Key](/docs/quickstart/request-api-key), covers detailed, step-by-step API key request flows for both UI and API. ## Find your Seller ID * Your Seller ID uniquely scopes API operations to your merchant account. * Retrieve it via the [`GET /sellers endpoint`](/api-reference/#tag/sellers) after you have a session token. ## Choose your environment * Use the correct `${BASE_URL}` configured for your account: * **Production:** `https://api.quivo.co` * **Sandbox:** `https://api-sandbox.quivo.co` * Keep base URLs, API keys, and session tokens separate per environment. An API key is always required in the `X-Api-Key` header. ## Where to go next Learn how to authenticate and make your first API call to verify your setup. Send your products to Quivo warehouses to make them available for fulfillment. # Logistics Glossary Source: https://api-docs.quivo.co/docs/introduction/logistics-glossary This reference provides precise definitions of key logistics terms used throughout the Quivo API documentation. Use this glossary to understand terminology and keep vocabulary aligned when working with the Quivo Connector. ## SKU SKU stands for Stock Keeping Unit. In the Quivo system, a SKU is the unique identifier for an article product in the system. You use SKUs to: * Identify products when sending inventory to warehouses * Reference products when creating fulfillment orders * Track inventory levels and quantities Each product in your catalog must have a unique SKU. The SKU appears in API requests and responses when working with articles, inventory, orders, and inbound shipments. The Quivo API supports both seller SKUs and warehouse SKUs. Some sellers use warehouse SKUs (`warehouseSku`) while others use seller SKUs (`sellerSku`). See the [Send Inventory guide](/docs/quickstart/send-inventory) for details on using SKUs in inbound shipments. ## Inbound An Inbound is a record that notifies the Quivo warehouse team that you are sending a shipment of products. You create an inbound record before shipping products to a warehouse so the warehouse can plan for the arrival and process the inventory. When you create an inbound record, you specify: * Which products and their SKUs you are sending * The quantity of each product * The warehouse destination * Expected arrival information The inbound process has several statuses: * `PENDING`: The inbound has been received; however, we cannot start processing it due to missing information. * `CREATED`: You have notified Quivo, but the package hasn’t arrived * `PROCESSING`: The warehouse is currently counting and booking the stock * `COMPLETED`: The warehouse booked all items into inventory, and they are ready to sell * `CANCELLED`: The inbound is cancelled Once an inbound completes, the products are available in inventory, and you can create fulfillment orders for those items. For detailed instructions on creating and tracking inbounds, see the [Send Inventory guide](/docs/quickstart/send-inventory). ## Pick & Pack Pick & Pack is the warehouse process where warehouse staff: * Pick items from inventory based on order requirements * Pack the items into shipping containers with appropriate packaging When you create a fulfillment order through the API, you trigger the Pick & Pack process automatically. The warehouse team receives the instruction and begins picking the ordered items from inventory, then packs them for shipment to the customer. The Pick & Pack process is part of the fulfillment workflow. After you create an order, the warehouse processes it through Pick & Pack, then ships the package to the customer's delivery address. For instructions on creating orders that trigger Pick & Pack, see the [Create a Fulfillment Order guide](/docs/quickstart/create-order). ## Last Mile Last Mile refers to the final stage of delivery from a distribution center or warehouse to the end customer's delivery address. This is the final leg of the shipping process where carriers transport packages to their final destination. The last-mile delivery stage is critical for customer satisfaction, as it represents the final touchpoint before the customer receives their order. Carriers handle the last-mile delivery using various transportation methods to reach the customer's address. ## Fulfillment Fulfillment refers to the complete process of receiving, processing, and shipping customer orders. In the Quivo Fulfillment Service model, Quivo manages the entire fulfillment process, including storage, order processing, packaging, and shipping. ## Warehouse A warehouse is a storage facility where products are stored before being shipped to customers. Quivo operates fulfillment centers in multiple locations: Germany, Austria, the United Kingdom, France, and the United States, plus partner hubs. ## Carrier A carrier is a shipping company that transports packages from the warehouse to the customer. Quivo supports major carriers including Royal Mail, DHL (Deutsche Post DHL), DPD (Dynamic Parcel Distribution), and FedEx. ## Shipment A shipment is a package prepared for delivery. Shipments include tracking information, and Quivo assigns them to carriers for transportation to the delivery address. ## Order An Order, also called a Fulfillment Order, is a request to fulfill a customer purchase. When you create an order through the API, you trigger the Pick & Pack process in the warehouse. An order contains: * Order identifiers `orderIdentifier` and `orderReference` to track the order and prevent duplicates * Delivery address for the customer * List of product positions with SKUs and quantities Orders progress through several statuses: * `PENDING`: The order has been received; however, we cannot start processing it due to missing information. * `PROCESSING`: The warehouse is currently picking and packing the items * `COMPLETED`: The order has been packed and handed over to the carrier * `CANCELLED`: The order was cancelled before fulfillment For instructions on creating orders, see the [Create a Fulfillment Order guide](/docs/quickstart/create-order). ## Article An Article is a product definition in your catalog. Each article has a unique SKU that identifies it. Articles contain product information such as name, SKU, weight, dimensions, and other attributes needed for fulfillment. You must create articles in the system before you can send them as inventory or include them in orders. You create articles using the `POST /articles` endpoint. An article is a product definition, while an item represents physical inventory. See the Item definition for the distinction. ## Item An Item is a physical unit of inventory stored in a warehouse. The system creates items from articles after you send inventory to a warehouse and the inbound shipment completes. The relationship between articles and items: * An article is a product definition * An item is physical stock at a specific warehouse location * One article can have many items across different warehouses * Each item represents available inventory ready for fulfillment You check item inventory levels using the Items API (`GET /items`). Items contain information about quantity, reserved amounts, and warehouse location. For instructions on monitoring inventory, see the [Monitor Inventory guide](/docs/quivo-guides/monitor-inventory). ## Seller A Seller is a merchant account in the Quivo system. Each seller has a unique integer seller ID that identifies the merchant account. You use your seller ID to scope operations to your account's data and resources. The seller ID appears in API requests when creating orders, sending inventory, and managing other operations. You can retrieve your seller ID using the `GET /sellers` endpoint. ## Inventory Inventory refers to the stock of products available in Quivo warehouses. Products become part of your inventory after you send them to a warehouse through an inbound shipment and the inbound completes. The system tracks inventory levels by SKU and warehouse. You can check inventory levels using the API to see how many units of each product are available for fulfillment. ## Tracking Tracking refers to the ability to monitor the location and status of a shipment as it moves from the warehouse to the customer. Each shipment receives a tracking number from the carrier, which you can use to check delivery status. The Quivo API provides tracking numbers and tracking links in order and shipment responses. You can share these with customers so they can monitor their package delivery. ## Return A Return is a shipment sent back from a customer to the Quivo warehouse. Quivo processes returns when customers need to send products back, for example, due to defects, wrong items, or customer preference. You can generate return labels programmatically through the API. When a return arrives at the warehouse, staff inspect it and update the return status. You can track returns and their inspection status through the API. For instructions on managing returns, see the [Manage Returns guide](/docs/quickstart/manage-returns). ## Webhook A Webhook is a mechanism that allows Quivo to send real-time notifications to your server when specific events occur. Instead of polling the API for status changes, webhooks push data to your endpoint via HTTP POST requests. You can subscribe to webhooks for entities such as: * `ORDERS`: Order creation and status changes * `SHIPMENTS`: Shipment creation and tracking updates * `INBOUNDS`: Inbound shipment status changes * `RETURNS`: Return creation and receipt at the warehouse * `INVOICES`: Invoice creation and updates For instructions on setting up webhooks, see the [Manage Subscriptions guide](/docs/webhooks/manage-subscriptions). ## Where to go next Now that you understand these key terms, continue with these guides: Learn how to create inbound records to send products to Quivo warehouses. Learn how to create orders that trigger the Pick & Pack process. # Overview Source: https://api-docs.quivo.co/docs/introduction/overview This overview explains what Quivo is and the platform structure. For step-by-step instructions, see the [Make your first API call tutorial](/docs/introduction/first-api-call) and the core workflow guides. Quivo is a third-party logistics provider (3PL) created from the merger of LOGSTA and ANCLA (PackAngels). It operates fulfillment centers in Germany, Austria, the United Kingdom, France, and the United States, and has partner hubs through a strategic partnership with GWC Group (Gulf Warehousing Company) in the Gulf region, including Qatar, the United Arab Emirates, Saudi Arabia, Bahrain, and Oman. The Quivo platform combines warehouse operations with the Quivo Connector, which exposes APIs and integrations to manage the order lifecycle from inventory intake to delivery. The platform integrates with multiple shop systems, including Shopify, WooCommerce, Magento, Amazon Fulfillment by Merchant (FBM), TikTok, Wix, Shopware, and PrestaShop, and with shipping providers such as Royal Mail, DHL (Deutsche Post DHL Group), Dynamic Parcel Distribution (DPD), and FedEx. ## Ecosystem Quivo offers two primary service models. The Quivo API supports both models and provides access to Quivo transport services. ### Fulfillment Service In the Fulfillment Service model, Quivo manages the entire logistics process on behalf of the merchant. This includes: * Storing products in Quivo's dedicated fulfillment centers * Handling order processing, packaging, and shipping directly to customers * Seamless integration with over 40 shop and Enterprise Resource Planning (ERP) systems * Real-time inventory tracking * Customized packaging options * Returns management ### Send It Yourself The Send It Yourself (SIY) model serves merchants who handle storage, packing, and shipping themselves. Through the Quivo Connector, merchants can: * Integrate their online shop systems * Compare shipping options * Print shipping labels * Manage shipments efficiently ### Transport services Quivo transport services support both service models and include pallet and container transport via truck, air, or sea freight. ## API integration Quivo exposes APIs to manage inventory, orders, and shipments. These APIs serve as the technical foundation of the Quivo platform. You can find the API reference [here](/api-reference/api-overview). ## Quickstart The following guides walk you through the main workflows for integrating with Quivo: Notify the Quivo warehouse that you are sending a shipment of products. Learn how to create inbound records and manage inventory shipments. Programmatically submit fulfillment orders to the Quivo Connector. Trigger the pick and pack process for your products. Retrieve current status and tracking information for orders. Monitor shipment progress and delivery status. Generate return labels and track returned items. Learn how to process customer returns through the API. Configure event subscriptions for real-time notifications. Set up webhooks to receive updates about order status changes and other events. # Create a Fulfillment Order Source: https://api-docs.quivo.co/docs/quickstart/create-order This tutorial guides you step by step through creating a fulfillment order and triggering the "Pick & Pack" process in the warehouse for your products. ## 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. * **Seller ID:** Use the [`GET /sellers endpoint`](/api-reference/#tag/sellers) to find it. * **Product SKU:** Create at least one product via the [`POST /articles endpoint`](/api-reference/#tag/articles) before ordering it. 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). ## Create the order request To create an order, construct a JSON object that matches the `OrderPost` schema using the [`POST /orders endpoint`](/api-reference/#tag/orders). You must provide four main fields in the payload: 1. **Seller Context:** Identifies the merchant account `sellerId`. 2. **Order Identifiers:** Unique IDs to track the order and prevent duplicates `orderIdentifier` and `orderReference`. 3. **Delivery Address:** The destination for the package `deliveryAddress`. 4. **Order Positions:** The list of items to ship `positions`, including SKUs, names, and quantities. The following example shows an order payload with all required fields: Use this request to create a new fulfillment order with basic delivery and position data. ```bash theme={null} curl -X POST "${BASE_URL}/orders" \ -H "X-Api-Key: " \ -H "Authorization: " \ -H "Content-Type: application/json" \ -d '{ "sellerId": , "orderIdentifier": "", "orderReference": "", "deliveryAddress": { "company": "", "name": "", "email": "", "street": "", "city": "", "zip": "", "countryIso2": "" }, "positions": [ { "sku": "", "name": "", "quantity": }, { "sku": "", "name": "", "quantity": } ] }' ``` A successful request returns a `200 OK` status code and an `OrderPostResult` object. ```json theme={null} { "status": "OK", "message": "Order created successfully", "orderId": } ``` Capture the `orderId` from the response. You need this ID to track the order status later. For the complete order request schema—including all required and optional fields—see the [Orders section in the API Reference](/api-reference/#tag/orders). ## Where to go next Now that you have created the order, the warehouse team receives the Pick & Pack instruction automatically. Continue with these guides: Monitor order status and retrieve tracking information when Quivo ships the order. Set up webhooks to receive automatic notifications when order status changes or when Quivo generates tracking numbers. # Manage Returns Source: https://api-docs.quivo.co/docs/quickstart/manage-returns This guide shows you how to programmatically generate return shipping labels and track returned items. Handling returns efficiently is crucial for customer satisfaction. The API allows you to generate a shipping label that your customer can use to send an item back to the Quivo warehouse. ## 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. * **Seller ID:** Use the [`GET /sellers endpoint`](/api-reference/#tag/sellers) to find it. * **Shipping Service Group ID:** Use the [`GET /shippingServiceGroups endpoint`](/api-reference/#tag/shippingServiceGroups) to select the carrier/service for the return. 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). ## Book a return label To let a customer return an item, you must generate a shipping label for them via the [`POST /returnApp/book endpoint`](/api-reference/#tag/returnApp). You need to provide the "Ship From" address (your customer's house) and the weight of the package. The following example shows how to send a complete return request payload in one command: Use this request to book a return shipping label for your customer. ```bash theme={null} curl -X POST "${BASE_URL}/returnApp/book" \ -H "X-Api-Key: " \ -H "Authorization: " \ -H "Content-Type: application/json" \ -d '{ "requestUUID": "", "hash": "", "reference": "", "grossWeightKG": , "shipFrom": { "name": "", "street": "", "city": "", "zip": "", "countryIso2": "", "email": "" } }' ``` A successful request returns a `200 OK` status code with a response containing the tracking number and URLs to the PDF label (`labelUrls`). You should email this link or file to your customer. ```json theme={null} { "status": "OK", "trackingNumber": "", "labelUrls": [ "" ] } ``` ## Track received returns When the package arrives back at the Quivo warehouse, the staff inspects it. You can list all received returns to see their status and condition via the [`GET /returns endpoint`](/api-reference/#tag/returns). Use this request to list all received returns and review their status. ```bash theme={null} curl -X GET "${BASE_URL}/returns?sort=created:desc" \ -H "X-Api-Key: " \ -H "Authorization: " ``` A successful request returns a `200 OK` status code. The response returns an array of `ReturnShipmentSummary` objects. The following example shows the structure of a return in the array: ```json theme={null} { "returnShipmentId": , "returnShipmentIdentifier": "", "returnShipmentReference": "", "sellerId": , "warehouseId": , "orderId": , "trackingNumber": "", "trackingLink": "", "receivedDate": "", "customerExamined": false, "positions": [ { "sellerSku": "", "warehouseSku": "", "name": "", "quantity": , "classCode": "", "reasonCode": "" } ] } ``` The response (`ReturnShipmentSummary`) contains critical information for processing refunds. Timestamps use the ISO 8601 pattern YYYY-MM-DDTHH:mm:ssZ in Coordinated Universal Time. * `returnShipmentReference`: Matches the reference you provided, for example `""`. * `positions`: Lists the items inside the box. * `customerExamined`: A boolean indicating if the warehouse has finished inspecting the item. * `reasonCode` / `classCode`: If available, details on why it was returned and its condition. ## Where to go next Now that you can manage returns, continue with these guides: Check the status of the original order to understand the full fulfillment lifecycle. Create new orders for replacement items or refund processing. # Request an API Key Source: https://api-docs.quivo.co/docs/quickstart/request-api-key This how-to shows two ways to request and track your Quivo API key: through The Connector web app (UI) or via the API. If you already have your key, proceed to [Make your first API call](/docs/introduction/first-api-call). ## Prerequisites Before you start, make sure you have: * **Connector Web App access:** To use the UI flow. * **Credentials:** Your Quivo login for The Connector. * **API access (for API flow):** Ability to call authenticated endpoints. See the [Authentication guide](/api-reference/authentication). ## Request your API key 1. Sign in to The Connector Web App. 2. In the left sidebar, open Admin. 3. Click Request API Key. 4. Submit the request and wait for approval. 5. After approval, the API Key field appears on this page; use the copy icon to copy it. To request an API key via the API, you need to get your Seller ID first, then submit the request, and finally check the status. Follow these steps: ### Get your Seller ID If you don't know your Seller ID, retrieve it after authenticating. ```bash theme={null} curl -X GET "${BASE_URL}/sellers" \ -H "X-Api-Key: " \ -H "Authorization: " ``` Key fields in the response: * `id`: Your Seller ID (integer) * `status`: One of `ACTIVE`, `BLOCKED`, `TERMINATED`, `NEW`, `PENDING` ### Request the API key ```bash theme={null} curl -X POST "${BASE_URL}/apiKeyRequests/{sellerId}" \ -H "Content-Type: application/json" ``` Replace `{sellerId}` with your Seller ID. ### Check request status ```bash theme={null} curl -X GET "${BASE_URL}/apiKeyRequests" \ -H "X-Api-Key: " \ -H "Authorization: " ``` * Use the correct `${BASE_URL}` configured for your account. * Contact Quivo support if you hit authentication issues or if your request is stalled. ## Check status & retrieve your key After approval, sign back into The Connector and open the Request API Keys section under Admin. Use the copy icon to copy the key. Periodically call `GET /apiKeyRequests` and inspect each request’s `status` field: ```bash theme={null} curl -X GET "${BASE_URL}/apiKeyRequests" \ -H "X-Api-Key: " \ -H "Authorization: " ``` The response contains an array of requests with `status` values such as `PENDING`, `APPROVED`, `REJECTED`, or `EXPIRED`. When the status for your request changes to `APPROVED`, check whether the response includes the key in the `value` field; if it does, store it securely and start using it in the `X-Api-Key` header. If the key isn’t exposed in the response, contact Quivo support. ## Where to go next Get a session token and make your first authenticated request. Notify the warehouse that you are sending products so they are ready for fulfillment. # Send Inventory (Inbound) Source: https://api-docs.quivo.co/docs/quickstart/send-inventory This tutorial guides you step by step through creating an "Inbound" record to notify the Quivo warehouse team that you are sending products. To fulfill orders, you need inventory available in a Quivo warehouse. This API flow creates an inbound record so the warehouse can plan for the arrival and process the inventory. ## 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. * **Seller ID:** Use the [`GET /sellers endpoint`](/api-reference/#tag/sellers) to find it. * **Warehouse ID:** Use the [`GET /warehouses endpoint`](/api-reference/#tag/warehouses) to list available warehouses. * **Product SKUs:** The items you are sending must already exist. Use the [`GET /articles endpoint`](/api-reference/#tag/articles) to find them. 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). ## Create the inbound request Create an inbound record when you are preparing to send products to a Quivo warehouse. You must tell the warehouse exactly what’s coming so they can plan for its arrival using the [`POST /inbounds endpoint`](/api-reference/#tag/inbounds). The following example shows a complete inbound payload with all required fields and some common optional fields. Use this request to create a new inbound record and notify the warehouse about incoming stock. ```bash theme={null} curl -X POST "${BASE_URL}/inbounds" \ -H "X-Api-Key: " \ -H "Authorization: " \ -H "Content-Type: application/json" \ -d '{ "sellerId": , "warehouseId": , "deliverySlipNumber": "", "estimatedArrivalTime": "", "trackingNumber": "", "carrier": "", "deliveryInfo": { "cargoType": "CARTON", "quantity": }, "inboundPositions": [ { "sku": "", "quantity": }, { "sku": "", "quantity": } ], "shipFrom": { "company": "", "address1": "", "city": "", "country": "", "zip": "" } }' ``` A successful request returns a `200 OK` status code. ```json theme={null} { "status": "OK", "inboundId": , "message": "Inbound created successfully" } ``` **Important:** Save the `inboundId` returned in the response. You may need to print this ID on the shipping label so the warehouse can identify the boxes when they arrive. For the complete inbound request schema—including all required and optional fields—see the [Inbounds section in the API Reference](/api-reference/#tag/inbounds). ## Track inbound status After creating an inbound record, use this endpoint to monitor the processing status. Once your shipment arrives, the warehouse team starts scanning the items. Check the status of this process via the API using the [`GET /inbounds/{inboundId} endpoint`](/api-reference/#tag/inbounds). Use this request to retrieve the current status of an existing inbound by its ID. ```bash theme={null} curl -X GET "${BASE_URL}/inbounds/" \ -H "X-Api-Key: " \ -H "Authorization: " ``` A successful request returns a `200 OK` status code. The response returns an `InboundGet` object with details about the inbound: ```json theme={null} { "id": , "sellerId": , "warehouseId": , "shopId": , "inboundStatus": "PROCESSING", "deliverySlipNumber": "", "estimatedArrivalTime": "", "trackingNumber": "", "carrier": "", "created": "", "completedAt": "", "shipFrom": { "company": "", "address1": "", "city": "", "country": "", "zip": "" }, "deliveryInfo": { "cargoType": "CARTON", "quantity": }, "inboundPositions": [ { "sku": "", "quantity": } ] } ``` Look for the `inboundStatus` field in the response to see the current status of the inbound: * `PENDING`: The inbound has been received; however, processing cannot start due to missing information. * `CREATED`: You have notified Quivo, but the package hasn't arrived. * `PROCESSING`: The warehouse is currently counting and booking the stock. * `COMPLETED`: The warehouse booked all items into inventory, and they're ready to sell. If the inbound completes, you can start the next step to create the order. * `CANCELLED`: Quivo cancelled the inbound. ## Where to go next Now that you have sent inventory to the warehouse, continue with these guides: Once Quivo processes your inventory, create fulfillment orders to start shipping products to customers. Monitor order status and retrieve tracking information for shipments. # Track an Order Source: https://api-docs.quivo.co/docs/quickstart/track-order This guide shows you how to programmatically check if Quivo shipped an order and retrieve the carrier's tracking link to share with your customer. ## 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. 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). ## Retrieve order details To track an order, retrieve its full details using its unique ID via the [`GET /orders/{orderId} endpoint`](/api-reference/#tag/orders). A successful request returns a 200 OK status. The response body contains the order's current state. Focus on two specific sections: the status and the tracking information. Timestamps use the ISO 8601 pattern YYYY-MM-DDTHH:mm:ssZ in Coordinated Universal Time UTC. Use this request to retrieve the current status and tracking information for a specific order: ```bash theme={null} curl -X GET "${BASE_URL}/orders/" \ -H "X-Api-Key: " \ -H "Authorization: " ``` A successful request returns a `200 OK` status code. ```json theme={null} { "orderId": , "orderIdentifier": "", "orderReference": "", "orderStatus": "", "orderDate": "", "completedAt": "", "shippingMethodName": "", "shipmentTracking": [ { "number": "", "link": "" } ], "positions": [ { "sku": "", "name": "", "quantity": } ] } ``` Locate the `orderStatus` field in the response body. This field indicates where the order is in the fulfillment lifecycle. | Status | Description | | ------------ | ----------------------------------------------------------------------------------------------- | | `PENDING` | The order has been received; however, we cannot start processing it due to missing information. | | `PROCESSING` | The warehouse is currently picking and packing the items. | | `COMPLETED` | The warehouse packed the order and handed it over to the carrier. | | `CANCELLED` | The order is cancelled before fulfillment. | Once the status changes to `COMPLETED`, the system generates tracking information. Find this in the `shipmentTracking` array. * `number`: The tracking number assigned by the carrier. * `link`: A direct URL to the carrier's tracking page. ## Where to go next Now that you can track orders, you can continue with these guides: Generate return labels and track returned items when customers need to send products back. Automate order tracking by setting up webhooks to receive real-time status updates. # Create Products Source: https://api-docs.quivo.co/docs/quivo-guides/create-products This tutorial guides you step by step through creating your first article. An article is a product in the Quivo system. Each article must have a unique SKU that identifies it. You must create articles before you can send them as inventory to warehouses or include them in fulfillment orders. ## 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. * **Seller ID:** Use the [`GET /sellers endpoint`](/api-reference/#tag/sellers) to find it. 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). ## Create your first article To create an article, use the [`POST /articles/{sellerId} endpoint`](/api-reference/#tag/articles). For warehouse processing of inbounds and orders, include at least `sku`, `name`, `barcode`, and weight (`grossWeight` or `netWeight` with `unit`). The following example shows how to create an article with essential fields: Use this request example to create a new article with essential product data. ```bash theme={null} curl -X POST "${BASE_URL}/articles/" \ -H "X-Api-Key: " \ -H "Authorization: " \ -H "Content-Type: application/json" \ -d '{ "sku": "", "name": { "value": "", "language": "EN" }, "grossWeight": { "value": , "unit": "KG" }, "length": { "value": , "unit": "CM" }, "width": { "value": , "unit": "CM" }, "height": { "value": , "unit": "CM" }, "countryOfOrigin": "", "salesPrice": { "value": , "currencyCode": "" } }' ``` A successful request returns a `200 OK` status code with an `ArticleGetDetail` object: ```json theme={null} { "articleId": , "sellerId": , "sku": "", "name": { "value": "", "language": "EN" }, "barcode": "", "grossWeight": { "value": , "unit": "KG" }, "created": "", "lastModified": "" } ``` Save the `articleId` from the response. You need this ID to update the article or upload images later. Timestamps follow the ISO 8601 pattern YYYY-MM-DDTHH:mm:ssZ in Coordinated Universal Time UTC. **Required for warehouse processing:** To process inbounds and orders in the warehouse, include at least `sku`, `name`, `barcode`, and weight (`grossWeight` or `netWeight` with `unit`). For a complete list of additional fields—including `customsValue`, `alternativeNames`, and more—see the [API Reference](/api-reference/#tag/articles). ## Where to go next Now that you can create articles, continue with these guides: Learn how to update articles, upload images, search your catalog, and validate product data. Send your products to Quivo warehouses. # Manage Orders Source: https://api-docs.quivo.co/docs/quivo-guides/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. 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). ## 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: Use this request to update order details: ```bash theme={null} curl -X PATCH "${BASE_URL}/orders/" \ -H "X-Api-Key: " \ -H "Authorization: " \ -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](#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`. Use this request to update the delivery address: ```bash theme={null} curl -X PUT "${BASE_URL}/orders//address?type=DELIVERY" \ -H "X-Api-Key: " \ -H "Authorization: " \ -H "Content-Type: application/json" \ -d '{ "name": "", "email": "", "phone": "", "street": "", "street2": "", "city": "", "zip": "", "state": "", "countryIso2": "" }' ``` 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`](/api-reference/#tag/orders). Once you cancel an order, fulfillment can't proceed. Use this request to cancel an order: ```bash theme={null} curl -X POST "${BASE_URL}/orders//cancelRequest" \ -H "X-Api-Key: " \ -H "Authorization: " ``` 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: Monitor order status and retrieve tracking information when Quivo ships orders. Generate return labels and track returned items when customers need to send products back. # Manage Product Bundles Source: https://api-docs.quivo.co/docs/quivo-guides/manage-product-bundles A bundle is a product definition that groups multiple articles together into a single offering. Each bundle has its own SKU (stock keeping unit) that you can use in orders. When you use a bundle SKU in an order, the system processes the bundle during the fulfillment process. Bundles enable you to: * Sell sets of products together as a single item * Manage complex product combinations A bundle contains: * A unique SKU that identifies the bundle * A list of bundle items, where each item references an article and specifies a quantity * Optional metadata such as name, weight, and customs value This guide shows you how to create product bundles and use bundles in fulfillment orders. ## 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. * **Seller ID:** Use the [`GET /sellers endpoint`](/api-reference/#tag/sellers) to find it. * **Existing articles:** Create the articles that you want to include in bundles. See the [Create Products guide](/docs/quivo-guides/create-products) if you have not created articles 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](/api-reference/environments). ## Create a bundle Create a bundle using the [`POST /bundles/{sellerId} endpoint`](/api-reference/#tag/bundles). You must provide a SKU, and you can optionally include bundle items and other metadata. Use `articleId` values that reference articles in your catalog. The following example shows how to create a bundle with bundle items: Use this request to create a new bundle: ```bash theme={null} curl -X POST "${BASE_URL}/bundles/" \ -H "X-Api-Key: " \ -H "Authorization: " \ -H "Content-Type: application/json" \ -d '{ "sku": "", "name": { "value": "", "language": "EN" }, "bundleItems": [ { "articleId": , "quantity": 2 }, { "articleId": , "quantity": 1 } ], "grossWeight": { "value": 1.5, "unit": "KG" }, "customsValue": { "value": 29.99, "currencyCode": "EUR" } }' ``` A successful request returns a `200 OK` status code with a `BundleGetDetail` object: ```json theme={null} { "id": , "sellerId": , "sku": "", "name": { "value": "", "language": "EN" }, "bundleItems": [ { "id": , "articleId": , "articleSku": "", "quantity": 2 }, { "id": , "articleId": , "articleSku": "", "quantity": 1 } ], "grossWeight": { "value": 1.5, "unit": "KG" }, "customsValue": { "value": 29.99, "currencyCode": "EUR" }, "created": "", "lastModified": "" } ``` Save the `id` from the response. You need this ID to retrieve, update, or delete the bundle later. Timestamps use the ISO 8601 format YYYY-MM-DDTHH:mm:ssZ. The following table describes the key fields you can include when creating a bundle. For complete field definitions, see the [API Reference](/api-reference/#tag/bundles): | Field | Type | Description | | -------------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `sku` | String (1-50 characters) | The SKU that identifies this bundle. | | `bundleItems` | Array of objects | Each item includes `articleId` (integer, required) and `quantity` (integer, minimum 1, required). Optionally includes `articleSku` (string) and `unitCustomsValue` (number). | | `name` | Object | Object with `value` (string) and `language` (string). | | `grossWeight` | Object | Object with `value` (number) and `unit` (string). | | `netWeight` | Object | Object with `value` (number) and `unit` (string). | | `customsValue` | Object | Object with `value` (number) and `currencyCode` (string). | | `alternativeSkus` | Array of strings | Array of string values. | | `alternativeNames` | Array of objects | Array of name objects (same structure as `name`). | | `alternativeCustomsValues` | Array of objects | Array of customs value objects (same structure as `customsValue`). | ## Search bundles Search for bundles using the [`GET /bundles endpoint`](/api-reference/#tag/bundles). This endpoint supports query, sorting, and pagination parameters. Use the `query` parameter to filter results, `sort` to order them, and `pageSize` to limit the number of results. Use this request to search for bundles using query parameters: ```bash theme={null} curl -X GET "${BASE_URL}/bundles?query=sku:&sort=created:desc&pageSize=50" \ -H "X-Api-Key: " \ -H "Authorization: " ``` A successful request returns a `200 OK` status code with an array of `BundleGetSummary` objects: ```json theme={null} [ { "id": , "sellerId": , "sku": "", "name": { "value": "", "language": "EN" } } ] ``` ## Retrieve bundle details Retrieve bundle details using the bundle ID. Use the [`GET /bundles/{sellerId}/{bundleId} endpoint`](/api-reference/#tag/bundles) to get details by bundle ID: Use this request to retrieve the full details of a bundle by its ID: ```bash theme={null} curl -X GET "${BASE_URL}/bundles//" \ -H "X-Api-Key: " \ -H "Authorization: " ``` A successful request returns a `200 OK` status code with the full bundle details as a `BundleGetDetail` object, including all bundle items and metadata. ## Update a bundle Update an existing bundle using the [`PUT /bundles/{sellerId}/{bundleId} endpoint`](/api-reference/#tag/bundles). Send a JSON object with the bundle data you want to update, using the same structure as the `BundlePost` schema used for creating bundles. The following example shows how to update a bundle: Use this request to update an existing bundle: ```bash theme={null} curl -X PUT "${BASE_URL}/bundles//" \ -H "X-Api-Key: " \ -H "Authorization: " \ -H "Content-Type: application/json" \ -d '{ "sku": "", "name": { "value": "", "language": "EN" }, "bundleItems": [ { "articleId": , "quantity": 2 }, { "articleId": , "quantity": 1 } ], "grossWeight": { "value": 1.5, "unit": "KG" }, "customsValue": { "value": 29.99, "currencyCode": "EUR" } }' ``` A successful request returns a `200 OK` status code with a `BundleGetDetail` object: ```json theme={null} { "id": , "sellerId": , "sku": "", "name": { "value": "", "language": "EN" }, "bundleItems": [ { "id": , "articleId": , "articleSku": "", "quantity": 2 }, { "id": , "articleId": , "articleSku": "", "quantity": 1 } ], "grossWeight": { "value": 1.5, "unit": "KG" }, "customsValue": { "value": 29.99, "currencyCode": "EUR" }, "created": "", "lastModified": "" } ``` ## Delete a bundle Delete a bundle using the [`DELETE /bundles/{sellerId}/{bundleId} endpoint`](/api-reference/#tag/bundles): Use this request to delete a bundle: ```bash theme={null} curl -X DELETE "${BASE_URL}/bundles//" \ -H "X-Api-Key: " \ -H "Authorization: " ``` A successful deletion returns a `200 OK` status code with a `BundleGetDetail` object. ## Use bundles in orders To use a bundle in a fulfillment order, include the bundle's SKU in the order position's `sku` field when creating an order. The system processes the bundle during the fulfillment process. The following example shows how to use a bundle SKU in an order: Use this request to create an order that includes a bundle: ```bash theme={null} curl -X POST "${BASE_URL}/orders" \ -H "X-Api-Key: " \ -H "Authorization: " \ -H "Content-Type: application/json" \ -d '{ "sellerId": , "orderIdentifier": "", "orderReference": "", "deliveryAddress": { "name": "", "street": "", "city": "", "zip": "", "countryIso2": "" }, "positions": [ { "sku": "", "name": "", "quantity": 1 } ] }' ``` A successful request returns a `200 OK` status code with an `OrderPostResult` object: ```json theme={null} { "status": "OK", "message": "Order created successfully", "orderId": } ``` When you retrieve order details, the `FulfillmentOrderPositionSummary` includes a `bundleSku` field. The `sku` field shows the final SKU selected for fulfillment after considering bundles and maps, as described in the API specification. For complete details on creating orders, see the [Create a Fulfillment Order guide](/docs/quickstart/create-order). ## Where to go next Now that you can manage bundles, continue with these guides: Learn how to create articles that you can include in bundles. Learn how to create orders and use bundles in fulfillment requests. # Manage Products Source: https://api-docs.quivo.co/docs/quivo-guides/manage-products This guide shows you how to retrieve article details, update articles, manage product images, and search your catalog. After creating articles, you can manage them by updating details, uploading images, searching your catalog, and validating product data. Each article has a unique SKU that identifies it. ## 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. * **Seller ID:** Use the [`GET /sellers endpoint`](/api-reference/#tag/sellers) to find it. * **Existing articles:** Create at least one article first. See the [Create Products guide](/docs/quivo-guides/create-products) if you have not created articles 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](/api-reference/environments). ## Retrieve article details Retrieve article details using the article ID or article identifier. Use the [`GET /articles/{sellerId}/{articleId} endpoint`](/api-reference/#tag/articles) to get details by article ID. Use the `articleId` returned when you created the article. Use this request to retrieve the full details of an article by its ID: ```bash theme={null} curl -X GET "${BASE_URL}/articles//" \ -H "X-Api-Key: " \ -H "Authorization: " ``` A successful request returns a `200 OK` status code with the full article details: ```json theme={null} { "articleId": , "sellerId": , "sku": "", "name": { "value": "", "language": "EN" }, "grossWeight": { "value": , "unit": "KG" }, "images": [ { "id": "", "url": { "link": "" }, "source": "" } ], "created": "", "lastModified": "" } ``` Timestamps use the ISO 8601 format YYYY-MM-DDTHH:mm:ssZ in Coordinated Universal Time UTC. You can also retrieve an article by its identifier using the [`GET /articles/{sellerId}/identifier/{articleIdentifier} endpoint`](/api-reference/#tag/articles). ## Search articles Search for articles using the [`GET /articles endpoint`](/api-reference/#tag/articles). This endpoint supports query, sorting, and pagination parameters. Use the `query` parameter to filter results, `sort` to order them, and `pageSize` to limit the number of results. Use this request to search for articles using query parameters: ```bash theme={null} curl -X GET "${BASE_URL}/articles?query=sku:&sort=created:desc&pageSize=50" \ -H "X-Api-Key: " \ -H "Authorization: " ``` A successful request returns a `200 OK` status code with a paginated list of articles: ```json theme={null} { "content": [ { "articleId": , "sku": "", "name": { "value": "", "language": "EN" } } ], "totalElements": 1, "totalPages": 1, "page": 0, "pageSize": 50 } ``` ## Update an article Update an existing article using the [`PUT /articles/{sellerId}/{articleId} endpoint`](/api-reference/#tag/articles). Provide the fields you want to update in the request body. Include all fields you want to keep, not just the ones you are updating. The request body should contain the complete article data. Use this request to update an existing article with new information: ```bash theme={null} curl -X PUT "${BASE_URL}/articles//" \ -H "X-Api-Key: " \ -H "Authorization: " \ -H "Content-Type: application/json" \ -d '{ "sku": "", "name": { "value": "", "language": "EN" }, "grossWeight": { "value": , "unit": "KG" } }' ``` A successful request returns a `200 OK` status code with the updated article details: ```json theme={null} { "articleId": , "sellerId": , "sku": "", "name": { "value": "", "language": "EN" }, "grossWeight": { "value": , "unit": "KG" }, "lastModified": "" } ``` **Validation:** Before updating an article, you can validate your request using the [`POST /articles/{sellerId}/validate endpoint`](/api-reference/#tag/articles). This helps catch errors before making changes. ## Upload product images You can upload product images to articles using the following endpoints: 1. [`POST /articles/{sellerId}/{articleId}/images/upload endpoint`](/api-reference/#tag/articles) - Get an upload URL 2. Upload the image file to the provided URL 3. [`POST /articles/{sellerId}/{articleId}/images endpoint`](/api-reference/#tag/articles) - Store the image information ### Step 1: Get upload link Request an upload link using the [`POST /articles/{sellerId}/{articleId}/images/upload endpoint`](/api-reference/#tag/articles): Use this request to get an upload URL for a product image: ```bash theme={null} curl -X POST "${BASE_URL}/articles///images/upload?mimeType=image/jpeg" \ -H "X-Api-Key: " \ -H "Authorization: " ``` A successful request returns a `200 OK` status code with upload details: ```json theme={null} { "id": "", "uploadUrl": "" } ``` Save the `uploadUrl` and `id` values. You need these for the next step. ### Step 2: Upload the image Upload your image file to the `uploadUrl` using a PUT request: Use this request to upload the image file to the provided upload URL: ```bash theme={null} curl -X PUT "" \ -H "Content-Type: image/jpeg" \ --data-binary "@" ``` Replace `` with the upload URL from Step 1. Replace `` with the path to your image file. Set the `Content-Type` header to match the mime type you specified in Step 1. A successful upload returns a `200 OK` or `204 No Content` status code with no response body. ### Step 3: Store image information After uploading the image, store the image information using the [`POST /articles/{sellerId}/{articleId}/images endpoint`](/api-reference/#tag/articles): Use this request to store the uploaded image information on the article: ```bash theme={null} curl -X POST "${BASE_URL}/articles///images" \ -H "X-Api-Key: " \ -H "Authorization: " \ -H "Content-Type: application/json" \ -d '{ "id": "" }' ``` Use the `id` value from Step 1. This is the only required field for storing the image information. A successful request returns a `200 OK` status code with image information: ```json theme={null} { "id": "", "url": { "link": "" }, "source": "" } ``` ## Delete an article image Delete an article image using the [`DELETE /articles/{sellerId}/{articleId}/images/{uuid} endpoint`](/api-reference/#tag/articles). Use the image `id` from the article details. Use this request to delete an image from an article: ```bash theme={null} curl -X DELETE "${BASE_URL}/articles///images/" \ -H "X-Api-Key: " \ -H "Authorization: " ``` A successful deletion returns a `200 OK` or `204 No Content` status code with no response body. ## Validate article data Validate article data before creating or updating an article. Use the [`POST /articles/{sellerId}/validate endpoint`](/api-reference/#tag/articles) to check your article data: Use this request to validate article data before creating or updating: ```bash theme={null} curl -X POST "${BASE_URL}/articles//validate" \ -H "X-Api-Key: " \ -H "Authorization: " \ -H "Content-Type: application/json" \ -d '{ "sku": "", "name": { "value": "", "language": "EN" }, "grossWeight": { "value": , "unit": "KG" } }' ``` A successful validation returns a `200 OK` status code with the validated article data as an `ArticleGetDetail` object: ```json theme={null} { "articleId": , "sellerId": , "sku": "", "name": { "value": "", "language": "EN" }, "grossWeight": { "value": , "unit": "KG" }, "created": "", "lastModified": "" } ``` The response contains the processed article data if validation passes. If validation fails, the API returns an error response. ## Where to go next Now that you can manage articles, continue with these guides: Learn how to create new articles in your catalog. Send your products to Quivo warehouses to make them available for fulfillment. # Manage Shipments Source: https://api-docs.quivo.co/docs/quivo-guides/manage-shipments This guide shows you how to manually book shipments, retrieve shipping labels, track shipment status, schedule pickups, perform batch operations, and estimate shipment costs. ## 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. * **Seller ID:** Use the [`GET /sellers endpoint`](/api-reference/#tag/sellers) to find it. * **Shipping service group ID:** Use the [`GET /shippingServiceGroups/{sellerId} endpoint`](/api-reference/#tag/shippingServiceGroups) to find available shipping service groups. 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). ## Estimate shipment costs Estimate the price of shipment labels before booking using the [`POST /shipments/estimate endpoint`](/api-reference/#tag/shipments). Use the `requestUUID` field to match the estimate results to your requests. Use this request to estimate shipment costs: ```bash theme={null} curl -X POST "${BASE_URL}/shipments/estimate" \ -H "X-Api-Key: " \ -H "Authorization: " \ -H "Content-Type: application/json" \ -d '{ "estimateRequests": [ { "sellerId": , "shippingServiceGroupId": , "grossWeightKg": , "shipTo": { "name": "", "street": "", "city": "", "zip": "", "countryIso2": "" }, "requestUUID": "" } ] }' ``` A successful request returns a `200 OK` status code with an `EstimateResponse` object: ```json theme={null} { "estimateResults": [ { "requestUUID": "", "success": true, "currency": { "currencyCode": "", "symbol": "" }, "amountLabel": , "amountInsurance": } ] } ``` The `amountLabel` field shows the cost for the shipping label. The `amountInsurance` field shows the cost for insurance, if applicable. Use the `requestUUID` to match each result to the corresponding estimate request. ## Book a shipment Book a shipment label using the [`POST /shipments/book endpoint`](/api-reference/#tag/shipments). You must provide the seller ID, shipping service group ID, gross weight, and delivery address. The `shipFrom` address is optional. The following example shows how to book a shipment: Use this request to book a shipment label: ```bash theme={null} curl -X POST "${BASE_URL}/shipments/book" \ -H "X-Api-Key: " \ -H "Authorization: " \ -H "Content-Type: application/json" \ -d '{ "sellerId": , "shippingServiceGroupId": , "grossWeightKg": , "shipTo": { "name": "", "company": "", "email": "", "phone": "", "street": "", "street2": "", "city": "", "zip": "", "state": "", "countryIso2": "" }, "shipFrom": { "name": "", "street": "", "city": "", "zip": "", "countryIso2": "" }, "reference": "", "requestUUID": "", "lengthM": , "widthM": , "heightM": , "trackingEnabled": true }' ``` A successful request returns a `200 OK` status code with a `BookResponse` object: ```json theme={null} { "status": "OK", "message": "", "bookedShipmentId": , "trackingNumber": "", "trackingLink": "", "labelUrls": [ "", "" ], "documentUrls": [ "" ] } ``` Save the `bookedShipmentId` from the response. You need this ID to retrieve shipment details, labels, or cancel the shipment later. The `labelUrls` array contains URLs where you can download the shipping labels. The `documentUrls` array contains URLs for additional documents such as export documents, if applicable. ### Request fields The following table describes the key fields you can include when booking a shipment. The `shipTo` and `shipFrom` objects use the `ShipmentDeliveryAddress` schema. For complete field definitions, see the [API Reference](/api-reference/#tag/shipments): | Field | Type | Description | | --------------------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `sellerId` | Integer | The seller who is booking this shipment. | | `shippingServiceGroupId` | Integer | Shipping service group from which to load the shipping services to use. | | `grossWeightKg` | Number | The total weight (kilograms) of the shipment including packaging. Must be greater than 0. | | `shipTo` | Object | Delivery address object. See address fields below. | | `shipFrom` | Object | Sender address object. Optional. | | `reference` | String | A human readable reference for the request. Optional. If not included, the system generates a random reference. | | `requestUUID` | String | A unique identifier for the request. Used for tracing and to prevent duplicate shipment bookings. Optional. If not included, the system generates a random requestUUID. | | `lengthM` | Number | Optional length in meters of the shipment. Must be greater than 0. | | `widthM` | Number | Optional width in meters of the shipment. Must be greater than 0. | | `heightM` | Number | Optional height in meters of the shipment. Must be greater than 0. | | `trackingEnabled` | Boolean | Optional value setting whether to turn on/off tracking for shipment. Additional charges apply when set to true. | | `includeReturnLabel` | Boolean | Optional value setting whether to include a return label along with the main label. | | `shipmentDate` | String (date) | Optional future or today's date when the carrier picks up the shipment. If not specified, defaults to today. | | `termsOfTrade` | String | Optional terms of trade. If not specified, defaults to `DAP`. Valid values: `DAP`, `DDP`. | | `customsPositions` | Array | Optional customs positions for the shipment. Only required if shipping to countries that require export documents. | | `invoiceNumber` | String | The invoice number for customs declaration. | | `invoiceDate` | String (date) | The invoice date for customs declaration. | | `transportInsuranceAmount` | Number | Optional amount to insure when booking the shipment. Setting this field to a non-null value books additional insurance. | | `shipTo.name` / `shipFrom.name` | String | Name of the recipient. Usually the first and last name. You must provide either `name` or `company`. | | `shipTo.company` / `shipFrom.company` | String | Name of the company. You must provide either `name` or `company`. | | `shipTo.email` / `shipFrom.email` | String | Email address of the recipient. | | `shipTo.phone` / `shipFrom.phone` | String | Phone number of the recipient. | | `shipTo.street` / `shipFrom.street` | String | Street address (Address Line 1). Optional only when you provide latitude and longitude coordinates. | | `shipTo.street2` / `shipFrom.street2` | String | Address Line 2. Optional. | | `shipTo.city` / `shipFrom.city` | String | City. Optional only when you provide latitude and longitude coordinates. | | `shipTo.zip` / `shipFrom.zip` | String | ZIP or postal code. Optional for some countries, but required for most. Optional when you provide latitude and longitude coordinates. | | `shipTo.state` / `shipFrom.state` | String | State or province. Required for some countries (for example, United States). | | `shipTo.countryIso2` / `shipFrom.countryIso2` | String | Two-letter ISO country code. Optional only when you provide latitude and longitude coordinates. | | `shipTo.latitude` / `shipFrom.latitude` | Number | Latitude coordinate for the address. Optional, used for some carriers to optimize the delivery process. | | `shipTo.longitude` / `shipFrom.longitude` | Number | Longitude coordinate for the address. Optional, used for some carriers to optimize the delivery process. | ## Retrieve shipment details Retrieve shipment details using the booked shipment ID. Use the [`GET /shipments/{bookedShipmentId} endpoint`](/api-reference/#tag/shipments) to get details by shipment ID: Use this request to retrieve the full details of a booked shipment by its ID: ```bash theme={null} curl -X GET "${BASE_URL}/shipments/" \ -H "X-Api-Key: " \ -H "Authorization: " ``` A successful request returns a `200 OK` status code with the full shipment details as a `BookedShipmentGet` object, including tracking information, documents, and all shipment metadata. ## Retrieve shipping labels You can retrieve shipping labels in two ways: 1. **From the booking response:** The `labelUrls` array in the `BookResponse` contains URLs where you can download the shipping labels. 2. **From shipment details:** Retrieve shipment details using the `GET /shipments/{bookedShipmentId}` endpoint. The response includes a `documents` array with document information. Use the `shipmentDocumentId` from each document to retrieve the download URL using the `GET /shipments/documentLink` endpoint. To get a download link for a specific document, use the [`GET /shipments/documentLink endpoint`](/api-reference/#tag/shipments): Use this request to get a download link for a shipment document: ```bash theme={null} curl -X GET "${BASE_URL}/shipments/documentLink?shipmentDocumentId=" \ -H "X-Api-Key: " \ -H "Authorization: " ``` A successful request returns a `200 OK` status code with a `Link` object containing the download URL: ```json theme={null} { "link": "" } ``` ## Track shipment status Search for booked shipments using the [`GET /shipments endpoint`](/api-reference/#tag/shipments). This endpoint supports query, sorting, and pagination parameters. Use the `query` parameter to filter results, `sort` to order them, and `pageSize` to limit the number of results. Use this request to search for shipments using query parameters: ```bash theme={null} curl -X GET "${BASE_URL}/shipments?query=trackingNumber:&sort=created:desc&pageSize=50" \ -H "X-Api-Key: " \ -H "Authorization: " ``` A successful request returns a `200 OK` status code with an array of `BookedShipmentSummary` objects: ```json theme={null} [ { "bookedShipmentId": , "trackingNumber": "", "trackingLink": "", "carrierSlug": "", "reference": "", "created": "" } ] ``` For detailed tracking information, retrieve the full shipment details using the `GET /shipments/{bookedShipmentId}` endpoint. The response includes a `trackingDetails` array with tracking information. ## Schedule a pickup Book a pickup for booked shipments using the [`POST /shipments/pickups endpoint`](/api-reference/#tag/shipments). You must provide the seller ID, shipping service group ID, parcel count, and pickup date. The `pickupFrom` address is optional. Use this request to book a pickup: ```bash theme={null} curl -X POST "${BASE_URL}/shipments/pickups" \ -H "X-Api-Key: " \ -H "Authorization: " \ -H "Content-Type: application/json" \ -d '{ "sellerId": , "shippingServiceGroupId": , "parcelCount": , "pickupDate": "", "pickupFrom": { "name": "", "street": "", "city": "", "zip": "", "countryIso2": "", "phone": "" } }' ``` A successful request returns a `200 OK` status code with an empty response body. ### Search for booked pickups Search for booked pickups using the [`GET /shipments/pickups endpoint`](/api-reference/#tag/shipments). Use the `query` parameter to filter results by pickup date, seller, or other criteria. Use this request to search for booked pickups: ```bash theme={null} curl -X GET "${BASE_URL}/shipments/pickups?query=pickupDate:&sort=created:desc&pageSize=50" \ -H "X-Api-Key: " \ -H "Authorization: " ``` A successful request returns a `200 OK` status code with an array of `BookedPickupGet` objects: ```json theme={null} [ { "id": , "sellerId": , "shippingServiceGroupId": , "parcelCount": , "pickupDate": "", "created": "" } ] ``` ## Batch operations Book a batch of shipment labels using the [`POST /shipments/bookBatchAsync endpoint`](/api-reference/#tag/shipments). This endpoint processes multiple shipment bookings asynchronously and sends the results via email. The `lineNumber` field represents the line number in the original batch file. Once the batch operation completes, the system sends a ZIP file with labels and export documents to the specified email address. Use this request to book a batch of shipments: ```bash theme={null} curl -X POST "${BASE_URL}/shipments/bookBatchAsync" \ -H "X-Api-Key: " \ -H "Authorization: " \ -H "Content-Type: application/json" \ -d '{ "reference": "", "email": "", "bookRequests": [ { "lineNumber": , "sellerId": , "shippingServiceGroupId": , "grossWeightKg": , "shipTo": { "name": "", "street": "", "city": "", "zip": "", "countryIso2": "" }, "reference": "" }, { "lineNumber": , "sellerId": , "shippingServiceGroupId": , "grossWeightKg": , "shipTo": { "name": "", "street": "", "city": "", "zip": "", "countryIso2": "" }, "reference": "" } ] }' ``` A successful request returns a `200 OK` status code with an empty response body. The operation runs asynchronously, and the system sends results to the specified email address when complete. ## Cancel a shipment Cancel a booked shipment using the [`DELETE /shipments/{bookedShipmentId} endpoint`](/api-reference/#tag/shipments): Use this request to cancel a booked shipment: ```bash theme={null} curl -X DELETE "${BASE_URL}/shipments/" \ -H "X-Api-Key: " \ -H "Authorization: " ``` A successful cancellation returns a `200 OK` status code with an empty response body. ## Where to go next Now that you can manage shipments, continue with these guides: Monitor order status and retrieve tracking information when shipping occurs. Generate return labels and track returned items when customers need to send products back. # Monitor Inventory Source: https://api-docs.quivo.co/docs/quivo-guides/monitor-inventory This guide shows you how to check stock levels, view inventory by warehouse, and track item movements using the Items API. After you send inventory to a Quivo warehouse and the inbound completes, your products are available as items in the warehouse. Understanding the distinction between articles and items is important: * **Article:** A product definition in your catalog created using the Articles API * **Item:** A physical unit of inventory stored in a warehouse, created from articles after you send inventory to a warehouse and the inbound completes. An article can have many items across different warehouses, with each item representing physical stock at a specific warehouse location. For detailed definitions of these terms, see the [Logistics Glossary](/docs/introduction/logistics-glossary). This guide teaches you how to check current stock levels, view item history, and refresh inventory data when needed. ## 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. * **Seller ID:** Use the [`GET /sellers endpoint`](/api-reference/#tag/sellers) to find it. * **Warehouse ID:** Use the [`GET /warehouses endpoint`](/api-reference/#tag/warehouses) to list available warehouses. * **Completed inbound:** You should have sent inventory and the inbound status should be `COMPLETED`. See the [Send Inventory guide](/docs/quickstart/send-inventory) if you have not sent inventory yet. * **Articles created:** Products must exist as articles. See the [Create Products guide](/docs/quivo-guides/create-products) if you have not created articles 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](/api-reference/environments). ## Check stock levels by warehouse To check stock levels for all items in a specific warehouse, use the [`GET /items/{warehouseId}/{sellerId} endpoint`](/api-reference/#tag/items). This returns a list of all items in the warehouse with their current inventory levels. Replace the placeholders with your actual warehouse ID and seller ID. Use this request to list all items and their stock levels in a specific warehouse. ```bash theme={null} curl -X GET "${BASE_URL}/items//" \ -H "X-Api-Key: " \ -H "Authorization: " ``` A successful request returns a `200 OK` status code with an array of `ItemInfo` objects: ```json theme={null} [ { "itemId": , "articleId": , "sku": "", "sellerSku": "", "warehouseSku": "", "name": "", "quantity": , "inventory": , "inbound": , "reserved": , "warehouseId": , "articleName": { "value": "", "language": "EN" }, "articleType": "PRODUCT" } ] ``` The response includes key inventory fields: * `quantity`: Current available quantity ready for fulfillment * `inventory`: Total inventory quantity in the warehouse * `inbound`: Quantity that Quivo is currently processing from inbound shipments * `reserved`: Quantity reserved for pending orders ### Filter and search items You can use query parameters to filter and search items: * **`query`**: Search query string to filter results across multiple fields, for example SKU or name * **`sort`**: Sort criteria, for example `quantity:desc` to sort by quantity descending * **`page`**: Page number for pagination * **`pageSize`**: Number of items per page **Search by SKU:** ```bash theme={null} curl -X GET "${BASE_URL}/items//?query=" \ -H "X-Api-Key: " \ -H "Authorization: " ``` **Sort by quantity:** ```bash theme={null} curl -X GET "${BASE_URL}/items//?sort=quantity:desc" \ -H "X-Api-Key: " \ -H "Authorization: " ``` ## Get item details To get detailed information about a specific item, use the [`GET /items/{itemId} endpoint`](/api-reference/#tag/items). Use the `itemId` from the item list response. Use this request to retrieve detailed information for a single item. ```bash theme={null} curl -X GET "${BASE_URL}/items/" \ -H "X-Api-Key: " \ -H "Authorization: " ``` A successful request returns a `200 OK` status code with an `ItemInfo` object containing complete item details: ```json theme={null} { "itemId": , "articleId": , "sku": "", "sellerSku": "", "warehouseSku": "", "name": "", "quantity": , "inventory": , "inbound": , "reserved": , "warehouseId": , "barcode": "", "countryOfOrigin": "", "weight": , "articleName": { "value": "", "language": "EN" }, "articleType": "PRODUCT", "itemInventories": [] } ``` ## View item movements and history To view the movement history for a specific item, use the [`GET /items/{itemId}/movements endpoint`](/api-reference/#tag/items). This shows all movements (inbound, outbound, adjustments) for the item. Use the `itemId` from the item details. Use this request to retrieve movement history for a specific item. ```bash theme={null} curl -X GET "${BASE_URL}/items//movements" \ -H "X-Api-Key: " \ -H "Authorization: " ``` A successful request returns a `200 OK` status code with an `ItemMovements` object containing movement history: ```json theme={null} { "warehouseName": "", "itemMovements": [ { "movementDate": "", "warehouseIdentifier": "", "reference": "", "adjustmentQuantity": } ] } ``` The movement history shows inventory changes over time. Dates use the ISO 8601 format YYYY-MM-DD, and timestamps use YYYY-MM-DDTHH:mm:ssZ in Coordinated Universal Time UTC. ### Filter movements by date range You can filter movements by date range using the `movementFrom` and `movementTo` query parameters: ```bash theme={null} curl -X GET "${BASE_URL}/items//movements?movementFrom=2025-01-01T00:00:00Z&movementTo=2025-01-31T23:59:59Z" \ -H "X-Api-Key: " \ -H "Authorization: " ``` ## View item history by warehouse To view item history for all items in a warehouse, use the [`GET /items/itemHistories/{warehouseId}/{sellerId} endpoint`](/api-reference/#tag/items). This provides a comprehensive history of all item movements in the warehouse. You can use query parameters like `query` and `sort` to filter and sort the results. Use this request to retrieve movement history for all items in a warehouse: ```bash theme={null} curl -X GET "${BASE_URL}/items/itemHistories//" \ -H "X-Api-Key: " \ -H "Authorization: " ``` A successful request returns a `200 OK` status code with an array of `ItemHistorySummary` objects: ```json theme={null} [ { "warehouseId": , "sellerId": , "itemId": , "warehouseSku": "", "sellerSku": "", "name": "", "barcode": "", "inventory": , "reserved": , "eventDate": "", "itemHistoryInventories": [ { "quantity": , "lot": "", "expiration": "", "locationBlocked": false } ] } ] ``` Each object in the array represents an item history entry with inventory details and movement information. ## Refresh inventory data If you notice discrepancies between your records and the warehouse inventory, you can trigger a refresh operation to sync inventory data with the warehouse system. ### Refresh a specific item To refresh a specific item, use the [`POST /items/{itemId}/refresh endpoint`](/api-reference/#tag/items). This operation syncs the item's inventory data with the warehouse system. Use this request to refresh inventory data for a specific item. ```bash theme={null} curl -X POST "${BASE_URL}/items//refresh" \ -H "X-Api-Key: " \ -H "Authorization: " ``` A successful request returns a `200 OK` status code with the updated `ItemInfo` object: ```json theme={null} { "itemId": , "quantity": , "inventory": , "inbound": , "reserved": } ``` ### Refresh all seller items To refresh inventory for all items belonging to a seller, use the [`POST /items/seller/{sellerId}/refresh endpoint`](/api-reference/#tag/items). This operation syncs all items for your seller account with the warehouse system. Use this request to refresh inventory data for all items for a seller. ```bash theme={null} curl -X POST "${BASE_URL}/items/seller//refresh" \ -H "X-Api-Key: " \ -H "Authorization: " ``` A successful request returns a `200 OK` status code with no response body. The refresh operation is processed asynchronously. ## Where to go next Now that you can monitor inventory, continue with these guides: Create orders to fulfill customer purchases. Use inventory levels to ensure products are available before creating orders. Monitor order status and retrieve tracking information when Quivo ships orders from the warehouse. # Use Queries Source: https://api-docs.quivo.co/docs/quivo-guides/using-queries This guide explains how to use query parameters to filter and search data across different endpoints in the Quivo API. Many endpoints support a `query` parameter that allows you to filter results using specific syntax. ## Overview The Quivo API provides query parameters on many endpoints that let you filter and search data efficiently. The `query` parameter supports specific syntax for filtering across multiple fields, allowing you to build complex search queries without making multiple API calls. For information about pagination and sorting, which work together with query parameters, see the [Pagination & Idempotency](/api-reference/pagination-idempotency) reference. ## 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. * **API key:** Your static API key provided by Quivo. * **Understanding of endpoint structure:** Familiarity with the endpoints you want to query. See the [API Reference](/api-reference) for endpoint documentation. 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). ## Understanding the Query Parameter The `query` parameter is available on many GET endpoints in the Quivo API. It accepts a search query string that filters results using Elasticsearch query syntax. **Key characteristics:** * The query parameter uses **Elasticsearch query syntax directly** (queries are executed directly against Elasticsearch) * All fields stored in Elasticsearch can be used in queries * You can combine query parameters with sorting and pagination parameters * Supports logical operators (AND, OR, NOT), comparisons, and functions (for example, `exists`) The Quivo API uses Elasticsearch internally to process queries. The `/ping` endpoint confirms this by checking both database and Elasticsearch connectivity. The `query` parameter executes queries directly against Elasticsearch, so you can use standard Elasticsearch query syntax. ## Finding Query Support Not all endpoints support the `query` parameter. To determine if an endpoint supports querying, see the detailed endpoint documentation in the [API Reference](/api-reference/#tag) section ## Common Endpoints with Query Support The following endpoints are known to support the `query` parameter: * **Articles:** `GET /articles` - Search articles by various criteria * **Orders:** `GET /orders` - Filter orders by status, date, or other fields * **Shipments:** `GET /shipments` - Search shipments by tracking number, status, or other criteria * **Items:** `GET /items` - Filter inventory items by warehouse, SKU, or other fields * **Inbounds:** `GET /inbounds` - Search inbound shipments by status or other criteria * **Bundles:** `GET /bundles` - Filter product bundles by SKU or other criteria ## Query Syntax The `query` parameter uses Elasticsearch query syntax. Here are some common patterns: ### Basic Field Matching Filter by a specific field value: ``` fieldName: "value" ``` ### Logical Operators Combine multiple conditions using `AND`, `OR`, and `NOT`: ``` (field1: "value1" AND field2: "value2") (field1: "value1" OR field2: "value2") NOT field1: "value1" ``` ### Comparisons Use comparison operators for numeric and date fields: ``` fieldName: value # Greater than fieldName: <=value # Less than or equal fieldName: >=value # Greater than or equal ``` ### Existence Checks Check if a field exists: ``` exists: fieldName ``` ## Examples ### Example: Filtering Orders by Status and Date Filter orders with status "PROCESSING" created before a specific date: ```bash theme={null} curl -X GET "${BASE_URL}/orders?query=(orderStatus: \"PROCESSING\" AND created:<2026-01-01)" \ -H "X-Api-Key: " \ -H "Authorization: " ``` ### Example: Filtering Orders with Shipments Filter orders that have shipments with tracking numbers: ```bash theme={null} curl -X GET "${BASE_URL}/orders?query=(orderStatus: \"PROCESSING\" AND (exists: shipments.trackingNumber))" \ -H "X-Api-Key: " \ -H "Authorization: " ``` ### Example: Filtering Shipments by Tracking Number Filter shipments by tracking number: ```bash theme={null} curl -X GET "${BASE_URL}/shipments?query=trackingNumber:&sort=created:desc&pageSize=50" \ -H "X-Api-Key: " \ -H "Authorization: " ``` All fields stored in Elasticsearch can be used in queries. The exact fields available depend on the endpoint and what data is indexed in Elasticsearch. If you need a complete list of queryable fields for a specific endpoint, contact Quivo support. ## Combining Query with Other Parameters You can combine the `query` parameter with other parameters for more precise results: * **Sorting:** Use the `sort` parameter to order results (for example, `sort=created:desc`) * **Pagination:** Use `page`, `pageSize`, and `searchAfter` for pagination * **Multiple filters:** The query syntax may support combining multiple filters **Example combining query, sort, and pagination:** ```bash theme={null} curl -X GET "${BASE_URL}/articles?query=&sort=created:desc&page=1&pageSize=20" \ -H "X-Api-Key: " \ -H "Authorization: " ``` ## Where to go next Now that you understand how to use query parameters, continue with these guides: Learn how to search and filter products using query parameters. See examples of querying shipments by tracking number and other criteria. # Create Subscriptions Source: https://api-docs.quivo.co/docs/webhooks/create-subscriptions This guide explains what subscriptions are and shows you how to create them to receive real-time event notifications from Quivo. Instead of polling for status changes, subscriptions allow Quivo to push data to your server via an HTTP POST request whenever a specific event occurs. ## What are subscriptions? Subscriptions are webhook configurations that notify your server when specific events happen in the Quivo system. When you create a subscription, you specify: * **Entity type**: The type of resource you want to monitor (for example, orders or shipments) * **Endpoint URL**: The HTTPS endpoint on your server that receives the notification data When an event occurs for the subscribed entity type, Quivo sends a POST request to your endpoint with event details. Your endpoint must return a `200 OK` response to confirm receipt of the notification. **Important:** Your webhook endpoint must return a `200 OK` response to confirm receipt of the notification. If your endpoint does not return `200 OK`, Quivo may retry the webhook or mark it as failed. ## 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. * **API key:** Your static API key provided by Quivo. * **Seller ID:** Use the [`GET /sellers endpoint`](/api-reference/#tag/sellers) to find it. * **Public URL:** A secure HTTPS endpoint on your server capable of receiving JSON POST requests. 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). ## Supported Entity Types The following table lists the supported entity types and the events that trigger notifications: | Entity | Triggers On | | ----------- | ----------------------------------------------------------------------------- | | `ORDERS` | Order creation, status changes (for example, to `PROCESSING`). | | `SHIPMENTS` | Shipment creation, tracking updates (for example, `IN_TRANSIT`, `DELIVERED`). | | `INBOUNDS` | Inbound shipment status changes. | | `RETURNS` | When a return is created or received at the warehouse. | | `INVOICES` | Invoice creation and updates. | ## Create a subscription Create a subscription when you want to start receiving real-time notifications about specific events. Use the [`POST /subscriptions endpoint`](/api-reference/#tag/subscriptions) to create a new subscription. You need to construct a JSON payload containing your `sellerId`, the entity type, and the endpoint configuration. The following example shows how to subscribe to `SHIPMENTS` updates: Use this request to create a webhook subscription for a specific entity. ```bash theme={null} curl -X POST "${BASE_URL}/subscriptions" \ -H "X-Api-Key: " \ -H "Authorization: " \ -H "Content-Type: application/json" \ -d '{ "sellerId": , "entity": "SHIPMENTS", "endpoint": { "type": "WEBHOOK", "url": "" } }' ``` A successful request returns a `200 OK` status code. The API returns the created subscription object with a unique `uuid` (universally unique identifier). Save this UUID. You need it to delete the subscription later. ```json theme={null} { "uuid": "", "sellerId": , "entity": "SHIPMENTS", "endpoint": { "type": "WEBHOOK", "url": "" } } ``` ### Request body fields The request body must include the following fields: * **`sellerId`** (required): The unique integer ID for your merchant account. * **`entity`** (required): The entity type you want to subscribe to. Must be one of: `ORDERS`, `SHIPMENTS`, `INBOUNDS`, `RETURNS`, or `INVOICES`. * **`endpoint`** (required): An object containing: * **`type`**: Must be `"WEBHOOK"`. * **`url`**: The HTTPS URL of your webhook endpoint that receives notifications. ## Where to go next Now that you can create subscriptions, continue with these guides: Learn how to list and delete your existing subscriptions. Configure and manage event subscriptions via the API. # Manage Subscriptions Source: https://api-docs.quivo.co/docs/webhooks/manage-subscriptions This guide shows you how to list and delete webhook subscriptions. Use these operations to review your active subscriptions or remove subscriptions you no longer need. ## 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. * **API key:** Your static API key provided by Quivo. * **Subscription UUID:** The UUID of the subscription you want to delete. You can obtain this by listing your subscriptions or from the response when you created the subscription. 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). ## List active subscriptions List subscriptions when you need to review all webhooks currently configured for your account or find a subscription UUID. Use the [`GET /subscriptions endpoint`](/api-reference/#tag/subscriptions) to retrieve all active subscriptions. Use this request to list all active webhook subscriptions for your account. ```bash theme={null} curl -X GET "${BASE_URL}/subscriptions" \ -H "X-Api-Key: " \ -H "Authorization: " ``` A successful request returns a `200 OK` status code. The response returns an array of all active subscriptions: ```json theme={null} [ { "uuid": "", "sellerId": , "entity": "SHIPMENTS", "endpoint": { "type": "WEBHOOK", "url": "" } }, { "uuid": "", "sellerId": , "entity": "ORDERS", "endpoint": { "type": "WEBHOOK", "url": "" } } ] ``` Each object in the array represents an active subscription with its UUID, seller ID, entity type, and endpoint configuration. ## Get a specific subscription To retrieve details for a specific subscription, use the [`GET /subscriptions/{uuid} endpoint`](/api-reference/#tag/subscriptions) with the subscription UUID. Replace `` with the UUID of the subscription you want to retrieve. Use this request to retrieve details for a specific subscription by its UUID. ```bash theme={null} curl -X GET "${BASE_URL}/subscriptions/" \ -H "X-Api-Key: " \ -H "Authorization: " ``` A successful request returns a `200 OK` status code with the subscription details: ```json theme={null} { "uuid": "", "sellerId": , "entity": "SHIPMENTS", "endpoint": { "type": "WEBHOOK", "url": "" } } ``` ## Delete a subscription Delete a subscription when you no longer want to receive notifications for a specific event. Use the subscription UUID obtained when you created it or listed subscriptions. Delete it via the [`DELETE /subscriptions/{uuid} endpoint`](/api-reference/#tag/subscriptions). Replace `` with the UUID of the subscription you want to delete. Use this request to delete a webhook subscription by its UUID. ```bash theme={null} curl -X DELETE "${BASE_URL}/subscriptions/" \ -H "X-Api-Key: " \ -H "Authorization: " ``` A successful deletion returns a `200 OK` or `204 No Content` status code with no response body: ```http theme={null} HTTP/1.1 204 No Content ``` ## Where to go next Now that you can manage subscriptions, continue with these guides: Learn what subscriptions are and how to create them. Configure and manage event subscriptions via the API. # Webhook Response Examples Source: https://api-docs.quivo.co/docs/webhooks/webhooks-responses This reference documents webhook payloads and response examples for webhook notifications sent by the Quivo API. When you create a subscription for an entity type, Quivo sends HTTP POST requests to your configured endpoint when events occur for that entity. ## Overview When you subscribe to entity events using the [Create Subscriptions](/docs/webhooks/create-subscriptions) guide, Quivo sends webhook notifications to your endpoint when specific events occur. Your endpoint receives these notifications as HTTP POST requests with JSON payloads containing event data. ## Supported Entity Types You can subscribe to webhook notifications for the following entity types: | Entity Type | Description | Events Triggered | | ----------- | ----------------------- | ---------------------------------------------------------------------------- | | `ORDERS` | Order events | Order creation, status changes (for example, to `PROCESSING`) | | `SHIPMENTS` | Shipment events | Shipment creation, tracking updates (for example, `IN_TRANSIT`, `DELIVERED`) | | `INBOUNDS` | Inbound shipment events | Inbound shipment status changes | | `RETURNS` | Return events | When a return is created or received at the warehouse | | `INVOICES` | Invoice events | Invoice creation and updates | ## Webhook Request Format When an event occurs for a subscribed entity type, Quivo sends an HTTP POST request to your configured endpoint: * **Method:** `POST` * **Content-Type:** `application/json` * **Body:** JSON payload containing event data Your endpoint must return a `200 OK` HTTP status code to confirm receipt of the notification. Your webhook endpoint must return a `200 OK` response to confirm receipt of the notification. If your endpoint does not return `200 OK`, Quivo may retry the webhook or mark it as failed. ## Webhook Payload Structure Webhook payloads follow a consistent structure across all entity types. The payload contains an `events` array with a single event object. Each event includes metadata about the entity that changed, but **does not include the complete entity object**. ### Payload Format ```json theme={null} { "events": [ { "id": 123, "entity": "SHIPMENTS", "lastModified": "2019-12-15T14:48:12Z", "version": 2 } ] } ``` **Event fields:** * `id` (integer): The ID of the entity that changed * `entity` (string): The entity type (for example, `ORDERS`, `SHIPMENTS`, `INBOUNDS`, `RETURNS`, `INVOICES`) * `lastModified` (string): ISO 8601 timestamp of when the entity was last modified * `version` (integer): The version number of the entity The webhook payload contains only the entity ID and metadata, not the complete entity object. To retrieve the full entity data, make a GET request to the appropriate endpoint using the `id` from the webhook payload. ## Payload Examples by Entity Type ### SHIPMENTS ```json theme={null} { "events": [ { "id": 123, "entity": "SHIPMENTS", "lastModified": "2019-12-15T14:48:12Z", "version": 2 } ] } ``` ### ORDERS ```json theme={null} { "events": [ { "id": 1923, "entity": "ORDERS", "lastModified": "2021-12-15T14:48:12Z", "version": 5 } ] } ``` ### INBOUNDS ```json theme={null} { "events": [ { "id": 1, "entity": "INBOUNDS", "lastModified": "2019-12-15T14:48:12Z", "version": 100 } ] } ``` ### RETURNS ```json theme={null} { "events": [ { "id": 1, "entity": "RETURNS", "lastModified": "2021-12-15T14:48:12Z", "version": 5 } ] } ``` ### INVOICES The payload structure for `INVOICES` follows the same format as other entity types. ## Webhook Headers For `EndpointWebhook` type subscriptions: * **Content-Type:** `application/json` * **No signature or signing:** EndpointWebhook requests are unauthorized API POST requests (no authentication headers or signatures are included) The Quivo API also supports AWS SNS/SQS events. For SNS events, the payload includes a `subject` field (for example, "UPDATE - ORDERS #9461772"). SQS events do not include a `subject` field. ## Retrieving Full Entity Data Since webhook payloads contain only the entity ID and metadata, you will need to retrieve the full entity data using the API: 1. Extract the `id` and `entity` from the webhook payload 2. Make a GET request to the appropriate endpoint: * For `ORDERS`: `GET /orders/{id}` * For `SHIPMENTS`: `GET /shipments/{id}` * For `INBOUNDS`: `GET /inbounds/{id}` * For `RETURNS`: `GET /returns/{id}` * For `INVOICES`: `GET /invoices/{id}` **Example:** ```bash theme={null} # Receive webhook with id: 1923, entity: "ORDERS" # Then retrieve full order data: curl -X GET "${BASE_URL}/orders/1923" \ -H "X-Api-Key: " \ -H "Authorization: " ``` ## Where to go next Now that you understand webhook notifications, continue with these guides: Learn how to create webhook subscriptions to receive event notifications. Learn how to list and delete your webhook subscriptions. # QUIVO Docs Source: https://api-docs.quivo.co/index The official documentation for QUIVO.

Dive into our docs and learn how to integrate with the Quivo logistics platform and automate your fulfillment operations.

Overview

Understand what is the Quivo logistics platform.

Quickstart

Learn how to send inventory and create your first order.

API Reference

Explore the complete API Reference of the Quivo API