> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developer-dev.shipbob.dev/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer-dev.shipbob.dev/_mcp/server. # Create Warehouse Receiving Order POST https://gateway-dev.shipbob.dev/Experimental/receiving Content-Type: application/json Reference: https://developer-dev.shipbob.dev/api/receiving/create-warehouse-receiving-order ## OpenAPI Specification ```yaml openapi: 3.1.0 info: title: api-experimental version: 1.0.0 paths: /Experimental/receiving: post: operationId: create-warehouse-receiving-order summary: | Create Warehouse Receiving Order tags: - receiving parameters: - name: Authorization in: header description: Authentication using Personal Access Token (PAT) token required: true schema: type: string responses: '201': description: Created content: application/json: schema: $ref: >- #/components/schemas/Receiving.V3.WarehouseReceivingOrderViewModel '401': description: Authorization missing or invalid content: application/json: schema: description: Any type '403': description: The provided credentials are not authorized to access this resource content: application/json: schema: description: Any type '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/Receiving.ProblemDetails' '422': description: >- Unprocessable Content. Validation errors are returned keyed by field; business-rule errors that are not tied to a specific field are returned under an empty key. A receiving order referencing more than 10,000 unique inventory items (SKUs) across all of its boxes is rejected here with the WRO_UNIQUE_SKU_LIMIT_EXCEEDED reason code; the message includes the submitted and maximum counts so the request can be split. content: application/json: schema: $ref: >- #/components/schemas/Receiving.Post.3.0.Receiving.Unprocessable.Entity.Object requestBody: description: The receiving order to create content: application/json: schema: $ref: '#/components/schemas/Receiving.V3.CreateReceivingOrderV3Model' servers: - url: https://gateway-dev.shipbob.dev description: https://gateway-dev.shipbob.dev components: schemas: Receiving.PackingType: type: string enum: - EverythingInOneBox - OneSkuPerBox - MultipleSkuPerBox title: Receiving.PackingType Receiving.V3.AddBoxItemToBoxV3Model: type: object properties: inventory_id: type: - integer - 'null' description: >- Unique inventory id of the items in the box (optional if sku is provided) lot_date: type: - string - 'null' format: date-time description: Lot expiration date for the items in the box lot_number: type: - string - 'null' description: Lot number of the items in the box quantity: type: integer description: Quantity of the items in the box sku: type: - string - 'null' description: >- SKU identifier for the items in the box (optional if inventory_id is provided) required: - quantity description: "Information about an inventory item contained inside a receiving order box.\r\nAt least one of inventory_id or sku must be provided." title: Receiving.V3.AddBoxItemToBoxV3Model Receiving.V3.AddBoxToOrderV3Model: type: object properties: box_items: type: array items: $ref: '#/components/schemas/Receiving.V3.AddBoxItemToBoxV3Model' description: >- Items contained in this box. A receiving order may reference at most 10,000 unique inventory items (SKUs) across all of its boxes; exceeding this returns a 422 with the WRO_UNIQUE_SKU_LIMIT_EXCEEDED reason code. The limit applies to distinct inventory_ids across the whole order, not to a single box. tracking_number: type: string description: Tracking number for the box shipment required: - box_items - tracking_number description: Information about a box shipment to be added to a V3 receiving order title: Receiving.V3.AddBoxToOrderV3Model Receiving.V3.FreightMetadataV3Model: type: object properties: bol_number: type: - string - 'null' description: >- Bill of Lading number (the BOL number string, distinct from any uploaded BOL document) carrier: type: - string - 'null' description: Carrier name (e.g. Maersk, DHL, FedEx) container_number: type: - string - 'null' description: Shipping container number freight_forwarder: type: - string - 'null' description: Freight forwarder company name notes: type: - string - 'null' description: Free-text freight notes vessel_name: type: - string - 'null' description: Vessel (ship) name description: Optional container/freight metadata for a receiving order title: Receiving.V3.FreightMetadataV3Model Receiving.AssignOrderToFulfillmentCenterModel: type: object properties: id: type: integer description: ID of the fulfillment center to assign this receiving order to required: - id description: "Model containing information that assigns a receiving order to a fulfillment center.\r\nIf the fulfillment center provided is in a receiving hub region, then the response will be the receiving hub location." title: Receiving.AssignOrderToFulfillmentCenterModel Receiving.PackageType: type: string enum: - Package - Pallet - FloorLoadedContainer title: Receiving.PackageType Receiving.V3.CreateReceivingOrderV3Model: type: object properties: box_packaging_type: $ref: '#/components/schemas/Receiving.PackingType' boxes: type: array items: $ref: '#/components/schemas/Receiving.V3.AddBoxToOrderV3Model' description: Box shipments to be added to this receiving order expected_arrival_date: type: string format: date-time description: >- Expected arrival date of all the box shipments in this receiving order final_destination_fulfillment_center_id: type: - integer - 'null' description: Spoke site this receiving order is being routed to freight: oneOf: - $ref: '#/components/schemas/Receiving.V3.FreightMetadataV3Model' - type: 'null' description: Optional container/freight metadata for this receiving order fulfillment_center: $ref: '#/components/schemas/Receiving.AssignOrderToFulfillmentCenterModel' package_type: $ref: '#/components/schemas/Receiving.PackageType' purchase_order_number: type: - string - 'null' description: Purchase order number for this receiving order required: - box_packaging_type - boxes - expected_arrival_date - fulfillment_center - package_type description: Information to create a new receiving order title: Receiving.V3.CreateReceivingOrderV3Model Receiving.V3.FreightMetadataViewModel: type: object properties: bol_number: type: - string - 'null' description: >- Bill of Lading number (the BOL number string, distinct from any uploaded BOL document) carrier: type: - string - 'null' description: Carrier name (e.g. Maersk, DHL, FedEx) container_number: type: - string - 'null' description: Shipping container number freight_forwarder: type: - string - 'null' description: Freight forwarder company name notes: type: - string - 'null' description: Free-text freight notes vessel_name: type: - string - 'null' description: Vessel (ship) name description: Container/freight metadata returned for a receiving order title: Receiving.V3.FreightMetadataViewModel Receiving.FulfillmentCenterViewModel: type: object properties: address1: type: - string - 'null' description: Address line one of the fulfillment center address2: type: - string - 'null' description: Address line two of the fulfillment center city: type: - string - 'null' description: City the fulfillment center is located in country: type: - string - 'null' description: Country the fulfillment center is located in email: type: - string - 'null' description: Email contact for the fulfillment center id: type: integer description: Unique identifier of the fulfillment center name: type: - string - 'null' description: Name of the fulfillment center phone_number: type: - string - 'null' description: Phone number contact for the fulfillment center state: type: - string - 'null' description: State the fulfillment center is located in timezone: type: - string - 'null' description: Timezone the fulfillment center is located in zip_code: type: - string - 'null' description: Postal code of the fulfillment center description: Information about a fulfillment center title: Receiving.FulfillmentCenterViewModel Receiving.V2.InventoryQuantityViewModel: type: object properties: expected_quantity: type: integer description: Quantity of the inventory item submitted in the WRO inventory_id: type: integer description: ID of the inventory item received_quantity: type: integer description: Quantity of the inventory item received by the warehouse sku: type: - string - 'null' description: Sku of the inventory item stowed_quantity: type: integer description: Quantity of the inventory item stowed by the warehouse title: Receiving.V2.InventoryQuantityViewModel Receiving.ReceivingStatus: type: string enum: - Awaiting - Processing - Completed - Cancelled - Incomplete - Arrived - PartiallyArrived - PartiallyArrivedAtHub - ArrivedAtHub - ProcessingAtHub - InternalTransfer title: Receiving.ReceivingStatus Receiving.V2.ReceivingOrderStatusHistoryViewModel: type: object properties: id: type: integer description: Unique id of the status status: type: - string - 'null' description: Name of the status timestamp: type: string format: date-time description: Timestamp when the status was recorded description: View model for receiving order status history title: Receiving.V2.ReceivingOrderStatusHistoryViewModel Receiving.V3.WarehouseReceivingOrderViewModel: type: object properties: box_labels_uri: type: - string - 'null' description: >- URL to the packing slip to be included in each box shipment for this receiving order box_packaging_type: $ref: '#/components/schemas/Receiving.PackingType' expected_arrival_date: type: string format: date-time description: Expected date that all packages will have arrived external_sync_timestamp: type: - string - 'null' format: date-time description: >- The timestamp in UTC when a 3rd party integrator has set in our system freight: oneOf: - $ref: '#/components/schemas/Receiving.V3.FreightMetadataViewModel' - type: 'null' description: >- Optional container/freight metadata for this receiving order (null when none was provided) fulfillment_center: $ref: '#/components/schemas/Receiving.FulfillmentCenterViewModel' id: type: integer description: Unique id of the warehouse receiving order insert_date: type: string format: date-time description: Insert date of the receiving order inventory_quantities: type: - array - 'null' items: $ref: '#/components/schemas/Receiving.V2.InventoryQuantityViewModel' description: Inventory items and quantities within the WRO last_updated_date: type: string format: date-time description: Last date the receiving order was updated package_type: $ref: '#/components/schemas/Receiving.PackageType' purchase_order_number: type: - string - 'null' description: Purchase order number for a receiving order status: $ref: '#/components/schemas/Receiving.ReceivingStatus' status_history: type: - array - 'null' items: $ref: >- #/components/schemas/Receiving.V2.ReceivingOrderStatusHistoryViewModel description: The history of status changes for this receiving order title: Receiving.V3.WarehouseReceivingOrderViewModel Receiving.ProblemDetails: type: object properties: detail: type: - string - 'null' instance: type: - string - 'null' status: type: - integer - 'null' title: type: - string - 'null' type: type: - string - 'null' title: Receiving.ProblemDetails Receiving.Post.3.0.Receiving.Unprocessable.Entity.Object: type: object additionalProperties: type: array items: type: string title: Receiving.Post.3.0.Receiving.Unprocessable.Entity.Object securitySchemes: PAT: type: http scheme: bearer description: Authentication using Personal Access Token (PAT) token OAuth2: type: http scheme: bearer description: OAuth2 authentication using JWT tokens ``` ## Examples **Request** ```json { "box_packaging_type": "EverythingInOneBox", "boxes": [ { "box_items": [ { "quantity": 1, "inventory_id": 0, "lot_date": "2019-08-24T14:15:22+00:00", "lot_number": "2222", "sku": "string" } ], "tracking_number": "860C8CDC8F0B4FC7AB69AC86C20539EC" } ], "expected_arrival_date": "2019-08-24T14:15:22+00:00", "fulfillment_center": { "id": 0 }, "package_type": "Package", "final_destination_fulfillment_center_id": 0, "freight": { "bol_number": "string", "carrier": "string", "container_number": "string", "freight_forwarder": "string", "notes": "string", "vessel_name": "string" }, "purchase_order_number": "string" } ``` **Response** ```json { "box_labels_uri": "https://api.shipbob.com/1.0/receiving/1/labels", "box_packaging_type": "EverythingInOneBox", "expected_arrival_date": "2019-08-24T14:15:22+00:00", "external_sync_timestamp": "2019-08-24T14:15:22+00:00", "freight": { "bol_number": "string", "carrier": "string", "container_number": "string", "freight_forwarder": "string", "notes": "string", "vessel_name": "string" }, "fulfillment_center": { "address1": "5900 W Ogden Ave", "address2": "Suite 100", "city": "Cicero", "country": "USA", "email": "example@example.com", "id": 0, "name": "Cicero (IL)", "phone_number": "555-555-5555", "state": "IL", "timezone": "Central Standard Time", "zip_code": "60804" }, "id": 0, "insert_date": "2019-08-24T14:15:22+00:00", "inventory_quantities": [ { "expected_quantity": 0, "inventory_id": 0, "received_quantity": 0, "sku": "string", "stowed_quantity": 0 } ], "last_updated_date": "2019-08-24T14:15:22+00:00", "package_type": "Package", "purchase_order_number": "string", "status": "Awaiting", "status_history": [ { "id": 0, "status": "Processing", "timestamp": "2019-08-24T14:15:22+00:00" } ] } ``` **SDK Code** ```python default import requests url = "https://gateway-dev.shipbob.dev/Experimental/receiving" payload = { "box_packaging_type": "EverythingInOneBox", "boxes": [ { "box_items": [ { "quantity": 1, "inventory_id": 0, "lot_date": "2019-08-24T14:15:22+00:00", "lot_number": "2222", "sku": "string" } ], "tracking_number": "860C8CDC8F0B4FC7AB69AC86C20539EC" } ], "expected_arrival_date": "2019-08-24T14:15:22+00:00", "fulfillment_center": { "id": 0 }, "package_type": "Package", "final_destination_fulfillment_center_id": 0, "freight": { "bol_number": "string", "carrier": "string", "container_number": "string", "freight_forwarder": "string", "notes": "string", "vessel_name": "string" }, "purchase_order_number": "string" } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript default const url = 'https://gateway-dev.shipbob.dev/Experimental/receiving'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"box_packaging_type":"EverythingInOneBox","boxes":[{"box_items":[{"quantity":1,"inventory_id":0,"lot_date":"2019-08-24T14:15:22+00:00","lot_number":"2222","sku":"string"}],"tracking_number":"860C8CDC8F0B4FC7AB69AC86C20539EC"}],"expected_arrival_date":"2019-08-24T14:15:22+00:00","fulfillment_center":{"id":0},"package_type":"Package","final_destination_fulfillment_center_id":0,"freight":{"bol_number":"string","carrier":"string","container_number":"string","freight_forwarder":"string","notes":"string","vessel_name":"string"},"purchase_order_number":"string"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go default package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://gateway-dev.shipbob.dev/Experimental/receiving" payload := strings.NewReader("{\n \"box_packaging_type\": \"EverythingInOneBox\",\n \"boxes\": [\n {\n \"box_items\": [\n {\n \"quantity\": 1,\n \"inventory_id\": 0,\n \"lot_date\": \"2019-08-24T14:15:22+00:00\",\n \"lot_number\": \"2222\",\n \"sku\": \"string\"\n }\n ],\n \"tracking_number\": \"860C8CDC8F0B4FC7AB69AC86C20539EC\"\n }\n ],\n \"expected_arrival_date\": \"2019-08-24T14:15:22+00:00\",\n \"fulfillment_center\": {\n \"id\": 0\n },\n \"package_type\": \"Package\",\n \"final_destination_fulfillment_center_id\": 0,\n \"freight\": {\n \"bol_number\": \"string\",\n \"carrier\": \"string\",\n \"container_number\": \"string\",\n \"freight_forwarder\": \"string\",\n \"notes\": \"string\",\n \"vessel_name\": \"string\"\n },\n \"purchase_order_number\": \"string\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby default require 'uri' require 'net/http' url = URI("https://gateway-dev.shipbob.dev/Experimental/receiving") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"box_packaging_type\": \"EverythingInOneBox\",\n \"boxes\": [\n {\n \"box_items\": [\n {\n \"quantity\": 1,\n \"inventory_id\": 0,\n \"lot_date\": \"2019-08-24T14:15:22+00:00\",\n \"lot_number\": \"2222\",\n \"sku\": \"string\"\n }\n ],\n \"tracking_number\": \"860C8CDC8F0B4FC7AB69AC86C20539EC\"\n }\n ],\n \"expected_arrival_date\": \"2019-08-24T14:15:22+00:00\",\n \"fulfillment_center\": {\n \"id\": 0\n },\n \"package_type\": \"Package\",\n \"final_destination_fulfillment_center_id\": 0,\n \"freight\": {\n \"bol_number\": \"string\",\n \"carrier\": \"string\",\n \"container_number\": \"string\",\n \"freight_forwarder\": \"string\",\n \"notes\": \"string\",\n \"vessel_name\": \"string\"\n },\n \"purchase_order_number\": \"string\"\n}" response = http.request(request) puts response.read_body ``` ```java default import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://gateway-dev.shipbob.dev/Experimental/receiving") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"box_packaging_type\": \"EverythingInOneBox\",\n \"boxes\": [\n {\n \"box_items\": [\n {\n \"quantity\": 1,\n \"inventory_id\": 0,\n \"lot_date\": \"2019-08-24T14:15:22+00:00\",\n \"lot_number\": \"2222\",\n \"sku\": \"string\"\n }\n ],\n \"tracking_number\": \"860C8CDC8F0B4FC7AB69AC86C20539EC\"\n }\n ],\n \"expected_arrival_date\": \"2019-08-24T14:15:22+00:00\",\n \"fulfillment_center\": {\n \"id\": 0\n },\n \"package_type\": \"Package\",\n \"final_destination_fulfillment_center_id\": 0,\n \"freight\": {\n \"bol_number\": \"string\",\n \"carrier\": \"string\",\n \"container_number\": \"string\",\n \"freight_forwarder\": \"string\",\n \"notes\": \"string\",\n \"vessel_name\": \"string\"\n },\n \"purchase_order_number\": \"string\"\n}") .asString(); ``` ```php default request('POST', 'https://gateway-dev.shipbob.dev/Experimental/receiving', [ 'body' => '{ "box_packaging_type": "EverythingInOneBox", "boxes": [ { "box_items": [ { "quantity": 1, "inventory_id": 0, "lot_date": "2019-08-24T14:15:22+00:00", "lot_number": "2222", "sku": "string" } ], "tracking_number": "860C8CDC8F0B4FC7AB69AC86C20539EC" } ], "expected_arrival_date": "2019-08-24T14:15:22+00:00", "fulfillment_center": { "id": 0 }, "package_type": "Package", "final_destination_fulfillment_center_id": 0, "freight": { "bol_number": "string", "carrier": "string", "container_number": "string", "freight_forwarder": "string", "notes": "string", "vessel_name": "string" }, "purchase_order_number": "string" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp default using RestSharp; var client = new RestClient("https://gateway-dev.shipbob.dev/Experimental/receiving"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"box_packaging_type\": \"EverythingInOneBox\",\n \"boxes\": [\n {\n \"box_items\": [\n {\n \"quantity\": 1,\n \"inventory_id\": 0,\n \"lot_date\": \"2019-08-24T14:15:22+00:00\",\n \"lot_number\": \"2222\",\n \"sku\": \"string\"\n }\n ],\n \"tracking_number\": \"860C8CDC8F0B4FC7AB69AC86C20539EC\"\n }\n ],\n \"expected_arrival_date\": \"2019-08-24T14:15:22+00:00\",\n \"fulfillment_center\": {\n \"id\": 0\n },\n \"package_type\": \"Package\",\n \"final_destination_fulfillment_center_id\": 0,\n \"freight\": {\n \"bol_number\": \"string\",\n \"carrier\": \"string\",\n \"container_number\": \"string\",\n \"freight_forwarder\": \"string\",\n \"notes\": \"string\",\n \"vessel_name\": \"string\"\n },\n \"purchase_order_number\": \"string\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift default import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "box_packaging_type": "EverythingInOneBox", "boxes": [ [ "box_items": [ [ "quantity": 1, "inventory_id": 0, "lot_date": "2019-08-24T14:15:22+00:00", "lot_number": "2222", "sku": "string" ] ], "tracking_number": "860C8CDC8F0B4FC7AB69AC86C20539EC" ] ], "expected_arrival_date": "2019-08-24T14:15:22+00:00", "fulfillment_center": ["id": 0], "package_type": "Package", "final_destination_fulfillment_center_id": 0, "freight": [ "bol_number": "string", "carrier": "string", "container_number": "string", "freight_forwarder": "string", "notes": "string", "vessel_name": "string" ], "purchase_order_number": "string" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://gateway-dev.shipbob.dev/Experimental/receiving")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```