--- agentTools: projectIndex: https://quiver.readme.io/llms.txt --- # /returns/{taskId} # OpenAPI definition ```json { "openapi": "3.0.0", "info": { "title": "Task", "description": "Create and manage deliveries and store collections. For a collection, use the location's merchantLocationId and the QUIV_COL rate returned by /quotes. Store collection is stock-only in v1; select a location that has collection enabled and current stock for the full basket.", "version": "1.0" }, "tags": [ { "name": "TaskService" } ], "paths": { "/returns/{taskId}": { "get": { "operationId": "TaskService_GetReturn", "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/taskTask" } } } }, "default": { "description": "An unexpected error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/rpcStatus" } } } } }, "parameters": [ { "name": "taskId", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "tags": [ "TaskService" ] } } }, "servers": [ { "url": "https://api.quiver.london/task" } ], "components": { "schemas": { "fulfilmentFulfilmentType": { "type": "string", "enum": [ "MERCHANT", "PROPRIETARY" ] }, "fulfilmentLineItem": { "type": "object", "properties": { "quantity": { "type": "integer", "format": "int32" }, "product": { "$ref": "#/components/schemas/fulfilmentProduct" } } }, "fulfilmentProduct": { "type": "object", "properties": { "productId": { "type": "integer", "format": "int32" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "merchantId": { "type": "integer", "format": "int32" }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "excluded": { "type": "boolean" }, "ephemeral": { "type": "boolean" }, "sku": { "type": "string" }, "barcode": { "type": "string" }, "price": { "type": "number", "format": "double" }, "weight": { "type": "number", "format": "double" }, "dimensions": { "$ref": "#/components/schemas/sharedDimensions" }, "merchantProductId": { "type": "string" }, "merchantInventoryItemId": { "type": "string" }, "inventoryLevel": { "type": "integer", "format": "int32" }, "weightSource": { "type": "string", "description": "Where the measurements came from: PLATFORM (the merchant's store),\nMERCHANT (typed in by hand) or ESTIMATED (worked out by us when neither\nsupplied one). Absent when the measurement has never been set." }, "dimensionsSource": { "type": "string" }, "shopifyStatus": { "type": "string", "description": "Shopify's current listing state, for example ACTIVE, DRAFT, ARCHIVED or\nUNLISTED. It is absent for non-Shopify merchants and products imported\nbefore the status field was introduced." }, "shopifyBundle": { "type": "boolean", "description": "True when Shopify marks this specific variant as requiring components.\nThis is intentionally separate from a Quiver stock configuration: a native\nbundle can still need an ops decision before it has stock mapped here." }, "shopifyBundleConfigured": { "type": "boolean", "description": "Set for native Shopify bundles after Quiver has resolved every Shopify\ncomponent to physical stock. False means the recipe is known but needs an\ninventory mapping; absent means this is not a Shopify bundle." }, "shopifyBundleComponents": { "type": "array", "items": { "$ref": "#/components/schemas/fulfilmentShopifyBundleComponent" }, "description": "The recipe supplied by Shopify for a native bundle, enriched with each\ncomponent's current Quiver stock mapping. It is informational: Shopify\nremains the source of truth for the recipe itself." } } }, "fulfilmentShopifyBundleComponent": { "type": "object", "properties": { "productId": { "type": "integer", "format": "int32", "description": "Quiver's product record for the component. It is absent when Shopify's\ncomponent no longer resolves to a Quiver product." }, "merchantProductId": { "type": "string" }, "name": { "type": "string" }, "quantity": { "type": "integer", "format": "int32" }, "inventoryItemConfigs": { "type": "array", "items": { "$ref": "#/components/schemas/fulfilmentShopifyBundleComponentInventoryItem" } } } }, "fulfilmentShopifyBundleComponentInventoryItem": { "type": "object", "properties": { "inventoryItemId": { "type": "integer", "format": "int32" }, "multiplier": { "type": "integer", "format": "int32" } } }, "protobufAny": { "type": "object", "properties": { "@type": { "type": "string" } }, "additionalProperties": {} }, "rpcStatus": { "type": "object", "properties": { "code": { "type": "integer", "format": "int32" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/protobufAny" } } } }, "sharedAddress": { "type": "object", "properties": { "addressId": { "type": "integer", "format": "int32" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "city": { "type": "string" }, "postcode": { "type": "string" }, "country": { "type": "string" }, "company": { "type": "string" }, "latitude": { "type": "number", "format": "double" }, "longitude": { "type": "number", "format": "double" }, "addressType": { "$ref": "#/components/schemas/sharedAddressType" }, "locationTypeLabel": { "type": "string", "description": "A short, shared label for an address which does not fit the standard\ncategories, e.g. \"School\". It is a place type, never delivery guidance." }, "pinStatus": { "$ref": "#/components/schemas/sharedAddressPinStatus" }, "pinSource": { "$ref": "#/components/schemas/sharedAddressPinSource" }, "pinProviderQuality": { "type": "string" }, "pinPartialMatch": { "type": "boolean" }, "pinValidatedAt": { "type": "string", "format": "date-time" }, "pinConfirmationReason": { "type": "string" } } }, "sharedAddressPinSource": { "type": "string", "enum": [ "NAURT", "GOOGLE_MAPS", "OPERATOR", "LEGACY" ], "description": "The evidence that selected the current operational pin. Provider-specific\nprecision codes belong in pin_provider_quality; clients should use these\nstable, human-meaningful source names instead." }, "sharedAddressPinStatus": { "type": "string", "enum": [ "VERIFIED", "NEEDS_CONFIRMATION", "MANUAL_CONFIRMED", "UNAVAILABLE" ], "description": "Whether the coordinates can be used as an operational delivery pin. This is\ndeliberately separate from whether the written address is valid: an order\nmay name a real address while still needing a human to confirm its location." }, "sharedAddressType": { "type": "string", "enum": [ "HOUSE", "APARTMENT", "OFFICE", "SHOP", "RESTAURANT_CAFE", "HOTEL", "HEALTHCARE", "EDUCATION", "WAREHOUSE" ] }, "sharedDimensions": { "type": "object", "properties": { "height": { "type": "number", "format": "double" }, "width": { "type": "number", "format": "double" }, "depth": { "type": "number", "format": "double" } } }, "sharedMode": { "type": "string", "enum": [ "PRODUCTION", "SANDBOX" ] }, "sharedRateCode": { "type": "string", "enum": [ "QUIV_DEL_IM", "QUIV_DEL_WN", "QUIV_DEL_SD", "QUIV_DEL_ND", "QUIV_RET", "QUIV_DEL_RET", "QUIV_COL" ], "title": "- QUIV_DEL_IM: Immediate delivery\n - QUIV_DEL_WN: Window delivery\n - QUIV_DEL_SD: Same day delivery\n - QUIV_DEL_ND: Next day delivery\n - QUIV_RET: Return\n - QUIV_DEL_RET: Delivery and return\n - QUIV_COL: Collect from store" }, "sharedTaskStatus": { "type": "string", "enum": [ "NOT_STARTED", "READY_FOR_COLLECTION", "OUT_FOR_COLLECTION", "COLLECTED", "OUT_FOR_DELIVERY", "COMPLETED", "FAILED", "CANCELLED" ] }, "sharedTaskSubstatus": { "type": "string", "enum": [ "UNDELIVERABLE", "ATTEMPT" ] }, "sharedTaskType": { "type": "string", "enum": [ "DELIVERY", "RETURN", "COLLECTION" ] }, "sharedTaskUpdate": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32" }, "createdAt": { "type": "string", "format": "date-time" }, "taskId": { "type": "integer", "format": "int32" }, "userGroup": { "$ref": "#/components/schemas/sharedUserGroup" }, "value": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/sharedTaskUpdateValue" } } } }, "sharedTaskUpdateValue": { "type": "object", "properties": { "from": {}, "to": {} } }, "sharedUserGroup": { "type": "string", "enum": [ "CUSTOMER", "MERCHANT", "QUIVER", "CONTROLLER" ] }, "sharedWindow": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } }, "title": "TODO: Change to DateTimeWindow" }, "taskContact": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "company": { "type": "string" }, "emailAddress": { "type": "string" }, "phoneNumber": { "type": "string" } } }, "taskDeliveryType": { "type": "string", "enum": [ "IMMEDIATE", "SAME_DAY", "NEXT_DAY", "WINDOW" ] }, "taskExpectedWindow": { "type": "object", "properties": { "createdAt": { "type": "string", "format": "date-time" }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "isCustomerAtHome": { "type": "boolean" } } }, "taskOrder": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "lineItems": { "type": "array", "items": { "$ref": "#/components/schemas/fulfilmentLineItem" } }, "merchantOrderId": { "type": "string" }, "merchantOrderName": { "type": "string" }, "price": { "$ref": "#/components/schemas/taskOrderPrice" }, "note": { "type": "string" }, "isBig": { "type": "boolean" } } }, "taskOrderPrice": { "type": "object", "properties": { "total": { "type": "number", "format": "double" }, "subtotal": { "type": "number", "format": "double" }, "delivery": { "type": "number", "format": "double" } } }, "taskTask": { "type": "object", "properties": { "taskId": { "type": "integer", "format": "int32" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "taskType": { "$ref": "#/components/schemas/sharedTaskType" }, "merchantName": { "type": "string" }, "mode": { "$ref": "#/components/schemas/sharedMode" }, "status": { "$ref": "#/components/schemas/taskTaskStatusUpdate" }, "fulfilmentType": { "$ref": "#/components/schemas/fulfilmentFulfilmentType" }, "deliveryType": { "$ref": "#/components/schemas/taskDeliveryType" }, "collection": { "$ref": "#/components/schemas/taskTaskPart" }, "delivery": { "$ref": "#/components/schemas/taskTaskPart" }, "order": { "$ref": "#/components/schemas/taskOrder" }, "customer": { "$ref": "#/components/schemas/taskContact" }, "purchaser": { "$ref": "#/components/schemas/taskContact" }, "customerProfileId": { "type": "integer", "format": "int32" }, "trackingId": { "type": "string" }, "trackingUrl": { "type": "string" }, "trackingAccessKey": { "type": "string" }, "surcharge": { "type": "boolean" }, "co2Savings": { "type": "number", "format": "double" }, "notes": { "type": "array", "items": { "$ref": "#/components/schemas/taskTaskNote" } }, "statusUpdates": { "type": "array", "items": { "$ref": "#/components/schemas/taskTaskStatusUpdate" } }, "updates": { "type": "array", "items": { "$ref": "#/components/schemas/sharedTaskUpdate" } }, "rateCode": { "$ref": "#/components/schemas/sharedRateCode" }, "linkedTasks": { "type": "array", "items": { "type": "integer", "format": "int32" } }, "readyForCollection": { "type": "boolean" }, "onTime": { "type": "boolean" }, "onTimeDeviationMinutes": { "type": "integer", "format": "int32" }, "attempts": { "type": "array", "items": { "$ref": "#/components/schemas/taskTaskAttempt" } } } }, "taskTaskAttempt": { "type": "object", "properties": { "taskAttemptId": { "type": "integer", "format": "int32" }, "taskId": { "type": "integer", "format": "int32" }, "parentTaskAttemptId": { "type": "integer", "format": "int32" }, "taskAttemptType": { "$ref": "#/components/schemas/taskTaskAttemptType" }, "attemptNumber": { "type": "integer", "format": "int32", "description": "Numbered within the attempt type, so Ops can read \"Delivery attempt 1\"\nand, if needed later, \"Recovery attempt 2\"." }, "status": { "$ref": "#/components/schemas/taskTaskAttemptStatus" }, "reviewNote": { "type": "string" }, "outcomeNote": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "taskTaskAttemptStatus": { "type": "string", "enum": [ "PENDING", "IN_PROGRESS", "COMPLETED", "FAILED", "CANCELLED" ] }, "taskTaskAttemptType": { "type": "string", "enum": [ "DELIVERY", "RECOVERY", "RE_DELIVERY" ], "description": "A durable operational leg of a task. It is intentionally distinct from a\ncourier job: one attempt can have one or more courier jobs, while attempts\npreserve the reviewed history of a delivery, recovery, or re-delivery." }, "taskTaskNote": { "type": "object", "properties": { "taskNoteId": { "type": "integer", "format": "int32" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "deletedAt": { "type": "string", "format": "date-time" }, "taskId": { "type": "integer", "format": "int32" }, "userGroup": { "$ref": "#/components/schemas/sharedUserGroup" }, "value": { "type": "string" } } }, "taskTaskPart": { "type": "object", "properties": { "address": { "$ref": "#/components/schemas/sharedAddress" }, "date": { "type": "string" }, "window": { "$ref": "#/components/schemas/sharedWindow" }, "expectedWindow": { "$ref": "#/components/schemas/taskExpectedWindow" }, "instructions": { "type": "string" }, "originalDate": { "type": "string" }, "committedWindow": { "$ref": "#/components/schemas/sharedWindow" } } }, "taskTaskStatusUpdate": { "type": "object", "properties": { "taskStatusId": { "type": "integer", "format": "int32" }, "createdAt": { "type": "string", "format": "date-time" }, "userGroup": { "$ref": "#/components/schemas/sharedUserGroup" }, "taskId": { "type": "integer", "format": "int32" }, "value": { "$ref": "#/components/schemas/sharedTaskStatus" }, "subvalue": { "$ref": "#/components/schemas/sharedTaskSubstatus" }, "note": { "type": "string" } }, "title": "In controller service this is used as the create request as well as the type" } } }, "x-readme": { "explorer-enabled": true, "proxy-enabled": true }, "_id": { "buffer": { "0": 100, "1": 231, "2": 25, "3": 199, "4": 19, "5": 95, "6": 86, "7": 0, "8": 65, "9": 210, "10": 115, "11": 26 } } } ```