Create or update a list of shipments

POST {{baseUrl}}/integrations/:id/shipments

Inserting shipments into an integration

This end-point is only available for official Sendcloud partners.

This endpoint allows you to insert shipments (or 'orders') into an API integration from your shop system, and have them appear in your Sendcloud account. Imported orders will appear in the Sendcloud panel under the Incoming order overview with the status Ready to process. This allows you to easily generate parcels and create shipping labels via the API or directly from the Sendcloud panel. The validation for this endpoint is more relaxed, therefore we recommend this method over the Create a parcel endpoint for third-party integrators.

This is an UPSERT endpoint which attempts to be idempotent given specific fields to ensure that orders are not duplicated. If there's an existing match in our database for specific fields (external_order_id and external_shipment_id), then the shipment will be updated. The system will only update orders that have had their updated_at (ISO 8601 DateTime) timestamp changed.

The external_shipment_id field is used to split orders across multiple shipments, however, this field is not supported by all shop systems. If your shop system supports the distribution of product items within an order across multiple shipments, you can use the shipment data to create multiple entries. If your shop does not support this feature, you can set the external_shipment_id value to null.

Batches are limited to 100 orders at once. This endpoint should accept most values in any of the available fields, but in the case of erroneous data, an error message will be returned directly. Your requests should almost always succeed unless the field structure is not correct.

Request Body

{"0"=>{"address"=>"<string>", "address_2"=>"<string>", "city"=>"<string>", "company_name"=>"<string>", "country"=>"CC", "created_at"=>"<dateTime>", "currency"=>"USD", "customs_invoice_nr"=>"<string>", "customs_shipment_type"=>1, "email"=>"<email>", "external_order_id"=>"<string>", "external_shipment_id"=>"<string,null>", "house_number"=>"<string>", "name"=>"<string>", "order_number"=>"<string>", "order_status"=>{"id"=>"<string>", "message"=>"<string>"}, "parcel_items"=>nil, "payment_status"=>{"id"=>"<string>", "message"=>"<string>"}, "postal_code"=>"<string>", "shipping_method_checkout_name"=>"<string>", "telephone"=>"<string>", "to_post_number"=>"<string>", "to_service_point"=>"<integer,null>", "to_state"=>"<string,null>", "updated_at"=>"<dateTime>", "shipping_method"=>"<integer,null>", "total_order_value"=>"<string,null>", "weight"=>"<string,null>", "checkout_payload"=>{"sender_address_id"=>"<integer>", "delivery_method_type"=>"<string>", "delivery_method_data"=>{"delivery_date"=>"<dateTime>", "formatted_delivery_date"=>"<string>", "parcel_handover_date"=>"<dateTime>"}}, "width"=>"<string,null>", "height"=>"<string,null>", "length"=>"<string,null>", "customs_details"=>{"discount_granted"=>{"value"=>"01760275598", "currency"=>"<string,null>"}, "insurance_costs"=>{"value"=>"365572907.5592825971", "currency"=>"<string,null>"}, "freight_costs"=>{"value"=>"019470.4330889647", "currency"=>"<string,null>"}, "other_costs"=>{"value"=>"5037745.870337", "currency"=>"<string,null>"}, "tax_numbers"=>nil}}, "1"=>{"address"=>"<string>", "address_2"=>"<string>", "city"=>"<string>", "company_name"=>"<string>", "country"=>"EE", "created_at"=>"<dateTime>", "currency"=>"GBP", "customs_invoice_nr"=>"<string>", "customs_shipment_type"=>1, "email"=>"<email>", "external_order_id"=>"<string>", "external_shipment_id"=>"<string,null>", "house_number"=>"<string>", "name"=>"<string>", "order_number"=>"<string>", "order_status"=>nil, "parcel_items"=>[{"description"=>"<string>", "quantity"=>"<integer>", "value"=>"<string>", "hs_code"=>"<string>", "origin_country"=>"ZA", "product_id"=>"<string>", "properties"=>{"inc"=>"<string,null>"}, "sku"=>"<string>", "weight"=>"<string,null>", "mid_code"=>"<string,null>", "material_content"=>"<string,null>", "intended_use"=>"<string,null>"}, {"description"=>"<string>", "quantity"=>"<integer>", "value"=>"<string>", "hs_code"=>"<string>", "origin_country"=>"GB", "product_id"=>"<string>", "properties"=>{"dolorecd5"=>"<string,null>", "nisid"=>"<string,null>"}, "sku"=>"<string>", "weight"=>"<string,null>", "mid_code"=>"<string,null>", "material_content"=>"<string,null>", "intended_use"=>"<string,null>"}], "payment_status"=>nil, "postal_code"=>"<string>", "shipping_method_checkout_name"=>"<string>", "telephone"=>"<string>", "to_post_number"=>"<string>", "to_service_point"=>"<integer,null>", "to_state"=>"<string,null>", "updated_at"=>"<dateTime>", "shipping_method"=>"<integer,null>", "total_order_value"=>"<string,null>", "weight"=>"<string,null>", "checkout_payload"=>{"sender_address_id"=>"<integer>", "delivery_method_type"=>"<string>", "delivery_method_data"=>{"delivery_date"=>"<dateTime>", "formatted_delivery_date"=>"<string>", "parcel_handover_date"=>"<dateTime>"}}, "width"=>"<string,null>", "height"=>"<string,null>", "length"=>"<string,null>", "customs_details"=>{"discount_granted"=>{"value"=>"058.730240", "currency"=>"<string,null>"}, "insurance_costs"=>{"value"=>"07181823585", "currency"=>"<string,null>"}, "freight_costs"=>{"value"=>"5084122306", "currency"=>"<string,null>"}, "other_costs"=>{"value"=>"393277", "currency"=>"<string,null>"}, "tax_numbers"=>{"sender"=>[{"name"=>"<string,null>", "country_code"=>"<string,null>", "value"=>"<string,null>"}, {"name"=>"<string,null>", "country_code"=>"<string,null>", "value"=>"<string,null>"}], "receiver"=>[{"name"=>"<string,null>", "country_code"=>"<string,null>", "value"=>"<string,null>"}, {"name"=>"<string,null>", "country_code"=>"<string,null>", "value"=>"<string,null>"}], "importer_of_records"=>[{"name"=>"<string,null>", "country_code"=>"<string,null>", "value"=>"<string,null>"}, {"name"=>"<string,null>", "country_code"=>"<string,null>", "value"=>"<string,null>"}]}}}}

HEADERS

RESPONSES

status: OK

[{"external_order_id":"\u003cstring\u003e","external_shipment_id":"\u003cstring\u003e","shipment_uuid":"\u003cuuid\u003e","status":"updated"},{"external_order_id":"\u003cstring\u003e","external_shipment_id":"\u003cstring\u003e","shipment_uuid":"\u003cuuid\u003e","status":"updated"}]