Create a parcel

POST {{baseUrl}}/parcels?errors=verbose-carrier

This endpoint creates a parcel under your API credentials.

• You can choose to announce the parcel and create the shipping label at the same time as you create the parcel by providing the parameter request_label: true.

• When request_label is false, you can create the parcel but it will not be announced.

• You can then request the shipping label at a later date by changing the request_label parameter via the Update a parcel endpoint. <!-- theme: warning -->

  Pay attention to enter the correct sender_address if you wish to ship this parcel from a location other than your default sender address. You can find the sender_address for each of the addresses you've saved in your Sendcloud account via the Retrieve a sender address endpoint.

International parcel creation

If you want to create a parcel to ship to a destination country outside the EU, it's mandatory to include additional information related to the parcel contents. This allows Sendcloud to automatically generate the required customs documentation based on the international shipping method selected. After the shipping label and associated documents are generated, you can retrieve and download them via the Parcel documents endpoint.

If you have more than one added active contracts for specific carrier, you must fill contract attribute with your desired contract's ID in your request. You can get your contracts ID from Retrieve a list of contracts.

International parcels require more information than domestic parcels. Certain customs documents must be created when shipping to countries outside the EU. For Sendcloud to successfully generate these documents, all the necessary information must be available in your parcel request. For more in-depth information on international shipping and the requirements, please check our developers portal.

Multicollo

More information on how to create multiple parcels within one shipment can be found on the related page of our developers portal.

Request Params

Request Body

{"parcel"=>{"name"=>"<string>", "address"=>"<string>", "city"=>"<string>", "postal_code"=>"<string>", "country"=>"<string>", "id"=>"<integer>", "company_name"=>"<string>", "contract"=>"<integer>", "address_2"=>"<string>", "house_number"=>"<string>", "telephone"=>"<string>", "request_label"=>"<boolean>", "email"=>"<string>", "shipment"=>{"id"=>"<integer>", "name"=>"<string>"}, "weight"=>"<string>", "order_number"=>"<string>", "insured_value"=>"<integer>", "total_order_value_currency"=>"<string>", "total_order_value"=>"<string>", "quantity"=>"<integer>", "shipping_method_checkout_name"=>"<string>", "to_post_number"=>"<string>", "country_state"=>"<string>", "sender_address"=>"<integer>", "customs_invoice_nr"=>"<string>", "customs_shipment_type"=>2, "external_reference"=>"<string>", "reference"=>"0", "to_service_point"=>"<integer>", "total_insured_value"=>"<integer>", "shipment_uuid"=>"<string>", "parcel_items"=>[{"hs_code"=>"<string>", "weight"=>"<string>", "quantity"=>"<integer>", "description"=>"<string>", "value"=>"<number>", "origin_country"=>"<string>", "sku"=>"<string>", "product_id"=>"<string>", "item_id"=>"<string>", "return_reason"=>"<integer>", "return_message"=>"<string>", "mid_code"=>"<string>", "material_content"=>"<string>", "intended_use"=>"<string>"}, {"hs_code"=>"<string>", "weight"=>"<string>", "quantity"=>"<integer>", "description"=>"<string>", "value"=>"<number>", "origin_country"=>"<string>", "sku"=>"<string>", "product_id"=>"<string>", "item_id"=>"<string>", "return_reason"=>"<integer>", "return_message"=>"<string>", "mid_code"=>"<string>", "material_content"=>"<string>", "intended_use"=>"<string>"}], "is_return"=>"<boolean>", "length"=>"<string>", "width"=>"<string>", "height"=>"<string>", "request_label_async"=>"<boolean>", "apply_shipping_rules"=>"<boolean>", "from_name"=>"<string>", "from_company_name"=>"<string>", "from_address_1"=>"<string>", "from_address_2"=>"<string>", "from_house_number"=>"<string>", "from_city"=>"<string>", "from_postal_code"=>"<string>", "from_country"=>"<string>", "from_telephone"=>"<string>", "from_email"=>"<string>", "from_vat_number"=>"<string>", "from_eori_number"=>"<string>", "from_inbound_vat_number"=>"<string>", "from_inbound_eori_number"=>"<string>", "from_ioss_number"=>"<string>", "customs_information"=>{"customs_invoice_nr"=>"<string>", "customs_shipment_type"=>3, "export_type"=>"commercial_b2c", "invoice_date"=>"<date>", "discount_granted"=>"<string>", "freight_costs"=>"<string>", "insurance_costs"=>"<string>", "other_costs"=>"<string>", "general_notes"=>"<string>", "additional_declaration_statements"=>["<string>", "<string>"], "importer_of_record"=>{"name"=>"<string>", "address_1"=>"<string>", "city"=>"<string>", "postal_code"=>"<string>", "country_code"=>"<string>", "company_name"=>"<string>", "address_2"=>"<string>", "house_number"=>"<string>", "country_state"=>"<string>", "telephone"=>"<string>", "email"=>"<string>"}, "tax_numbers"=>{"sender"=>[{"name"=>"CNP", "country_code"=>"<string>", "value"=>"<string>"}, {"name"=>"EORI", "country_code"=>"<string>", "value"=>"<string>"}], "receiver"=>[{"name"=>"STA", "country_code"=>"<string>", "value"=>"<string>"}, {"name"=>"RGP", "country_code"=>"<string>", "value"=>"<string>"}], "importer_of_record"=>[{"name"=>"STA", "country_code"=>"<string>", "value"=>"<string>"}, {"name"=>"STA", "country_code"=>"<string>", "value"=>"<string>"}]}, "return_data"=>{"return_postal_code"=>"<string>", "outbound_tracking_number"=>"<string>", "outbound_shipment_date"=>"<date>", "outbound_carrier_name"=>"<string>"}}}}

HEADERS

RESPONSES

status: OK

{"failed_parcels":[{"parcel":{"id":"\u003cinteger\u003e","address":"\u003cstring\u003e","address_2":"\u003cstring\u003e","address_divided":{"house_number":"\u003cstring\u003e","street":"\u003cstring\u003e"},"carrier":{"code":"dhl_express"},"city":"\u003cstring\u003e","company_name":"\u003cstring\u003e","contract":"\u003cinteger\u003e","country":{"iso_2":"\u003cstring\u003e","iso_3":"\u003cstring\u003e","name":"\u003cstring\u003e"},"customs_invoice_nr":"\u003cstring\u003e","customs_shipment_type":1,"data":{},"date_created":"\u003cstring\u003e","date_updated":"\u003cstring\u003e","date_announced":"\u003cstring\u003e","email":"\u003cstring\u003e","insured_value":"\u003cinteger\u003e","label":{"label_printer":"\u003cstring\u003e","normal_printer":["\u003cstring\u003e","\u003cstring\u003e"]},"name":"\u003cstring\u003e","order_number":"\u003cstring\u003e","shipment_uuid":"\u003cstring\u003e","parcel_items":[{"hs_code":"\u003cstring\u003e","weight":"\u003cstring\u003e","quantity":"\u003cinteger\u003e","description":"\u003cstring\u003e","value":"\u003cnumber\u003e","origin_country":"\u003cstring\u003e","sku":"\u003cstring\u003e","product_id":"\u003cstring\u003e","properties":{},"item_id":"\u003cstring\u003e","return_reason":"\u003cinteger\u003e","return_message":"\u003cstring\u003e","mid_code":"\u003cstring\u003e","material_content":"\u003cstring\u003e","intended_use":"\u003cstring\u003e"},{"hs_code":"\u003cstring\u003e","weight":"\u003cstring\u003e","quantity":"\u003cinteger\u003e","description":"\u003cstring\u003e","value":"\u003cnumber\u003e","origin_country":"\u003cstring\u003e","sku":"\u003cstring\u003e","product_id":"\u003cstring\u003e","properties":{},"item_id":"\u003cstring\u003e","return_reason":"\u003cinteger\u003e","return_message":"\u003cstring\u003e","mid_code":"\u003cstring\u003e","material_content":"\u003cstring\u003e","intended_use":"\u003cstring\u003e"}],"postal_code":"\u003cstring\u003e","external_reference":"\u003cstring\u003e","reference":"0","shipment":{"id":"\u003cinteger\u003e","name":"\u003cstring\u003e"},"status":{"id":"\u003cinteger\u003e","message":"\u003cstring\u003e"},"documents":[{"type":"commercial-invoice","size":"\u003cstring\u003e","link":"\u003cstring\u003e"},{"type":"label","size":"\u003cstring\u003e","link":"\u003cstring\u003e"}],"telephone":"\u003cstring\u003e","to_service_point":"\u003cstring\u003e","to_state":"\u003cstring\u003e","total_insured_value":"\u003cinteger\u003e","total_order_value_currency":"\u003cstring\u003e","total_order_value":"\u003cstring\u003e","tracking_number":"\u003cstring\u003e","tracking_url":"\u003cstring\u003e","weight":"\u003cstring\u003e","type":"parcel","colli_uuid":"\u003cstring\u003e","collo_nr":"\u003cinteger\u003e","collo_count":"\u003cinteger\u003e","is_return":"\u003cboolean\u003e","awb_tracking_number":"\u003cstring\u003e","box_number":"\u003cinteger\u003e","length":"\u003cstring\u003e","width":"\u003cstring\u003e","height":"\u003cstring\u003e","shipping_method_checkout_name":"\u003cstring\u003e","customs_declaration":{},"errors":{"non_field_errors":["\u003cstring\u003e","\u003cstring\u003e"]},"customs_information":{"customs_invoice_nr":"\u003cstring\u003e","customs_shipment_type":3,"export_type":"commercial_b2c","invoice_date":"\u003cdate\u003e","discount_granted":"\u003cstring\u003e","freight_costs":"\u003cstring\u003e","insurance_costs":"\u003cstring\u003e","other_costs":"\u003cstring\u003e","general_notes":"\u003cstring\u003e","additional_declaration_statements":["\u003cstring\u003e","\u003cstring\u003e"],"importer_of_record":{"name":"\u003cstring\u003e","address_1":"\u003cstring\u003e","city":"\u003cstring\u003e","postal_code":"\u003cstring\u003e","country_code":"\u003cstring\u003e","company_name":"\u003cstring\u003e","address_2":"\u003cstring\u003e","house_number":"\u003cstring\u003e","country_state":"\u003cstring\u003e","telephone":"\u003cstring\u003e","email":"\u003cstring\u003e"},"tax_numbers":{"sender":[{"name":"MID","country_code":"\u003cstring\u003e","value":"\u003cstring\u003e"},{"name":"OKP","country_code":"\u003cstring\u003e","value":"\u003cstring\u003e"}],"receiver":[{"name":"KPP","country_code":"\u003cstring\u003e","value":"\u003cstring\u003e"},{"name":"DUN","country_code":"\u003cstring\u003e","value":"\u003cstring\u003e"}],"importer_of_record":[{"name":"VAT","country_code":"\u003cstring\u003e","value":"\u003cstring\u003e"},{"name":"GST","country_code":"\u003cstring\u003e","value":"\u003cstring\u003e"}]},"return_data":{"return_postal_code":"\u003cstring\u003e","outbound_tracking_number":"\u003cstring\u003e","outbound_shipment_date":"\u003cdate\u003e","outbound_carrier_name":"\u003cstring\u003e"}}},"errors":{}},{"parcel":{"id":"\u003cinteger\u003e","address":"\u003cstring\u003e","address_2":"\u003cstring\u003e","address_divided":{"house_number":"\u003cstring\u003e","street":"\u003cstring\u003e"},"carrier":{"code":"viatim"},"city":"\u003cstring\u003e","company_name":"\u003cstring\u003e","contract":"\u003cinteger\u003e","country":{"iso_2":"\u003cstring\u003e","iso_3":"\u003cstring\u003e","name":"\u003cstring\u003e"},"customs_invoice_nr":"\u003cstring\u003e","customs_shipment_type":0,"data":{},"date_created":"\u003cstring\u003e","date_updated":"\u003cstring\u003e","date_announced":"\u003cstring\u003e","email":"\u003cstring\u003e","insured_value":"\u003cinteger\u003e","label":{"label_printer":"\u003cstring\u003e","normal_printer":["\u003cstring\u003e","\u003cstring\u003e"]},"name":"\u003cstring\u003e","order_number":"\u003cstring\u003e","shipment_uuid":"\u003cstring\u003e","parcel_items":[{"hs_code":"\u003cstring\u003e","weight":"\u003cstring\u003e","quantity":"\u003cinteger\u003e","description":"\u003cstring\u003e","value":"\u003cnumber\u003e","origin_country":"\u003cstring\u003e","sku":"\u003cstring\u003e","product_id":"\u003cstring\u003e","properties":{},"item_id":"\u003cstring\u003e","return_reason":"\u003cinteger\u003e","return_message":"\u003cstring\u003e","mid_code":"\u003cstring\u003e","material_content":"\u003cstring\u003e","intended_use":"\u003cstring\u003e"},{"hs_code":"\u003cstring\u003e","weight":"\u003cstring\u003e","quantity":"\u003cinteger\u003e","description":"\u003cstring\u003e","value":"\u003cnumber\u003e","origin_country":"\u003cstring\u003e","sku":"\u003cstring\u003e","product_id":"\u003cstring\u003e","properties":{},"item_id":"\u003cstring\u003e","return_reason":"\u003cinteger\u003e","return_message":"\u003cstring\u003e","mid_code":"\u003cstring\u003e","material_content":"\u003cstring\u003e","intended_use":"\u003cstring\u003e"}],"postal_code":"\u003cstring\u003e","external_reference":"\u003cstring\u003e","reference":"0","shipment":{"id":"\u003cinteger\u003e","name":"\u003cstring\u003e"},"status":{"id":"\u003cinteger\u003e","message":"\u003cstring\u003e"},"documents":[{"type":"cn23-default","size":"\u003cstring\u003e","link":"\u003cstring\u003e"},{"type":"cp71","size":"\u003cstring\u003e","link":"\u003cstring\u003e"}],"telephone":"\u003cstring\u003e","to_service_point":"\u003cstring\u003e","to_state":"\u003cstring\u003e","total_insured_value":"\u003cinteger\u003e","total_order_value_currency":"\u003cstring\u003e","total_order_value":"\u003cstring\u003e","tracking_number":"\u003cstring\u003e","tracking_url":"\u003cstring\u003e","weight":"\u003cstring\u003e","type":"letter","colli_uuid":"\u003cstring\u003e","collo_nr":"\u003cinteger\u003e","collo_count":"\u003cinteger\u003e","is_return":"\u003cboolean\u003e","awb_tracking_number":"\u003cstring\u003e","box_number":"\u003cinteger\u003e","length":"\u003cstring\u003e","width":"\u003cstring\u003e","height":"\u003cstring\u003e","shipping_method_checkout_name":"\u003cstring\u003e","customs_declaration":{},"errors":{"non_field_errors":["\u003cstring\u003e","\u003cstring\u003e"]},"customs_information":{"customs_invoice_nr":"\u003cstring\u003e","customs_shipment_type":0,"export_type":"commercial_b2c","invoice_date":"\u003cdate\u003e","discount_granted":"\u003cstring\u003e","freight_costs":"\u003cstring\u003e","insurance_costs":"\u003cstring\u003e","other_costs":"\u003cstring\u003e","general_notes":"\u003cstring\u003e","additional_declaration_statements":["\u003cstring\u003e","\u003cstring\u003e"],"importer_of_record":{"name":"\u003cstring\u003e","address_1":"\u003cstring\u003e","city":"\u003cstring\u003e","postal_code":"\u003cstring\u003e","country_code":"\u003cstring\u003e","company_name":"\u003cstring\u003e","address_2":"\u003cstring\u003e","house_number":"\u003cstring\u003e","country_state":"\u003cstring\u003e","telephone":"\u003cstring\u003e","email":"\u003cstring\u003e"},"tax_numbers":{"sender":[{"name":"CNP","country_code":"\u003cstring\u003e","value":"\u003cstring\u003e"},{"name":"MID","country_code":"\u003cstring\u003e","value":"\u003cstring\u003e"}],"receiver":[{"name":"FTZ","country_code":"\u003cstring\u003e","value":"\u003cstring\u003e"},{"name":"MID","country_code":"\u003cstring\u003e","value":"\u003cstring\u003e"}],"importer_of_record":[{"name":"CNP","country_code":"\u003cstring\u003e","value":"\u003cstring\u003e"},{"name":"RGP","country_code":"\u003cstring\u003e","value":"\u003cstring\u003e"}]},"return_data":{"return_postal_code":"\u003cstring\u003e","outbound_tracking_number":"\u003cstring\u003e","outbound_shipment_date":"\u003cdate\u003e","outbound_carrier_name":"\u003cstring\u003e"}}},"errors":{}}]}