{"openapi":"3.1.0","info":{"title":"POST /api/v1/inventory/transfers/{transfer_id}/receive","version":"1.0.0","description":"Receive transfer"},"servers":[{"url":"https://api.ondayzero.com","description":"Production"}],"paths":{"/api/v1/inventory/transfers/{transfer_id}/receive":{"post":{"tags":["inventory:transfers"],"summary":"Receive transfer","description":"Mark transfer as received. Adds inventory to destination location.","operationId":"receive_transfer","parameters":[{"name":"transfer_id","in":"path","required":true,"schema":{"type":"string","title":"Transfer Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferReceiveRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_TransferResponse_"}}}},"400":{"description":"Bad Request - Invalid input","content":{"application/json":{"example":{"error":"validation_error","message":"Validation failed: due_date: Input should be a valid date","errors":{"due_date":"Input should be a valid date"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing/invalid token or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - Resource does not exist","content":{"application/json":{"example":{"error":"not_found","message":"Resource not found","code":"NOT_FOUND_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"receive_transfer_api_v1_inventory_transfers__transfer_id__receive_post"}}},"components":{"schemas":{"LocationSummary":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code"},"location_type":{"$ref":"#/components/schemas/LocationTypeEnum"},"is_default":{"type":"boolean","title":"Is Default"}},"type":"object","required":["id","name","location_type","is_default"],"title":"LocationSummary","description":"Minimal location info for embedding in other responses."},"LocationTypeEnum":{"type":"string","enum":["warehouse","store","virtual","drop_ship","office","supplier","manufacturer","packaging","copacker","third_party_logistics","other"],"title":"LocationTypeEnum","description":"Types of inventory locations."},"SuccessEnvelope_TransferResponse_":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code"},"data":{"anyOf":[{"$ref":"#/components/schemas/TransferResponse"},{"type":"null"}]}},"additionalProperties":true,"type":"object","title":"SuccessEnvelope[TransferResponse]"},"TransferItemReceive":{"properties":{"transfer_item_id":{"type":"string","title":"Transfer Item Id","description":"ID of the transfer item"},"received_quantity":{"type":"integer","minimum":0.0,"title":"Received Quantity","description":"Actual quantity received"},"has_damage":{"type":"boolean","title":"Has Damage","default":false},"damage_notes":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Damage Notes"}},"type":"object","required":["transfer_item_id","received_quantity"],"title":"TransferItemReceive","description":"Schema for receiving a transfer item."},"TransferItemResponse":{"properties":{"variant_id":{"type":"string","title":"Variant Id","description":"Variant being transferred"},"quantity":{"type":"integer","exclusiveMinimum":0.0,"title":"Quantity","description":"Quantity to transfer"},"notes":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Notes"},"id":{"type":"string","title":"Id"},"transfer_id":{"type":"string","title":"Transfer Id"},"received_quantity":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Received Quantity"},"has_damage":{"type":"boolean","title":"Has Damage","default":false},"damage_notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Damage Notes"},"final_quantity":{"type":"integer","title":"Final Quantity"},"has_discrepancy":{"type":"boolean","title":"Has Discrepancy"},"discrepancy_amount":{"type":"integer","title":"Discrepancy Amount"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"},"variant_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Variant Name"},"variant_sku":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Variant Sku"}},"type":"object","required":["variant_id","quantity","id","transfer_id","final_quantity","has_discrepancy","discrepancy_amount","created_at","updated_at"],"title":"TransferItemResponse","description":"Schema for transfer item response."},"TransferReceiveRequest":{"properties":{"received_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Received Date","description":"Date of receipt (defaults to today)"},"items":{"items":{"$ref":"#/components/schemas/TransferItemReceive"},"type":"array","minItems":1,"title":"Items","description":"Items received with quantities"},"notes":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Notes"}},"type":"object","required":["items"],"title":"TransferReceiveRequest","description":"Schema for receiving a transfer."},"TransferResponse":{"properties":{"id":{"type":"string","title":"Id"},"business_id":{"type":"string","title":"Business Id"},"transfer_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Transfer Number"},"status":{"$ref":"#/components/schemas/TransferStatusEnum"},"from_location_id":{"type":"string","title":"From Location Id"},"to_location_id":{"type":"string","title":"To Location Id"},"from_location":{"anyOf":[{"$ref":"#/components/schemas/LocationSummary"},{"type":"null"}]},"to_location":{"anyOf":[{"$ref":"#/components/schemas/LocationSummary"},{"type":"null"}]},"transfer_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Transfer Date"},"expected_arrival_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Expected Arrival Date"},"received_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Received Date"},"tracking_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tracking Number"},"carrier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Carrier"},"shipping_cost":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Shipping Cost"},"expected_freight_cost":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expected Freight Cost"},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notes"},"items":{"items":{"$ref":"#/components/schemas/TransferItemResponse"},"type":"array","title":"Items","default":[]},"total_items":{"type":"integer","title":"Total Items","default":0},"total_quantity":{"type":"integer","title":"Total Quantity","default":0},"total_received_quantity":{"type":"integer","title":"Total Received Quantity","default":0},"has_discrepancy":{"type":"boolean","title":"Has Discrepancy","default":false},"is_editable":{"type":"boolean","title":"Is Editable","default":false},"can_ship":{"type":"boolean","title":"Can Ship","default":false},"can_receive":{"type":"boolean","title":"Can Receive","default":false},"can_cancel":{"type":"boolean","title":"Can Cancel","default":false},"shipped_by_user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Shipped By User Id"},"received_by_user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Received By User Id"},"version":{"type":"integer","title":"Version","default":1},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"},"cost_basis":{"type":"integer","title":"Cost Basis","default":0},"bill_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bill Id"},"bill_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bill Status"},"bill_amount":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Bill Amount"},"bill_balance_due":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Bill Balance Due"},"bill_received_on":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Bill Received On"},"bill_paid_on":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Bill Paid On"}},"type":"object","required":["id","business_id","status","from_location_id","to_location_id","created_at","updated_at"],"title":"TransferResponse","description":"Schema for transfer response."},"TransferStatusEnum":{"type":"string","enum":["draft","pending","in_transit","received","cancelled"],"title":"TransferStatusEnum","description":"Status of an inventory transfer."},"ErrorResponse":{"title":"ErrorResponse","type":"object","description":"Envelope returned by every non-2xx response. Branch on `code` (stable) rather than `message` (human-readable, may change).","required":["error","message","code"],"properties":{"error":{"type":"string","description":"Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`."},"message":{"type":"string","description":"Human-readable explanation, safe to show to end users."},"code":{"type":"string","description":"Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`)."},"request_id":{"type":"string","description":"Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied."},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"Field-level validation messages keyed by field name. Present on 400/422 validation failures only."}}}},"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Token","description":"API token authentication. Format: `Bearer dz_...`"}}},"security":[{"BearerAuth":[]}]}