> ## Documentation Index > Fetch the complete documentation index at: https://sendcloud.dev/llms.txt > Use this file to discover all available pages before exploring further. # Create a shipment with rules and/or defaults and announce it synchronously > Create and announce a shipment applying shipping rules and/or defaults The main advantage of this endpoint over the [Create and announce a shipment synchronously](/api/v3/shipments/create-and-announce-a-shipment-synchronously) endpoint (and also the difference between them) is the ability to apply [shipping rules](https://app.sendcloud.com/v2/shipping/rules) and [shipping defaults](https://app.sendcloud.com/v2/shipping/shipping-defaults) to a shipment. Because of this, more fields in this endpoint are optional. If no shipping rules or defaults are configured to automatically assign the fields listed below, those fields must be provided to create a shipment successfully: * `from_address` (from Ship with address) * `ship_with` (from Ship with) * `parcels` (from Set number of parcels) **Note: the shipment (parcels) will be linked to the integration identified by the API credentials you supply as request authentication (`Basic ...`).** ## Shipping rules * **Due to the data (shipments) that we receive in this API, NOT all of the shipping rules (actions or conditions) can (and will) be applied.** * **Shipping rules do not fully apply to multicollo shipments. In such cases, the rule conditions for weight, parcel dimensions (height, length, width), total order value, item name, item quantity, item SKU and total parcel item value will not be matched. Additionally, the following actions will not be triggered:** * Using a box (Use box) * Setting the weight (Set weight) * Setting the number of parcels (Set number of parcels) * Insuring the shipment value (Insure shipment value by) * Insuring it by percentage (Insure shipment value by %) * Increasing item value by percentage (Decrease item value by %) * Setting item HS code (Set Item HS Code) * Setting item name (Set item name) * Setting item origin country (Set Item Origin Country) * Setting item value (Set item value) * Setting item weight (Set item weight) **Please consider these limitations when defining rules.** ### Shipping rules conditions (IF) that can be applied * Carrier * Checkout delivery method * Company name * Customer email * Integration * Item SKU * Item name * Item quantity * Parcel height (cm) * Parcel length (cm) * Parcel width (cm) * Phone number * Postal code * To country * Total order value * Total parcel item value * Weight (kg) ## Shipping rules actions (THEN) that can be applied * Add customs declaration statement * Use box * Decrease item value by % * Insure shipment value by * Insure shipment value by % * Set customs general notes * Set customer email * Set Item HS Code * Set item name * Set Item Origin Country * Set item value * Set item weight * Set number of parcels * Phone number * Ship with address * Ship with * Set weight * Use shipping contract ## OpenAPI ````yaml /.openapi/v3/shipments/openapi.yaml post /shipments/announce-with-shipping-rules openapi: 3.1.0 info: title: Shipments version: 3.0.0 description: >- The Shipments API allows you to create and announce, retrieve, and cancel outgoing shipments and their associated parcels within the Sendcloud platform. contact: name: Sendcloud API Support email: contact@sendcloud.com license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html servers: - url: https://panel.sendcloud.sc/api/v3 description: Sendcloud Production security: [] tags: - name: Shipments description: Shipments API paths: /shipments/announce-with-shipping-rules: post: tags: - Shipments summary: >- Create a shipment with rules and/or defaults and announce it synchronously description: Create and announce a shipment applying shipping rules and/or defaults operationId: sc-public-v3-scp-post-announce_shipment_with_rules parameters: - $ref: '#/components/parameters/SendcloudPartnerId' requestBody: content: application/json: schema: $ref: '#/components/schemas/shipment-request-with-rules' examples: CreateShipmentWithRulesAndDefaultsAndDeliveryIndicator: summary: >- Create a shipment with defaults and rules (using delivery_indicator) value: apply_shipping_defaults: true apply_shipping_rules: true delivery_indicator: DHL home delivery to_address: name: John Doe company_name: Sendcloud address_line_1: Insulindelaan 115 house_number: '115' postal_code: 5642CV city: Eindhoven country_code: NL phone_number: '+31612345678' email: john.doe@sendcloud.com po_box: PO Box 678 from_address: name: Marie Doe company_name: Sendcloud address_line_1: Stadhuisplein 10 address_line_2: 2e verdieping house_number: '10' postal_code: 5611 EM city: Eindhoven country_code: NL phone_number: '+31612345678' email: marie.doe@sendcloud.com po_box: PO Box 478 ship_with: type: shipping_option_code properties: shipping_option_code: postnl:standard contract_id: 517 order_number: '1234567890' total_order_price: currency: EUR value: '11.11' parcels: - dimensions: length: '5.00' width: '15.00' height: '20.00' unit: cm weight: value: '1.320' unit: kg parcel_items: - item_id: '5552' description: T-Shirt XL quantity: 1 weight: value: 0.3 unit: kg price: value: '12.65' currency: EUR hs_code: '620520' origin_country: NL sku: TS1234 product_id: '19284' mid_code: NLOZR92MEL material_content: 100% Cotton intended_use: Personal use dds_reference: 25FIYPEK0A7573 taric_doc_code: Y142 properties: size: XL color: green - item_id: '98712' description: Sneakers 42 quantity: 1 weight: value: 1.02 unit: kg price: value: '12.65' currency: EUR hs_code: '620520' origin_country: US sku: TS1234 product_id: '19284' mid_code: US1234567 material_content: 100% Cotton intended_use: Personal use dds_reference: 25FIYPEK0A7573 taric_doc_code: Y142 properties: size: 42 color: black CreateShipmentWithOnlyRules: summary: Create a shipment with only rules (not defaults) value: apply_shipping_defaults: false apply_shipping_rules: true to_address: name: John Doe company_name: Sendcloud address_line_1: Insulindelaan 115 house_number: '115' postal_code: 5642CV city: Eindhoven country_code: NL phone_number: '+31612345678' email: john.doe@sendcloud.com po_box: PO Box 678 from_address: name: Marie Doe company_name: Sendcloud address_line_1: Stadhuisplein 10 address_line_2: 2e verdieping house_number: '10' postal_code: 5611 EM city: Eindhoven country_code: NL phone_number: '+31612345678' email: marie.doe@sendcloud.com po_box: PO Box 478 ship_with: type: shipping_option_code properties: shipping_option_code: postnl:standard contract_id: 517 order_number: '1234567890' total_order_price: currency: EUR value: '11.11' parcels: - dimensions: length: '5.00' width: '15.00' height: '20.00' unit: cm weight: value: '1.320' unit: kg parcel_items: - item_id: '5552' description: T-Shirt XL quantity: 1 weight: value: 0.3 unit: kg price: value: '12.65' currency: EUR hs_code: '620520' origin_country: NL sku: TS1234 product_id: '19284' mid_code: NLOZR92MEL material_content: 100% Cotton intended_use: Personal use dds_reference: 25FIYPEK0A7573 taric_doc_code: Y142 properties: size: XL color: green - item_id: '98712' description: Sneakers 42 quantity: 1 weight: value: 1.02 unit: kg price: value: '12.65' currency: EUR hs_code: '620520' origin_country: US sku: TS1234 product_id: '19284' mid_code: US1234567 material_content: 100% Cotton intended_use: Personal use dds_reference: 25FIYPEK0A7573 taric_doc_code: Y142 properties: size: 42 color: black CreateShipmentWithOnlyDefaults: summary: Create a shipment with only defaults (not rules) value: apply_shipping_defaults: true apply_shipping_rules: false to_address: name: John Doe company_name: Sendcloud address_line_1: Insulindelaan 115 house_number: '115' postal_code: 5642CV city: Eindhoven country_code: NL phone_number: '+31612345678' email: john.doe@sendcloud.com po_box: PO Box 678 from_address: name: Marie Doe company_name: Sendcloud address_line_1: Stadhuisplein 10 address_line_2: 2e verdieping house_number: '10' postal_code: 5611 EM city: Eindhoven country_code: NL phone_number: '+31612345678' email: marie.doe@sendcloud.com po_box: PO Box 478 ship_with: type: shipping_option_code properties: shipping_option_code: postnl:standard contract_id: 517 order_number: '1234567890' total_order_price: currency: EUR value: '11.11' parcels: - dimensions: length: '5.00' width: '15.00' height: '20.00' unit: cm weight: value: '1.320' unit: kg parcel_items: - item_id: '5552' description: T-Shirt XL quantity: 1 weight: value: 0.3 unit: kg price: value: '12.65' currency: EUR hs_code: '620520' origin_country: NL sku: TS1234 product_id: '19284' mid_code: NLOZR92MEL material_content: 100% Cotton intended_use: Personal use dds_reference: 25FIYPEK0A7573 taric_doc_code: Y142 properties: size: XL color: green - item_id: '98712' description: Sneakers 42 quantity: 1 weight: value: 1.02 unit: kg price: value: '12.65' currency: EUR hs_code: '620520' origin_country: US sku: TS1234 product_id: '19284' mid_code: US1234567 material_content: 100% Cotton intended_use: Personal use dds_reference: 25FIYPEK0A7573 taric_doc_code: Y142 properties: size: 42 color: black CreateShipmentWithoutRulesAndDefaults: summary: Create a shipment without rules and defaults value: apply_shipping_defaults: false apply_shipping_rules: false to_address: name: John Doe company_name: Sendcloud address_line_1: Insulindelaan 115 house_number: '115' postal_code: 5642CV city: Eindhoven country_code: NL phone_number: '+31612345678' email: john.doe@sendcloud.com po_box: PO Box 678 from_address: name: Marie Doe company_name: Sendcloud address_line_1: Stadhuisplein 10 address_line_2: 2e verdieping house_number: '10' postal_code: 5611 EM city: Eindhoven country_code: NL phone_number: '+31612345678' email: marie.doe@sendcloud.com po_box: PO Box 478 ship_with: type: shipping_option_code properties: shipping_option_code: postnl:standard contract_id: 517 order_number: '1234567890' total_order_price: currency: EUR value: '11.11' parcels: - dimensions: length: '5.00' width: '15.00' height: '20.00' unit: cm weight: value: '1.320' unit: kg parcel_items: - item_id: '5552' description: T-Shirt XL quantity: 1 weight: value: 0.3 unit: kg price: value: '12.65' currency: EUR hs_code: '620520' origin_country: NL sku: TS1234 product_id: '19284' mid_code: NLOZR92MEL material_content: 100% Cotton intended_use: Personal use dds_reference: 25FIYPEK0A7573 taric_doc_code: Y142 properties: size: XL color: green - item_id: '98712' description: Sneakers 42 quantity: 1 weight: value: 1.02 unit: kg price: value: '12.65' currency: EUR hs_code: '620520' origin_country: US sku: TS1234 product_id: '19284' mid_code: US1234567 material_content: 100% Cotton intended_use: Personal use dds_reference: 25FIYPEK0A7573 taric_doc_code: Y142 properties: size: 42 color: black description: '' responses: '201': description: Shipment response content: application/json: schema: description: Create a shipment type: object title: Announced shipment including label properties: data: $ref: '#/components/schemas/sync-shipment-with-rules-response' examples: CreatedSingleParcelDomesticShipment: summary: Domestic Shipment (with single parcel) created value: data: id: XXX-Shipment-id label_details: mime_type: application/pdf dpi: 72 order_number: '1234567890' total_order_price: currency: EUR value: '11.11' parcels: - id: 383707309 status: code: READY_TO_SEND message: Ready to send documents: - type: label size: a6 link: >- https://panel.sendcloud.sc/api/v3/parcels/383707309/documents/label dimensions: width: '15.00' length: '5.00' height: '20.00' unit: cm weight: value: '1.320' unit: kg tracking_url: >- https://tracking.eu-central-1-0.sendcloud.sc/forward?carrier=postnl&code=3SYZXG8498635&destination=NL&lang=en-us&source=NL&type=parcel&verification=5642+CV&servicepoint_verification=&created_at=2024-06-06 tracking_number: 3SYZXG8498635 additional_carrier_data: awb_tracking_number: null box_number: null created_at: '2024-06-06T17:11:14.616615Z' updated_at: '2024-06-06T17:11:14.648081Z' announced_at: '2024-06-06T17:11:14.712398Z' label_notes: - I live at the blue door - The doorbell isn't working package_type: package parcel_items: - item_id: '5552' description: T-Shirt XL quantity: 1 weight: value: 0.3 unit: kg price: value: '12.65' currency: EUR hs_code: '620520' origin_country: NL sku: TS1234 product_id: '19284' mid_code: NLOZR92MEL material_content: 100% Cotton intended_use: Personal use dds_reference: 25FIYPEK0A7573 taric_doc_code: Y142 properties: size: XL color: green - item_id: '98712' description: Sneakers 42 quantity: 1 weight: value: 1.02 unit: kg price: value: '12.65' currency: EUR hs_code: '620520' origin_country: US sku: TS1234 product_id: '19284' mid_code: US1234567 material_content: 100% Cotton intended_use: Personal use dds_reference: 25FIYPEK0A7573 taric_doc_code: Y142 properties: size: 42 color: black from_address: address_line_1: Stadhuisplein 10 address_line_2: 2e verdieping city: Eindhoven company_name: Sendcloud country_code: NL email: marie.doe@sendcloud.com house_number: '10' name: Marie Doe phone_number: '+31612345678' postal_code: 5611 EM po_box: PO Box 678 to_address: address_line_1: Insulindelaan address_line_2: '' city: Eindhoven company_name: Sendcloud country_code: NL email: john.doe@sendcloud.com house_number: '115' name: John Doe phone_number: '+31612345678' postal_code: 5642 CV po_box: PO Box 483 ship_with: type: shipping_option_code properties: shipping_option_code: postnl:standard contract_id: 517 customs_information: null carrier: code: postnl name: PostNL errors: [] applied_shipping_rules: - rule: id: 315157 name: Ship with PostNL for NL result: shipping_option_code: postnl:standard CreatedCustomsRequiredShipment: summary: Shipment (with Customs and a single parcel) created value: data: id: XXX-Shipment-id label_details: mime_type: application/pdf dpi: 72 order_number: '1234567890' total_order_price: currency: EUR value: '11.11' parcels: - id: 383707309 status: code: READY_TO_SEND message: Ready to send documents: - type: label size: a6 link: >- https://panel.sendcloud.sc/api/v3/parcels/383707309/documents/label dimensions: width: '15.00' length: '5.00' height: '20.00' unit: cm weight: value: '1.320' unit: kg tracking_url: >- https://tracking.eu-central-1-0.sendcloud.sc/forward?carrier=postnl&code=3SYZXG8498635&destination=NL&lang=en-us&source=NL&type=parcel&verification=5642+CV&servicepoint_verification=&created_at=2024-06-06 tracking_number: 3SYZXG8498635 additional_carrier_data: awb_tracking_number: null box_number: null created_at: '2024-06-06T17:11:14.616615Z' updated_at: '2024-06-06T17:11:14.648081Z' announced_at: '2024-06-06T17:11:14.712398Z' parcel_items: - item_id: '5552' description: T-Shirt XL quantity: 1 weight: value: 0.3 unit: kg price: value: '12.65' currency: EUR hs_code: '620520' origin_country: NL sku: TS1234 product_id: '19284' mid_code: NLOZR92MEL material_content: 100% Cotton intended_use: Personal use dds_reference: 25FIYPEK0A7573 taric_doc_code: Y142 properties: size: XL color: green - item_id: '98712' description: Sneakers 42 quantity: 1 weight: value: 1.02 unit: kg price: value: '12.65' currency: EUR hs_code: '620520' origin_country: US sku: TS1234 product_id: '19284' mid_code: US1234567 material_content: 100% Cotton intended_use: Personal use dds_reference: 25FIYPEK0A7573 taric_doc_code: Y142 properties: size: 42 color: black from_address: address_line_1: Stadhuisplein 10 address_line_2: 2e verdieping city: Eindhoven company_name: Sendcloud country_code: NL email: marie.doe@sendcloud.com house_number: '10' name: Marie Doe phone_number: '+31612345678' postal_code: 5611 EM po_box: PO Box 678 to_address: name: John Doe company_name: Company XYZ address_line_1: 10 Kamal Chunchie Way address_line_2: '' postal_code: E16 1ZE city: London country_code: GB phone_number: '+31612345678' email: john.doe@sendcloud.com state_province_code: GB-ENG po_box: PO Box 678 ship_with: type: shipping_option_code properties: shipping_option_code: dhl_express:worldwide/incoterm=dap contract_id: 4195 customs_information: invoice_number: INV-123 export_reason: commercial_goods export_type: private invoice_date: '2023-08-24' discount_granted: value: '14.99' currency: EUR freight_costs: value: '21.98' currency: EUR insurance_costs: value: '3.60' currency: EUR other_costs: value: '1.2' currency: EUR goods_description: Electronic components and accessories general_notes: >- Compliance: Goods comply with international safety standards (CE certified). additional_declaration_statements: - >- With reference to the above shipment, I understate that the content is not made of leather parts of animal species protected by the Washington Convention. - >- I solemnly declare that the contents of this document represent a true and accurate account of the events as they occurred. I acknowledge my responsibility for the information presented herein and understand that any misrepresentation or falsification may result in legal consequences or other penalties as applicable. importer_of_record: name: John Doe company_name: ImporterCo address_line_1: Maple Avenue address_line_2: '' house_number: '123' postal_code: '90210' city: Springfield country_code: US state_province_code: US-MA telephone: '+15551234567' email: info@importer-of-record-example.com tax_numbers: sender: - name: VAT country_code: NL value: NL123456789B01 - name: EORI country_code: NL value: NL123456789 receiver: - name: EIN country_code: US value: '123456789' importer_of_record: - name: EIN country_code: US value: '987654321' carrier: code: postnl name: PostNL errors: [] applied_shipping_rules: - rule: id: 315157 name: Ship with DHL Express for GB result: shipping_option_code: dhl_express:worldwide/incoterm=dap DomesticSingleParcelShipmentAnnouncementFailed: summary: >- Domestic with a single parcel shipment created, but announcement failed value: data: id: XXX-Shipment-id order_number: '1234567890' total_order_price: currency: EUR value: '11.11' parcels: - id: 383707309 created_at: '2018-01-01T21:45:30' updated_at: '2018-01-01T21:47:12' announced_at: '2018-01-01T21:47:13' tracking_number: 3SYZXG8498635 dimensions: length: '5.00' width: '15.00' height: '20.00' unit: cm weight: value: '1.320' unit: kg status: code: ANNOUNCEMENT_FAILED message: Announcement Failed additional_carrier_data: awb_tracking_number: null box_number: null parcel_items: - item_id: '5552' description: T-Shirt XL quantity: 1 weight: value: 0.3 unit: kg price: value: '12.65' currency: EUR hs_code: '620520' origin_country: NL sku: TS1234 product_id: '19284' mid_code: NLOZR92MEL material_content: 100% Cotton intended_use: Personal use dds_reference: 25FIYPEK0A7573 taric_doc_code: Y142 properties: size: XL color: green - item_id: '98712' description: Sneakers 42 quantity: 1 weight: value: 1.02 unit: kg price: value: '12.65' currency: EUR hs_code: '620520' origin_country: US sku: TS1234 product_id: '19284' mid_code: US1234567 material_content: 100% Cotton intended_use: Personal use dds_reference: 25FIYPEK0A7573 taric_doc_code: Y142 properties: size: 42 color: black to_address: name: John Doe company_name: Sendcloud address_line_1: Insulindelaan 115 address_line_2: '' house_number: '115' postal_code: 5642CV city: Eindhoven country_code: NL phone_number: '+31612345678' email: john.doe@sendcloud.com state_province_code: '' po_box: PO Box 678 from_address: name: Marie Doe company_name: Sendcloud address_line_1: Stadhuisplein 10 address_line_2: 2e verdieping house_number: 5A postal_code: 5611 EM city: Eindhoven country_code: NL phone_number: '+31612345678' email: marie.doe@sendcloud.com state_province_code: '' po_box: PO Box 483 ship_with: type: shipping_option_code properties: shipping_option_code: postnl:standard contract_id: 517 carrier: code: postnl name: PostNL errors: - status: '500' code: parcel_announcement_error detail: >- Service error: An error occurred while connecting to the carrier. applied_shipping_rules: - rule: id: 315157 name: Ship with PostNL for NL result: shipping_option_code: postnl:standard '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/errors' examples: Failed: summary: Failed to create shipment with a single parcel value: errors: - detail: This field is required. status: '400' source: pointer: /to_address/name code: required '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/errors' examples: NotFound: summary: Partner ID was not found. value: errors: - title: Not found detail: The partner ID was not found. status: '404' code: not_found security: - HTTPBasicAuth: [] - OAuth2ClientCreds: [] components: parameters: SendcloudPartnerId: in: header name: Sendcloud-Partner-Id description: >- If you are an official [Sendcloud Tech Partner](https://www.sendcloud.com/ecosystem/), send your unique Sendcloud Partner UUID as a request header for the system to recognize you. The header is not required but if it is set, the system will check it. An unknown or invalid UUID will cause a 400 error. schema: type: string schemas: shipment-request-with-rules: title: Asynchronous Announcement Shipment with Rules request Object description: Asynchronous Shipment with Rules request object model type: object allOf: - $ref: '#/components/schemas/shipment-request-with-optional-fields' - $ref: >- #/components/schemas/multicollo-parcels-array-request-with-optional-fields - type: object properties: apply_shipping_defaults: type: boolean description: >- When set to `true`, the "Default weight", "Preferred shipping method" and "Default export reason" [shipping defaults](https://app.sendcloud.com/v2/shipping/shipping-defaults) will be applied, if they were not provided by the request payload. **Note that the request payload values and shipping rules take precedence over these defaults.** default: true example: true apply_shipping_rules: type: boolean description: >- When set to `true`, [shipping rules](https://app.sendcloud.com/v2/shipping/rules) will be applied. **Note that rules take precedence over the values provided in the request payload and over the [shipping defaults](https://app.sendcloud.com/v2/shipping/shipping-defaults).** For instance, if a contract is specified in one of the applicable rules for the shipment that is being requested, the contract value provided in the request payload will be ignored. Also keep in mind that since orders created by the API do not appear in the Sendcloud platform's Incoming Orders overview, not all shipping rules can be applied. default: true example: true delivery_indicator: type: string description: > Free text that is intended for applying the **Checkout Delivery Method** condition in shipping rules. Learn more about [Shipping rules](/docs/shipping/shipping-rules/). example: DHL home delivery sync-shipment-with-rules-response: title: Sync shipment with rules response Object description: Sync shipment response object model including applied shipping rules. allOf: - $ref: '#/components/schemas/base-shipment-response' - properties: parcels: description: Represents each package of the shipment. type: array items: $ref: '#/components/schemas/sync-parcels-array-response' label_details: $ref: '#/components/schemas/label-details' applied_shipping_rules: description: >- List of shipping rules that were applied to the shipment and the result of each rule's modifications. type: array items: $ref: '#/components/schemas/applied-shipping-rule' type: object errors: title: Errors description: >- A standardized format for errors in [JSON:API](https://jsonapi.org/format/#error-objects) responses. type: array items: allOf: - $ref: '#/components/schemas/ErrorObject' - required: - status - code - detail shipment-request-with-optional-fields: title: Shipment request with optional fields Object description: Shipment request with optional fields object model allOf: - $ref: '#/components/schemas/shipment-common-with-optional-fields' - type: object properties: from_address: description: >- The sender address for the shipment. You can either provide a `sender_address_id` to reference a pre-configured sender address (with optional address field overrides), or provide all address fields directly. oneOf: - $ref: '#/components/schemas/address-with-sender-address-id' - $ref: '#/components/schemas/address-with-required-fields' customs_information: $ref: '#/components/schemas/customs-information-with-optional-fields' - type: object properties: to_service_point: $ref: '#/components/schemas/service-point-request' - type: object properties: label_details: $ref: '#/components/schemas/label-details' delivery_dates: oneOf: - $ref: '#/components/schemas/delivery-dates' - type: 'null' description: >- Defined delivery dates. The `handover_at` date indicates when the item will be handed over to the carrier by the merchant in ISO 8601. If this date is not passed the carrier default will be used. For most carriers this is the following working day. type: object multicollo-parcels-array-request-with-optional-fields: title: Parcels array request with optional fields Object description: Parcels array request with optional fields object model type: object properties: parcels: description: >- Represents each package of the shipment. Each carrier can have its own number of parcels limit per shipment, otherwise there is a restriction to a maximum of 50 parcels (default). type: array items: allOf: - $ref: '#/components/schemas/parcel-common-with-optional-fields' - type: object properties: parcel_items: type: array description: >- List of items/products that the parcel contains. **Note that parcel items array is required for shipments that require customs documents.** maxItems: 1000 items: $ref: '#/components/schemas/parcel-item-with-optional-fields' minItems: 1 maxItems: 50 base-shipment-response: title: Base shipment response Object description: Base shipment response object model type: object allOf: - $ref: '#/components/schemas/shipment-common' - type: object required: - from_address properties: from_address: $ref: '#/components/schemas/address-with-required-fields' description: The sender address for the shipment. id: description: >- ID of the shipment (required to retrieve or cancel a specific shipment) type: string readOnly: true to_service_point: $ref: '#/components/schemas/service-point-response' errors: type: array items: $ref: '#/components/schemas/ErrorObject' readOnly: true description: >- This errors object will contain errors such as carrier announcement errors or validation errors. delivery-dates: $ref: '#/components/schemas/delivery-dates' type: object carrier: type: object description: Carrier used for the shipment. readOnly: true properties: code: type: string title: Carrier Code description: A carrier represented by a Sendcloud unique identifier. example: postnl name: type: string title: Carrier Name description: Carrier friendly name. example: PostNL sync-parcels-array-response: title: Sync Parcels Array Response Object description: Sync parcel common object model type: object allOf: - $ref: '#/components/schemas/parcels-array-response' - type: object properties: label_file: type: - string - 'null' format: byte description: >- The base64 representation of the label file. **Note that it will be returned if there is only one parcel in the shipment.** label-details: title: Label details Object description: >- Describes the format and resolution of the label. **Note**: If you request a label in ZPL format and the carrier supports native ZPL, then it won't be possible to download the label in any other format later. type: object properties: mime_type: type: string default: application/pdf enum: - application/pdf - application/zpl - image/png example: application/zpl description: The format of the label dpi: type: integer description: >- The resolution of the label in **dots per inch**. ZPL labels are not affected by the DPI setting, as the resolution is determined by the carrier itself. Most carriers use a resolution of 203 DPI. Zebra printers need to be configured to print at the specific DPI of the label if they have higher resolution capabilities. default: 72 enum: - 72 - 203 - 300 - 600 example: 300 applied-shipping-rule: title: Applied shipping rule modification description: >- Represents a shipping rule that was applied to the shipment and the result of the changes it made. type: object properties: rule: type: object description: The shipping rule that was applied. properties: id: type: integer description: The unique identifier of the shipping rule. example: 315157 name: type: string description: The name of the shipping rule. example: Ship with PostNL for NL required: - id - name result: type: object description: >- The changes that were applied by the shipping rule. The keys represent the fields that were modified and the values represent the new values. Possible keys: `additional_declaration_statements`, `box`, `change_return_fee`, `contract`, `email`, `hs_code`, `number_of_shipments`, `origin_country`, `telephone`, `sender_address`, `shipping_option_code`, `total_insured_value`, `disable_return_requests`, `weight`. additionalProperties: true example: shipping_option_code: postnl:standard required: - rule - result ErrorObject: title: Error type: object description: Error in a JSON:API error format properties: id: type: string description: A unique identifier for the error. links: type: object description: >- A set of hyperlinks that provide additional information about the error. properties: about: type: string description: A URL that provides additional information about the error. status: type: string format: int32 description: The HTTP status code of the error. minLength: 1 code: type: string description: A unique error code for the error, in snake case format. minLength: 1 enum: - unknown_field - invalid - forbidden - invalid_choice - min_value - 'null' - not_found - required - not_a_list - non_field_errors - authentication_failed - validation_error - parcel_announcement_error title: type: string description: A short, human-readable summary of the error. minLength: 1 detail: type: string description: A human-readable explanation of the error. minLength: 1 source: type: object description: >- An object that identifies the source of the error within the request payload. properties: pointer: type: string description: >- A `JSON` pointer to the location of the error within the request payload. parameter: type: string description: The name of the `query` parameter that caused the error. header: type: string description: The name of the `header` parameter that caused the error. meta: type: object description: Additional metadata about the error. shipment-common-with-optional-fields: title: Shipment common with optional fields Object description: Shipment common with optional fields object model type: object properties: brand_id: description: > The `id` of the brand. Brands can be added through the [Sendcloud platform](https://app.sendcloud.com/v2/settings/brands/list) and be retrieved (alongside their `id`) from the [Retrieve a list of brands](/api/v2/brands/retrieve-a-list-of-brands) endpoint. example: 42 type: integer ship_with: $ref: '#/components/schemas/ship-with' to_address: $ref: '#/components/schemas/address-with-required-fields' order_number: type: string description: Order number generated manually or by shop system total_order_price: $ref: '#/components/schemas/optional-price' description: | The value paid by the buyer for the order. reference: description: > A reference that will be stored on the Shipment and returned in your responses. This is not sent to the carrier. type: - string - 'null' example: shipment-1234 external_reference_id: description: > An optional reference can be provided by the API user; if included, it must be unique across shipments of the user. Using the same reference more than once will result in a 409 HTTP status code and the associated object being returned. type: - string - 'null' example: unique-value-1234 validation_methods: type: array description: > A list of additional address validations to apply. At present, the only supported validation service is Here, and it is used exclusively for transactional contracts. To enable this feature, contract_id must be explicitly set and must reference a transactional contract. When using the "Here" validation method, Sendcloud will attempt to verify and correct the provided address based on the best available match from the selected provider. For example, if you submit "city": "Amstredan", the system will automatically correct it to "city": "Amsterdam". If no suitable match is found, the request will return an error. Please note that only address components recognised by the selected provider will be kept. Any additional details included in address fields (e.g. "address_line_2": "Ring the blue doorbell") will be removed if they do not match the provider records. For adding delivery notes or extra instructions, use the parcels.label_notes field instead. items: $ref: '#/components/schemas/address-validation-method-enum' example: - here required: - to_address address-with-sender-address-id: title: Sender Address ID type: object description: A sender address referenced by ID. properties: sender_address_id: description: >- The ID of a pre-configured sender address to ship from. A sender address can be added through the [Sendcloud platform](https://app.sendcloud.com/v2/settings/addresses/sender) and be retrieved using the [Retrieve a list of sender addresses](/api/v3/sender-addresses/retrieve-a-list-of-sender-addresses) endpoint. Note: if the sender address has a brand or tax numbers configured, those will be used by default. However, explicitly provided `brand_id` or `tax_numbers` in the request will always take precedence over the values from the sender address. example: 192 type: integer required: - sender_address_id address-with-required-fields: title: Address Object type: object description: Sendcloud Address object allOf: - $ref: '#/components/schemas/address' - required: - name - address_line_1 - postal_code - city - country_code customs-information-with-optional-fields: title: CustomsInformation with optional fields type: - object - 'null' description: >- Optional customs information that should be provided for international shipments. This information is used for generating customs documents. example: invoice_number: INV-123 export_reason: commercial_goods export_type: private invoice_date: '2023-08-24' discount_granted: value: '14.99' currency: EUR freight_costs: null insurance_costs: value: '3.60' currency: EUR other_costs: value: '1.2' currency: EUR goods_description: Electronic components and accessories general_notes: >- Compliance: Goods comply with international safety standards (CE certified). additional_declaration_statements: - >- With reference to the above shipment, I understate that the content is not made of leather parts of animal species protected by the Washington Convention. - >- I solemnly declare that the contents of this document represent a true and accurate account of the events as they occurred. I acknowledge my responsibility for the information presented herein and understand that any misrepresentation or falsification may result in legal consequences or other penalties as applicable. importer_of_record: name: John Doe company_name: ImporterCo address_line_1: Maple Avenue house_number: '123' postal_code: '90210' city: Springfield country_code: US state_province_code: US-MA telephone: '+15551234567' email: info@importer-of-record-example.com tax_numbers: sender: - name: VAT country_code: NL value: NL123456789B01 - name: EORI country_code: NL value: NL123456789 receiver: - name: EIN country_code: US value: '123456789' importer_of_record: - name: EIN country_code: US value: '987654321' properties: invoice_number: type: string minLength: 1 maxLength: 40 description: Customs invoice number. example: INV-123 export_reason: type: string description: >- Indicates the purpose or reason behind exporting the items. This classification helps customs authorities determine the applicable regulations, taxes, and duties. enum: - gift - documents - commercial_goods - commercial_sample example: commercial_goods export_type: type: string description: >- Export type documentation serves to categorize international shipments into three primary classifications: Private exports, intended for personal use; Commercial B2C exports, directed towards individual consumers; and Commercial B2B exports, involving business-to-business transactions. These distinctions facilitate adherence to regulatory requirements and ensure the orderly movement of goods across international boundaries. enum: - private - commercial_b2c - commercial_b2b default: commercial_b2c example: private invoice_date: type: string format: date description: >- The date when the commercial invoice for the goods was issued (ISO 8601). If not provided, the announcement date will be used by default. discount_granted: $ref: '#/components/schemas/optional-price' description: Shipper's granted discount amount to user. freight_costs: $ref: '#/components/schemas/optional-price' description: >- Charges associated with the transportation of the goods to their destination paid by the receiver. insurance_costs: $ref: '#/components/schemas/optional-price' description: >- The costs of insurance coverage for the goods during transit paid by the receiver. other_costs: $ref: '#/components/schemas/optional-price' description: >- Additional costs or charges associated with the shipment that are not covered by freight and insurance paid by the receiver. goods_description: type: string description: >- A description of the goods being shipped, used for customs clearance purposes. This field might not be supported by all carriers. maxLength: 255 example: Electronic components and accessories general_notes: type: string description: >- Exporter or shipper can include any additional information or special instructions related to the goods being shipped. This section is used to provide details that may not be covered in other parts of the invoice but are relevant for customs clearance. maxLength: 500 example: >- Compliance: Goods comply with international safety standards (CE certified). additional_declaration_statements: type: array description: >- List of additional declaration statements. Each statement may contain specific details about the nature of the goods being shipped, their origin, or any additional information required by customs authorities. The content of an additional declaration statement can vary based on the requirements of the importing and exporting countries, as well as the nature of the goods being transported. maxItems: 100 items: type: string example: >- With reference to the above shipment, I understate that the content is not made of leather parts of animal species protected by the Washington Convention. minLength: 1 maxLength: 1024 importer_of_record: type: - object - 'null' description: >- Importer of Record (IOR) information. A customs-connected record importer specializes in importing goods and managing the associated customs documentation. If not provided, the receiver's address will be used instead. properties: name: type: string description: Name of IOR minLength: 1 maxLength: 75 company_name: type: string description: IOR company name maxLength: 50 address_line_1: type: string description: Address of IOR minLength: 1 maxLength: 150 address_line_2: type: string description: Additional address information, e.g. 2nd level maxLength: 150 house_number: type: string description: IOR house number maxLength: 20 city: type: string description: IOR city minLength: 1 maxLength: 30 postal_code: type: string description: IOR postal code minLength: 1 maxLength: 12 country_code: type: string description: IOR country. ISO 3166-1 alpha-2 code minLength: 2 maxLength: 2 state_province_code: type: string description: >- Code of the state (e.g. NY for New York) or province (e.g. RM for Rome). Destinations that require this field are USA, Canada, Italy and Australia. Format ISO-3166-2. See [international shipping](/docs/shipments/international-shipping#required-fields-for-international-shipments) for details. example: IT-RM maxLength: 14 telephone: type: string description: IOR phone number in E.164 format maxLength: 20 email: type: string description: IOR email maxLength: 320 required: - name - address_line_1 - city - postal_code - country_code tax_numbers: type: object description: >- Identification numbers and codes related to sender, received and importer of record provider. properties: sender: type: array description: Sender's list of identification number objects maxItems: 20 items: $ref: '#/components/schemas/TaxNumber' receiver: type: array description: Receiver's list of identification number objects maxItems: 20 items: $ref: '#/components/schemas/TaxNumber' importer_of_record: type: array description: Importer of record's list of identification number objects items: $ref: '#/components/schemas/TaxNumber' maxItems: 20 required: - sender - receiver - importer_of_record required: - invoice_number service-point-request: title: Service Point description: >- Node for service point information. Use the [Retrieve a list of service points](/api/v2/service-points/retrieve-a-list-of-service-points) endpoint to find service points, or pass in the carrier's id for the service point. If both the `id` and `carrier_service_point_id` are provided, the `carrier_service_point_id` will be prioritised. type: object anyOf: - title: Sendcloud ID type: object properties: id: type: string description: The sendcloud `id` of a service point. example: '123' required: - id - title: Carrier Service Point ID type: object properties: carrier_service_point_id: type: string description: The carrier's id of a service point example: '123' required: - carrier_service_point_id delivery-dates: title: Delivery Dates description: Defined delivery dates type: - object properties: handover_at: type: - string - 'null' format: date-time description: >- The date when the item will be handed over to the carrier by the merchant in ISO 8601 example: '2025-02-27T10:00:00.555309+00:00' deliver_at: type: - string - 'null' format: date-time description: The date when the order should reach the end customer in ISO 8601 example: '2025-03-15T10:00:00.555309+00:00' parcel-common-with-optional-fields: title: Parcel common with optional fields Object description: Parcel common with optional fields model type: object properties: dimensions: $ref: '#/components/schemas/str-dimensions' description: >- While dimensions are optional, some carriers require them present. If this is the case, an error will be thrown. weight: $ref: '#/components/schemas/str-weight' additional_insured_price: $ref: '#/components/schemas/optional-price' description: >- Amount for which you want to add additional insurance (on top of carrier insurance) to the parcel with our insurance provider XCover. You can inure up from 2 euros to 5000 euros per shipment. label_notes: type: - array - 'null' description: >- Custom messages printed on the shipping label. Use this field to include custom text - such as invoice numbers, product IDs, or internal reference codes - on the package's shipping label. **Note that support for label messages varies by carrier; some carriers may ignore this field or offer alternatives, such as delivery instructions, which are communicated to the carrier but not printed on the label. Some carriers may apply label notes at the shipment level rather than per individual parcel.** maxItems: 255 items: type: string example: The doorbell isn’t working minLength: 1 maxLength: 255 sscc: type: - string - 'null' minLength: 18 maxLength: 18 pattern: ^\d{18}$ description: >- The Serial Shipping Container Code (SSCC) serves as a globally unique identifier for a logistic unit, functioning as a digital "license plate" for tracking and managing goods throughout the supply chain. example: '019844628346512933' package_type: type: - string - 'null' description: >- The package type defines how you pack your parcels. This field is mostly only required for carriers with specific needs, such as pallet carriers. For more information, reach out to your Sendcloud contact person. enum: - package - euro_pallet - block_pallet - mini_pallet - one_way_pallet - tube - over_size_pallet - bundle - half_pallet - letterbox - null example: package parcel-item-with-optional-fields: title: Parcel Item with optional fields Object description: >- A single item (with optional fields) in a shipment. **Note that parcel item object is required for shipments that require customs documents.** type: object properties: item_id: type: string description: Order Item external ID in shop system example: '5552' minLength: 1 description: type: string description: Description of the item example: T-Shirt XL minLength: 1 maxLength: 255 quantity: type: integer description: Quantity of items shipped minimum: 1 example: 1 weight: $ref: '#/components/schemas/weight' price: $ref: '#/components/schemas/required-price' hs_code: type: string description: >- Harmonized System Code. **This field is required if it's an international shipment** example: '620520' maxLength: 12 origin_country: type: string description: >- ISO-2 code of the country where the items were originally produced. **This field is required if it's an international shipment** example: NL sku: type: string description: The SKU of the product example: TS1234 product_id: type: string description: The internal ID of the product example: '19284' mid_code: title: MID Code type: - string - 'null' description: >- MID code is short for Manufacturer's Identification code and must be shown on the commercial invoice. It's used as an alternative to the full name and address of a manufacturer, shipper or exporter and is always required for U.S. formal customs entries. example: NLOZR92MEL material_content: title: Material Content type: - string - 'null' description: A description of materials of the order content. example: 100% Cotton intended_use: title: Intended Use type: - string - 'null' description: >- Intended use of the order contents. The intended use may be personal or commercial. example: Personal use dangerous_goods: $ref: '#/components/schemas/dangerous-goods' dds_reference: title: DDS Reference type: - string - 'null' description: >- The DDS (Due Diligence Statement) reference number associated with the item, if applicable. See EUDR system for more details. example: 25FIYPEK0A7573 taric_doc_code: title: TARIC document code type: - string - 'null' description: >- TARIC document codes are specific alphanumeric codes used in EU customs declarations (Box 44) to identify required supporting documents, certificates, or conditions for a product, like health certificates (e.g., 3200), origin proofs (e.g., EUR.1), or special authorizations (e.g., C716 for due diligence) for simplified procedures, ensuring compliance with EU trade rules for various goods. example: Y142 properties: type: object additionalProperties: true description: Any custom user-defined properties of order item or product example: size: red color: green required: - quantity shipment-common: title: Shipment common Object description: Shipment common object model type: object allOf: - $ref: '#/components/schemas/shipment-common-with-optional-fields' - type: object properties: customs_information: $ref: '#/components/schemas/customs-information' required: - ship_with service-point-response: title: Service Point description: Service point information returned in responses. type: object properties: id: type: string description: The `id` of a service point. example: '123' carrier_service_point_id: type: string description: The carrier's native id for the service point example: '91233' required: - id - carrier_service_point_id parcels-array-response: title: Parcels Array Response Object description: Parcel common object model type: object allOf: - $ref: '#/components/schemas/parcel-common' - type: object properties: created_at: type: string format: date-time description: The timestamp of when the parcel was created readOnly: true example: '2024-09-04T12:14:36.506925Z' updated_at: type: string format: date-time description: The timestamp of when the parcel was last updated readOnly: true example: '2024-09-04T12:14:47.203107Z' announced_at: type: - string - 'null' description: >- The timestamp of when the parcel was announced to the carrier (label was created) format: date-time readOnly: true example: '2024-09-04T12:14:47.153985Z' id: type: integer description: >- ID of the parcel (required to retrieve a parcel document for async announcement) readOnly: true status: $ref: '#/components/schemas/status' readOnly: true documents: type: array uniqueItems: true description: >- An array of documents. A parcel can contain multiple documents, for instance labels and a customs form. This field returns an array of all the available documents for this parcel. readOnly: true items: $ref: '#/components/schemas/documents' tracking_number: type: string description: Tracking number of the shipment. readOnly: true example: 3SYZXG8498635 tracking_url: type: - string - 'null' description: Tracking url of this shipment. readOnly: true additional_carrier_data: type: object title: Carrier-specific data readOnly: true description: Specific data that only belongs to some carriers. properties: awb_tracking_number: type: - string - 'null' description: >- Deutsche Post Global Mail only. This indicates the air waybill number of this box of Global Mail parcels. This will be set once the `Finalize box` has been called. box_number: type: - integer - 'null' description: >- Deutsche Post Global Mail only. This indicates the box to which this parcel belongs. This will be only set for Global Mail parcels. label_notes: type: - array - 'null' description: >- Custom messages printed on the shipping label. Use this field to include custom text - such as invoice numbers, product IDs, or internal reference codes - on the package’s shipping label. maxItems: 255 items: type: string example: The doorbell isn’t working minLength: 1 maxLength: 255 ship-with: title: Ship with object type: object description: > The ship with object can be used to define how you would like to send your shipment. You can use a `shipping_option_code`. This is a unique identifier that displays what carrier and what set of shipping functionalities you want to use. examples: - type: shipping_option_code properties: shipping_option_code: postnl:standard/insured=3000 contract_id: 517 properties: type: type: string description: > The way the shipping method and carrier will be selected. Nowadays the only possible value is 'shipping_option_code', which requires client to also send the `shipping_option_code` inside properties. enum: - shipping_option_code example: shipping_option_code properties: $ref: '#/components/schemas/shipping-option-code-properties' required: - type - properties optional-price: title: Optional price anyOf: - type: 'null' - $ref: '#/components/schemas/required-price' address-validation-method-enum: title: Address validation method enum type: string enum: - here address: title: Address Object type: object description: Sendcloud Address object properties: name: type: string example: John Doe description: Name of the person associated with the address minLength: 1 company_name: type: string example: Sendcloud description: Name of the company associated with the address address_line_1: type: string example: Stadhuisplein description: First line of the address house_number: type: string example: '50' description: House number of the address address_line_2: type: string description: Additional address information, e.g. 2nd level example: Apartment 17B postal_code: type: string example: 1013 AB description: Zip code of the address minLength: 1 city: type: string example: Eindhoven description: City of the address minLength: 1 po_box: type: - string - 'null' description: Code required in case of PO Box or post locker delivery state_province_code: type: string example: IT-RM description: >- The character state code of the customer represented as ISO 3166-2 code. This field is required for certain countries. See [international shipping](/docs/shipments/international-shipping#required-fields-for-international-shipments) for details. country_code: type: string example: NL description: The country code of the customer represented as ISO 3166-1 alpha-2 minLength: 1 email: type: string format: email example: johndoe@gmail.com description: Email address of the person associated with the address phone_number: type: string example: '+319881729999' description: Phone number of the person associated with the address TaxNumber: title: Tax Number Object description: >- Identification numbers and codes used in different contexts. These identifiers are used for taxation, customs, business registration, and other purposes, depending on the country and the specific regulatory requirements. Depending on these requirements you may need to pass one or several numbers related to sender, receiver or importer of record provider. These numbers and codes will be included into final Customs documents. type: object properties: name: type: string example: EORI description: | Tax number abbreviation * VAT - Value-Added Tax → VOEC number for Norway should be shared here as advised by the [Norwegian Tax Authorities](https://www.skatteetaten.no/globalassets/bedrift-og-organisasjon/voec/sending-and-marking-goods-through-postal-services-and-transporters.pdf) * EIN - Employer Identification Number * GST - Goods and Service Tax * SSN - Social Security Number * EORI - Economic Operators Registration and Identification for the European Union * DUN - Data Universal Numbering System * FED - Federal Tax ID * STA - State Tax ID * CNP - Brazil CNPJ/CPF Federal Tax * IE - Brazil type IE/RG Federal Tax * INN - Russia bank details section INN * KPP - Russia bank details section KPP * OGR - Russia bank details section OGRN * OKP - Russia bank details section OKPO * IOSS - SDT or Overseas Registered Supplier or Import One-Stop-Shop or GB VAT (foreign) registration or AUSid GST Registration or VAT on E-Commerce * FTZ - Free Trade Zone ID * DAN - Deferment Account Duties Only * TAN - Deferment Account Tax Only * DTF - Deferment Account Duties, Taxes and Fees Only * RGP - EU Registered Exporters Registration ID * DLI - Driver's License * NID - National Identity Card - A PID (Personal Identification Number) should be provided as NID (National Identity Card). * PAS - Passport * MID - Manufacturer ID * UKIMS - UK Internal Market Scheme -> customs clearance for shipping from Great Britain to Northern Ireland under the Windsor Framework, for more information see [Windsor Framework](https://www.gov.uk/government/publications/the-windsor-framework) enum: - VAT - EIN - GST - SSN - EORI - DUN - FED - STA - CNP - IE - INN - KPP - OGR - OKP - IOSS - FTZ - DAN - TAN - DTF - RGP - DLI - NID - PAS - MID - UKIMS country_code: type: string example: NL description: Issuing country code (ISO 3166-1 alpha-2 code) maxLength: 2 value: type: string example: NL123456789B01 description: Tax number itself maxLength: 100 required: - name - country_code - value str-dimensions: title: Dimensions type: object description: Dimensions in the specified unit properties: length: type: string description: length in specified unit example: '15' width: type: string description: width in specified unit example: '20.5' height: type: string description: height in specified unit example: '37' unit: $ref: '#/components/schemas/dimension-units' required: - length - width - height - unit str-weight: title: Weight type: object description: Weight in the specified unit properties: value: type: string description: Weight value example: '14.5' unit: $ref: '#/components/schemas/weight-units' required: - value - unit weight: title: Weight type: object description: Weight in the specified unit properties: value: type: number description: Weight value exclusiveMinimum: 0 example: 14.5 unit: $ref: '#/components/schemas/weight-units' required: - value - unit required-price: title: Price object description: Price, consisting of a value and currency. allOf: - $ref: '#/components/schemas/Price' - type: object required: - value - currency dangerous-goods: title: DangerousGoods type: object description: Hazardous materials information for items. properties: chemical_record_identifier: type: string nullable: true description: Chemical record identifier for the dangerous goods regulation_set: type: string enum: - IATA - ADR description: Regulation set governing the dangerous goods packaging_type_quantity: type: string nullable: true description: Quantity of packaging type packaging_type: type: string nullable: true description: Type of packaging used packaging_instruction_code: type: string nullable: true description: Packaging instruction code id_number: type: string nullable: true description: UN identification number class_division_number: type: string nullable: true description: Hazard class and division number quantity: type: string nullable: true description: Quantity of dangerous goods unit_of_measurement: type: string enum: - KG - G - L - ML description: Unit of measurement for dangerous goods quantity proper_shipping_name: type: string nullable: true description: Proper shipping name as defined by regulations commodity_regulated_level_code: type: string enum: - LQ - EQ description: Commodity regulated level code transportation_mode: type: string enum: - Highway - Ground - PAX - CAO description: Mode of transportation emergency_contact_name: type: string nullable: true description: Name of emergency contact person emergency_contact_phone: type: string nullable: true description: Phone number of emergency contact adr_packing_group_letter: type: string enum: - I - II - III description: ADR packing group classification local_proper_shipping_name: type: string nullable: true description: Local proper shipping name transport_category: type: string nullable: true description: Transport category for ADR regulations tunnel_restriction_code: type: string nullable: true description: Tunnel restriction code weight_type: type: string enum: - Net - Gross description: Type of weight measurement customs-information: title: CustomsInformation type: object allOf: - $ref: '#/components/schemas/customs-information-with-optional-fields' - required: - invoice_number - export_reason parcel-common: title: Parcel common Object description: Parcel common object model type: object allOf: - $ref: '#/components/schemas/parcel-common-with-optional-fields' - required: - weight - type: object properties: parcel_items: type: array description: >- List of items/products that the parcel contains. **Note that parcel items array is required for shipments that require customs documents.** maxItems: 1000 items: $ref: '#/components/schemas/parcel-item' status: title: Status Object type: object description: Status object for a parcel properties: code: type: string example: ANNOUNCING message: type: string example: Being announced documents: title: Documents Object type: object description: Documents object for a parcel properties: type: type: string deprecated: true description: The type of the document. See the list below for available types. enum: - label - cn23 - cp71 - commercial-invoice - cn23-default - air-waybill - qr document_type: type: string description: The type of the document. See the list below for available types. enum: - label - customs-declaration - air-waybill size: type: string description: The paper size of the document. enum: - a6 - a4 link: type: string description: >- A link to the document, which allows downloading of the document in PDF, PNG and ZPL and various DPI. shipping-option-code-properties: title: Shipping option properties Object description: >- Contains the required properties to be sent when API client informs the shipping method and carrier to be used type: object properties: shipping_option_code: type: - string - 'null' description: >- The shipping option that will be or is used for shipping your parcel. The code can be retrieved via the [Create a list of shipping options](/api/v3/shipping-options/create-a-list-of-shipping-options) endpoint. When `ship_with.type` is set to `shipping_option_code`, this field is mandatory. example: postnl:standard/insured=3000 contract_id: type: - integer - 'null' minimum: 1 description: >- The selected shipping contract. If you haven't specified a contract for shipping your parcel, we will automatically select the default contract for the carrier that matches your shipping option. You can retrieve your contract IDs from the [Retrieve a list of contracts](/api/v3/contracts/retrieve-a-list-of-contracts) endpoint. Otherwise, the default direct contract will be automatically selected. dimension-units: type: string title: Dimensional units enum: - cm - mm - m - yd - ft - in example: mm weight-units: type: string title: Mass Units Object enum: - kg - g - lbs - oz example: g Price: title: Price Object type: object properties: value: type: string example: '12.65' pattern: '[\d]+(\.[\d]+)?' currency: type: string description: ISO 4217 currency code minLength: 3 maxLength: 3 example: USD parcel-item: title: Parcel Item Object description: >- A single item in a shipment. **Note that parcel item object is required for shipments that require customs documents.** type: object allOf: - $ref: '#/components/schemas/parcel-item-with-optional-fields' - required: - hs_code - weight - description - price securitySchemes: HTTPBasicAuth: type: http description: >- Basic Authentication using API key and secrets is currently the main authentication mechanism. scheme: basic OAuth2ClientCreds: type: oauth2 description: >- OAuth2 is a standardized protocol for authorization that allows users to share their private resources stored on one site with another site without having to provide their credentials. OAuth2 Client Credentials Grant workflow. This workflow is typically used for server-to-server interactions that require authorization to access specific resources. flows: clientCredentials: tokenUrl: https://account.sendcloud.com/oauth2/token/ scopes: api: Default OAuth scope required to access Sendcloud API. ````