{"$schema":"http://json-schema.org/draft-04/schema#","type":"object","properties":{"carrier":{"type":"string","enum":["angel_de","asendia","cargo_international","dhl","dhl_express","dpag","dpd","gls","go","hermes","iloxx","parcel_one","ups"],"description":"acronym of the carrier you want to use"},"to":{"$ref":"#/definitions/address","description":"the receivers address"},"from":{"$ref":"#/definitions/address","description":"If missing, the default sender address (if defined in your shipcloud account) will be used"},"cover_address":{"$ref":"#/definitions/address","description":"Overwrites the sender address on the shipping label"},"package":{"$ref":"#/definitions/package"},"service":{"type":"string","enum":["asendia_epaq_standard_economy","asendia_epaq_standard_priority","cargo_international_express","dhl_europaket","dhl_prio","dhl_warenpost","dpag_warenpost","dpag_warenpost_signature","dpag_warenpost_untracked","economy_select","gls_express_0800","gls_express_0900","gls_express_1000","gls_express_1200","gls_pick_and_ship","one_day","one_day_early","returns","same_day","standard","ups_expedited","ups_express_1200"],"default":"standard","description":"The service that should be used for the shipment."},"reference_number":{"type":"string","description":"a reference number (max. 30 characters) that you want this shipment to be identified with. You can use this afterwards to easier find the shipment in the shipcloud.io backoffice"},"description":{"type":"string","description":"text that describes the contents of the shipment. This parameter is mandatory if you're using UPS and the following conditions are true: from and to countries are not the same; from and/or to countries are not in the EU; from and to countries are in the EU and the shipments service is not 'standard'. The parameter is also mandatory when using DHL Express as carrier."},"label":{"$ref":"#/definitions/label","description":"label characteristics"},"label_voucher":{"$ref":"#/definitions/label_voucher","description":"label voucher characteristics"},"notification_email":{"type":"string","description":"email address that we should notify once there's an update for this shipment"},"incoterm":{"type":"string","enum":["ddp","ddp_untaxed","dap","dap_cleared","ddu","ddu_cleared"]},"additional_services":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","enum":["advance_notice","angel_de_delivery_date_time","asendia_bonus_tracking","cash_on_delivery","delivery_date","delivery_note","delivery_time","dhl_endorsement","dhl_gogreen","dhl_ident_check","dhl_named_person_only","dhl_no_neighbor_delivery","dhl_parcel_outlet_routing","dhl_preferred_neighbor","dpd_food","drop_authorization","gls_guaranteed24service","hazardous_goods","hermes_eilservice","hermes_identservice","premium_international","saturday_delivery","ups_access_point_notification","ups_adult_signature","ups_carbon_neutral","ups_direct_delivery_only","ups_signature_required","visual_age_check"],"description":"key to identify the additional service"},"properties":{"type":"object","properties":{"amount":{"type":"number"},"bank_account_holder":{"type":"string"},"bank_account_number":{"type":"string"},"bank_code":{"type":"string"},"bank_name":{"type":"string"},"currency":{"type":"string"},"date":{"type":"string"},"date_of_birth":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string"},"handling":{"type":"string","enum":["abandon","return_immediately"],"description":"Used for dhl_endorsement. By choosing the handling option abandon, your parcel will not be returned to you, but rather auctioned off or destroyed by the recipient countrys' postal company. You will not be charged with a return fee for this option. When using the option return_immediately, the shipment will be returned to you and you will be charged for returning it."},"id_type":{"type":"string","enum":["german_identity_card","german_passport","international_passport"],"description":"Type of ID document that should be used for verifying a Hermes recipient"},"id_number":{"type":"string","description":"ID number from the document"},"language":{"type":"string","description":"language the customer should be notified in (ISO-639-1 format)"},"last_name":{"type":"string"},"message":{"type":"string"},"minimum_age":{"type":"string"},"phone":{"type":"string"},"reference1":{"type":"string","description":"Text that should be displayed as the reason for transfer"},"regulation_class":{"type":"string","enum":["limited_quantities"],"description":"Key that identifies the hazardous goods regulation class"},"sms":{"type":"string"},"time_of_day_earliest":{"type":"string"},"time_of_day_latest":{"type":"string"}}}}},"required":["name"],"additionalProperties":false},"pickup":{"$ref":"#/definitions/pickup","description":"pickup request for this shipment"},"customs_declaration":{"type":"object","description":"declaration of customs related information","properties":{"contents_type":{"type":"string","enum":["commercial_goods","commercial_sample","documents","gift","returned_goods"],"description":"Type of contents"},"contents_explanation":{"type":"string","description":"description of contents. Mandatory if contents_type is 'commercial_goods. Max 256 characters, when using DHL as your carrier'"},"currency":{"type":"string","description":"a valid ISO 4217 curreny code"},"additional_fees":{"type":"number","description":"additional custom fees to be payed"},"drop_off_location":{"type":"string","description":"location where the package will be dropped of with the carrier"},"exporter_reference":{"type":"string","description":"a note for the exporter"},"importer_reference":{"type":"string","description":"a note for the importer"},"posting_date":{"type":"string","format":"date","description":"date of commital at carrier"},"invoice_number":{"type":"string","description":"invoice number for the order"},"total_value_amount":{"type":"number","minimum":0,"maximum":1000,"description":"the overall value of the shipments' contents"},"items":{"type":"array","description":"array of item objects","items":{"type":"object","properties":{"origin_country":{"type":"string","description":"Country as uppercase ISO 3166-1 alpha-2 code"},"description":{"type":"string","description":"a description of the item"},"hs_tariff_number":{"type":"string","description":"customs tariff number. See https://en.wikipedia.org/wiki/Harmonized_System#Tariffs_by_region for detailed information on region specific tariff numbers","maxLength":10},"quantity":{"type":"integer","description":"Number that defines how many items of this kind are in the shipment"},"value_amount":{"type":"string","description":"Value of a single item of this kind"},"net_weight":{"type":"number","description":"Net weight of a single item of this kind"},"gross_weight":{"type":"number","description":"Gross weight of a single item of this kind"}},"required":["origin_country","description","quantity","value_amount","net_weight"],"additionalProperties":false}}},"required":["contents_type","currency","total_value_amount","items"],"additionalProperties":false},"create_shipping_label":{"type":"boolean","description":"determines if a shipping label should be created at the carrier (this means you will be charged when using the production api key)"},"metadata":{"type":"object","description":"here you can save additional data that you want to be associated with the shipment. Any combination of key-value pairs is possible","additionalProperties":true}},"required":["carrier","to","package"],"additionalProperties":false,"definitions":{"address":{"type":"object","properties":{"id":{"type":"string","description":"identifier of a previously created address"},"company":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"care_of":{"type":"string"},"street":{"type":"string"},"street_no":{"type":"string"},"city":{"type":"string"},"zip_code":{"type":"string"},"state":{"type":"string"},"country":{"type":"string","description":"Country as uppercase ISO 3166-1 alpha-2 code"},"phone":{"type":"string","description":"telephone number (mandatory when the following terms apply - when carrier is UPS: service is one_day or one_day_early or ship to country is different than ship from country. Carrier is DHL Express: always provide phone number.)"},"email":{"type":"string","description":"Corresponding email address. Some carrier will need this to be provided (e.g. to notify the sender/receiver)."},"drop_off_point":{"type":"object","properties":{"drop_off_point_id":{"type":"string","description":"identifier for where the shipment should be dropped off"},"type":{"type":"string","description":"the type of the dropoff location","enum":["parcel_shop"]}},"required":["drop_off_point_id","parcel_shop"],"additionalProperties":false}},"required":["last_name","street","street_no","city","zip_code","country"],"additionalProperties":false},"label":{"type":"object","properties":{"format":{"type":"string","enum":["pdf_100x70mm","pdf_103x199mm","pdf_a5","pdf_a6","pdf_a7","zpl2_100x70mm_203dpi","zpl2_103x199mm_203dpi","zpl2_4x6in_203dpi","zpl2_4x6in_300dpi","zpl2_4x8in_203dpi"],"description":"defines the format that the returned label should have"},"size":{"type":"string","enum":["A5","A6","A7","100x70mm"],"description":"defines the size that the returned label should have","deprecated":true}},"additionalProperties":false,"description":"label specific definitions"},"label_voucher":{"type":"object","properties":{"format":{"type":"string","enum":["png"],"description":"File format the label voucher should be in"},"type":{"type":"string","enum":["qr_code"],"description":"The type of label voucher that should be returned"}},"required":["format","type"],"additionalProperties":false,"description":"label voucher specific definitions"},"package":{"type":"object","properties":{"width":{"type":"number"},"height":{"type":"number"},"length":{"type":"number"},"weight":{"type":"number"},"declared_value":{"type":"object","description":"Use this to book additional insurance or expand the liability for a shipment. Caution: Please keep in mind that additional fees are charged by the carrier.","properties":{"amount":{"type":"number"},"currency":{"type":"string"}}},"description":{"type":"string","description":"text that describes the contents of the package. This parameter is mandatory if you're using UPS with service 'returns'"},"type":{"type":"string","enum":["books","bulk","letter","parcel","parcel_letter","cargo_international_large_parcel"],"description":"defines packages of being of a certain type - if no value is given, parcel will be used"}},"required":["width","height","length","weight"],"additionalProperties":false,"description":"defines package dimensions"},"pickup":{"type":"object","properties":{"pickup_time":{"type":"object","properties":{"earliest":{"type":"string","format":"date-time"},"latest":{"type":"string","format":"date-time"}},"description":"defined time window when the carrier should pickup shipments","required":["earliest","latest"],"additionalProperties":false},"pickup_address":{"$ref":"#/definitions/address","description":"address where the shipment should be picked up"}},"required":["pickup_time"],"additionalProperties":false}}}