> ## 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 return synchronously > Create a return synchronously, i.e. wait for a response from the carrier before continuing. This endpoint will create a return, similarly to the [Create a return](/api/v3/returns/create-a-return) endpoint, but via a synchronous API request. This means that the API will wait for a response from the carrier before you can continue. This endpoint is primarily used for **debugging purposes** in the event that a return parcel announcement fails, as it will retrieve the carrier announcement error. Creating a return synchronously can impact the performance of the endpoint, as the process will take longer than calls to the [Create a return](/api/v3/returns/create-a-return) endpoint. **Note:** The `parcel_items` field is mandatory if you're creating a return from outside the EU. ## OpenAPI ````yaml /.openapi/v3/returns/openapi.yaml post /returns/announce-synchronously openapi: 3.1.0 info: title: Returns version: 3.0.0 contact: name: Sendcloud API Support url: https://www.sendcloud.dev email: contact@sendcloud.com license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html description: >- The Sendcloud **Returns API** lets you create standalone returns easily and efficiently, so you can seamlessly incorporate returns into your existing workflow, ERP or WMS system. This API can be used in conjunction with other core Sendcloud features or independently. servers: - url: https://panel.sendcloud.sc/api/v3 description: Sendcloud Production security: [] tags: - name: Returns description: Sendcloud's Returns API paths: /returns/announce-synchronously: post: tags: - Returns summary: Create a return synchronously description: >- Create a return synchronously, i.e. wait for a response from the carrier before continuing. operationId: sc-public-v3-scp-post-returns_create_new_return_synchronously parameters: - $ref: '#/components/parameters/SendcloudPartnerId' requestBody: $ref: '#/components/requestBodies/CreateReturn' responses: '201': description: Created content: application/json: schema: type: object properties: return_id: type: integer description: The sendcloud return id minimum: 1 parcel_id: type: integer minimum: 1 description: The sendcloud incoming parcel id multi_collo_ids: type: array description: >- A list with all the related sendcloud incoming parcel ids in the collo items: type: integer minimum: 1 required: - return_id - parcel_id - multi_collo_ids examples: example-1: value: return_id: 12345 parcel_id: 67880 multi_collo_ids: [] '400': $ref: '#/components/responses/400' 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 requestBodies: CreateReturn: content: application/json: schema: type: object properties: from_address: $ref: '#/components/schemas/address-with-required-fields' to_address: $ref: '#/components/schemas/address-with-required-fields' ship_with: $ref: '#/components/schemas/ShipWith' dimensions: $ref: '#/components/schemas/dimension' weight: $ref: '#/components/schemas/weight' collo_count: type: integer default: 1 minimum: 1 description: The number of collos this return consists of parcel_items: type: array description: List of items contained in this return. Required outside EU. items: $ref: '#/components/schemas/parcel-item-returns-create' send_tracking_emails: type: boolean default: false description: >- When true Sendcloud will send out the default track and trace emails brand_id: type: integer description: >- The ID of the brand this return belongs to. To find the brand ID, refer to the [Retrieve a list of brands](/api/v2/brands/retrieve-a-list-of-brands) endpoint. example: 1 minimum: 1 total_insured_value: $ref: '#/components/schemas/price' order_number: type: string description: Identifier of the order associated with this return example: ORD12355 total_order_value: $ref: '#/components/schemas/price-with-any-currency' external_reference: type: string description: Unique reference for this return, generated by the user example: RET9876 customs_invoice_nr: type: - string - 'null' description: >- Customs invoice number. **This field is required if it's an international return** delivery_option: $ref: '#/components/schemas/DeliveryOption' customs_information: $ref: '#/components/schemas/parcel-customs-information' apply_rules: type: boolean default: false description: >- When set to `true`, return rules will be applied. Note that rules take precedence over the values provided in the request. For instance, if a contract is specified in one of the applied rules, the contract value provided in the request will be ignored. required: - from_address - to_address - ship_with - weight examples: Return: value: from_address: name: My name company_name: Sendcloud address_line_1: Stadhuisplein house_number: '50' postal_code: 1013 AB city: Amsterdam country_code: NL phone_number: '+319881729999' email: test@test.com to_address: name: My name company_name: Sendcloud address_line_1: Stadhuisplein house_number: '50' postal_code: 1013 AB city: Amsterdam country_code: NL phone_number: '+319881729999' email: test@test.com ship_with: type: shipping_option_code shipping_option_code: dpd:return/return contract: 123456 dimensions: height: 10 width: 10 length: 10 unit: cm weight: value: 0.4 unit: kg collo_count: 1 parcel_items: - description: T-Shirt XL quantity: 1 weight: value: 0.4 unit: kg value: value: 6.15 currency: EUR hs_code: '6205.20' origin_country: NL sku: TS1234 product_id: '19283' send_tracking_emails: false brand_id: 1 total_insured_value: value: 6.15 currency: EUR order_number: ORD123456 total_order_value: value: 6.15 currency: EUR external_reference: RET98765 customs_invoice_nr: test_invoice_123 delivery_option: drop_off_point EUReturn: value: from_address: name: Hendrik company_name: Twitter address_line_1: Stadhuisplein address_line_2: string house_number: '50' postal_code: 1013 AB city: Amsterdam country_code: NL phone_number: '+319881729999' email: test@test.com to_address: name: Jacobus company_name: Facebook address_line_1: Corso Porta Nuova house_number: '83' postal_code: '42049' city: Sant'ilario D'enza state_province_code: RE country_code: IT phone_number: '+3903788201357' email: test@test.com ship_with: shipping_product_code: postnl:standard/return functionalities: labelless: true contract: 123456 dimensions: length: 15 width: 20.5 height: 37 unit: mm weight: value: 14.5 unit: g collo_count: 1 parcel_items: - description: T-Shirt XL quantity: 1 weight: value: 14.5 unit: g value: value: 0 currency: EUR hs_code: '6205.20' origin_country: NL sku: TS1234 product_id: '19284' send_tracking_emails: true brand_id: 1 total_insured_value: value: 0 currency: EUR order_number: ORD12355 total_order_value: value: 0 currency: EUR external_reference: RET9876 delivery_option: drop_off_point responses: '400': description: Bad Request content: application/json: examples: InvalidPostalCodeError: value: error: code: invalid_postal_code request: api/v2/brand/devtest/return-portal/outgoing message: The postal code you provided is invalid. schema: type: object properties: error: type: object properties: code: type: string description: The code of the error example: invalid_postal_code request: type: string description: The request the error is originated from example: api/v2/brand/devtest/return-portal/outgoing message: type: string description: A message describing the error example: >- External reference has already been used in another return. schemas: address-with-required-fields: title: Address Object type: object description: Sendcloud Address object oneOf: - $ref: '#/components/schemas/address' required: - name - address_line_1 - postal_code - city - country_code ShipWith: title: Ship With Object type: object description: Shipping specifications chosen for return properties: type: type: string description: > The way the shipping method and carrier will be selected. The default is `shipping_product_code`, but the `shipping_option_code` is the new and preferred way. enum: - shipping_option_code - shipping_product_code example: shipping_option_code default: shipping_product_code shipping_option_code: type: string example: dpd:return/return description: >- Shipping option code as provided by the [Shipping options API](/api/v3/shipping-options) and the `code` property of the corresponding response. Required if `type` is `shipping_option_code`. shipping_product_code: type: string example: dpd:return/return description: >- Shipping product code as provided by the [Shipping products API](/api/v2/shipping-products/retrieve-a-list-of-shipping-products) and the `code` property of the corresponding response. Required if `type` is `shipping_product_code`. functionalities: $ref: '#/components/schemas/carrier-shipping-functionalities' description: >- Shipping functionalities. Should only be provided if `type` is `shipping_product_code`. contract: type: integer description: ID of the contract to ship the return with dimension: title: Dimension type: object description: Dimension in the specified unit properties: length: type: number description: length in specified unit minimum: 0 example: 15 width: type: number description: width in specified unit minimum: 0 example: 20.5 height: type: number description: height in specified unit minimum: 0 example: 37 unit: $ref: '#/components/schemas/dimension-units' required: - length - width - height - 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 parcel-item-returns-create: title: Parcel Item Object description: A single item in a shipment type: object properties: item_id: type: - string - 'null' description: Order Item external ID in shop system example: '5552' description: type: string description: Description of the item example: T-Shirt XL quantity: type: integer description: Quantity of items shipped minimum: 1 example: 1 weight: $ref: '#/components/schemas/weight' price: $ref: '#/components/schemas/price-with-any-currency' value: $ref: '#/components/schemas/price-with-any-currency' deprecated: true description: >- Price in the specified currency. **Deprecated** in favour of the `price` field. hs_code: type: string description: >- Harmonized System Code. **This field is required if it's an international return** example: '6205.20' 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 return** 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' return_reason_id: type: - string - 'null' description: The ID of the return reason, if any. example: '1' return_message: type: - string - 'null' description: Extra information relating to the return reason example: Too big 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 properties: type: object additionalProperties: true description: Any custom user-defined properties of order item or product example: size: red color: green variant_id: type: - string - 'null' description: Variant ID of the product. Imported from a shop system readOnly: true example: size-l price: title: Price Object type: object properties: value: type: number currency: type: string description: ISO 4217 currency code enum: - EUR - GBP - USD description: Price in the specified currency price-with-any-currency: title: Price With Any Currency type: object properties: value: type: number currency: type: string description: ISO 4217 currency code pattern: '[A-Z]{3}' example: EUR description: Price in the specified currency required: - value - currency DeliveryOption: title: DeliveryOption x-stoplight: id: 1e5khic8yxpaw type: - string - 'null' description: |- The options the customer has for returning this parcel: - `drop_off_point`: At a drop-off point - Print at home - `drop_off_labelless`: At a drop-off point - No printer needed - `in_store`: Return in store - `pickup`: Arrange a pick-up minLength: 1 example: drop_off_point enum: - drop_off_point - drop_off_labelless - pickup - in_store - null parcel-customs-information: title: ParcelCustomsInformation type: - object - 'null' description: >- Optional customs information that should be provided for international parcels. 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 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' return_data: return_postal_code: 1111 AA outbound_tracking_number: JT1234567890 outbound_shipment_date: '2023-08-14' outbound_carrier_name: UPS 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. For Returns, this field must always be set to `returned_goods`. enum: - gift - documents - commercial_goods - commercial_sample - returned_goods 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. If currency is not passed then `total_order_value_currency` is selected by default. freight_costs: $ref: '#/components/schemas/optional-price' description: >- Charges associated with the transportation of the goods to their destination paid by the receiver. If currency is not passed then `total_order_value_currency` is selected by default. insurance_costs: $ref: '#/components/schemas/optional-price' description: >- The costs of insurance coverage for the goods during transit paid by the receiver. If currency is not passed then `total_order_value_currency` is selected by default. 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. If currency is not passed then `total_order_value_currency` is selected by default. 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. minLength: 1 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 return_data: type: - object - 'null' description: >- Additional information that must be provided for return parcels. All fields are nullable. However, a partially filled object is invalid. Either all fields should be provided, or none should be. properties: return_postal_code: type: string minLength: 1 maxLength: 12 description: >- The Postcode of the customer to whom the parcel was originally shipped. outbound_tracking_number: type: string description: Tracking number of outbound shipment example: BE123456789 minLength: 1 maxLength: 40 outbound_shipment_date: type: string format: date description: Data of outbound shipment example: '2020-11-27' outbound_carrier_name: type: string description: The name of the carrier used for outbound shipment example: DHL minLength: 1 maxLength: 50 required: - return_postal_code - outbound_tracking_number - outbound_shipment_date - outbound_carrier_name required: - invoice_number - export_reason 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 carrier-shipping-functionalities: title: Shipping Functionalities Object type: object x-examples: {} properties: age_check: description: >- Indicates the minimal age of the recipient to be able to receive a shipment sent with this product/method enum: - null - 16 - 18 type: - integer - 'null' b2b: description: Indicates whether this product/method can be used for B2B shipments type: boolean b2c: description: >- Indicates whether this product/method can be used for B2C shipments (shipments between a business and a person) type: boolean boxable: description: Indicates whether the shipment fits in a box type: boolean bulky_goods: description: >- Indicates that this method/product is suitable for sending bulky goods type: boolean carrier_billing_type: description: Indicates the carrier billing method enum: - country - zonal - null type: - string - 'null' cash_on_delivery: description: >- Indicates the maximum value of cash-on-delivery payment and that this method/product can be used for COD shipments type: - integer - 'null' dangerous_goods: description: >- Indicates that this product/method can be used to ship dangerous goods (ADR goods) type: boolean delivery_attempts: description: >- Indicates the future amount of attempts for home deliveries until the package is rerouted to the sender or a service point type: - integer - 'null' delivery_before: description: >- Indicates that a shipment sent with this method/product will be delivered before the time specified on the day of delivery. Should be expressed in military time format (HHMM) type: - string - 'null' pattern: \d{4} delivery_deadline: description: >- Indicates the delivery deadline, that is the guarantee of time to deliver by a carrier. These usually come with some requirements, e.g. same day delivery may only be available if a shipment is acquired by a carrier before noon on the same day. Values: * BEST_EFFORT(best_effort): the shipment will be delivered by a carrier ASAP * SAMEDAY(sameday): the shipment will be delivered by a carrier on the day of acquiring the shipment * NEXTDAY(nextday): the shipment will be delivered by a carrier on the day next to the day of acquiring the shipment * WITHIN_24H(within_24h): the shipment will be delivered by a carrier within 24 hours from acquiring the shipment * WITHIN_48H(within_48h): the shipment will be delivered by a carrier within 48 hours from acquiring the shipment * WITHIN_72H(within_72h): the shipment will be delivered by a carrier within 72 hours from acquiring the shipment enum: - best_effort - sameday - nextday - within_24h - within_48h - within_72h - null type: - string - 'null' direct_contract_only: description: >- Indicates that this method is only available for shipments with a direct (SaaS) contract type: boolean eco_delivery: description: >- Indicates that a shipment with this method will be delivered in an ecologically friendly way type: boolean first_mile: description: >- Indicates how a shipment should be acquired by a carrier using the chosen method. Values: * PICKUP(pickup): the shipment should be picked up by the carrier's drivers from the sender (one-time) * DROPOFF(dropoff): the shipment should be handed in for delivery at a service point * PICKUP_DROPOFF(pickup_dropoff): the shipment can be either picked up by a carrier's driver, or be handed in for delivery at a service point * FULFILMENT(filfilment): the shipment should be picked up by a recurrent pickup enum: - pickup - dropoff - pickup_dropoff - fulfilment - null type: - string - 'null' flex_delivery: description: >- Indicates whether flexible rerouting is available for a shipment sent with this product/method type: boolean form_factor: description: |- Indicates the form factor of a shipment in general terms Values: * LETTER(letter) * PARCEL(parcel) * MAILBOX(mailbox) * PALLET(pallet) * LONG(long) enum: - letter - parcel - mailbox - pallet - long - null type: - string - 'null' fragile_goods: description: >- Indicates that fragile goods may be delivered with this method/product type: boolean fresh_goods: description: >- Inicates that fresh/perishable goods may be delivered with this method/product type: boolean harmonized_label: description: >- Indicates whether a harmonized label (a shipping label combined with customs documents) will be created for a shipment using this product/method type: boolean id_check: description: >- Indicates whether a recipient will be asked to show a proof of identity when receiving a package. Related to AgeCheck, but not the same. type: boolean incoterm: description: >- Indicates the customs terms of shipping, e.g. who is responsible for paying taxes and duties for international shipments. Values: * DDU(ddu) - Delivery Duty Unpaid, recipient pays duties * DDP(ddp) - Delivery Duty Paid, sender pays duties * DAP(dap) - Delivery At Place, the seller is responsible for delivery of the goods, ready for unloading, at the named place of destination. * DAP NP(dap_np) - Delivery At Place (duties & taxes Not Paid), the seller is responsible for delivery of the goods, ready for unloading, at the named place of destination. Seller bears costs of shipping incl. clearance. Receiver bears the costs and risks of duties and VAT. * DAP DP(dap_dp) - Delivery At Place (duties & taxes Paid), the seller is responsible for delivery of the goods, ready for unloading, at the named place of destination. Seller bears the costs and risks of transport, clearance, duties and VAT. enum: - dap - ddp - ddu - dap_np - dap_dp - null type: - string - 'null' insurance: description: >- Indicates the amount of insurance provided by a carrier for a shipment with this method/product type: - integer - 'null' last_mile: description: >- Indicates the end destination of a shipment (i.e. where it will be delivered) Formerly known as Destination Type Values: * HOME_DELIVERY (home_delivery) - regular parcel delivery at home * SERVICE_POINT (service_point) - the shipment will be delivered to a service point * MAILBOX (mailbox) - the shipment will be delivered to a mailbox of a recipient (related to FormFactor.MAILBOX) * LOCKER (locker) - the shipment will be delivered to a locker * LOCKER_OR_SERVICE_POINT (locker_or_servicepoint) - - the shipment will be delivered to a locker or a service point enum: - home_delivery - service_point - mailbox - locker - locker_or_service_point type: - string - 'null' manually: description: >- Indicates a subset of Deutsche Post shipping methods where a consumer should manually attach the label to the parcel. type: boolean multicollo: description: >- Indicates whether multicollo shipments are possible with this product/method. Multicollo shipments consist of multiple packages which are created and sent at the same moment to the same receiver address. All parcels of a multicollo shipment will be delivered to the recipient at once. type: boolean neighbor_delivery: description: >- Indicates the neighbour delivery availability. If the recipient is unavailable at the moment of delivery, the shipment sent with this method/product can be delivered to neighbours. type: boolean non_conveyable: description: >- Indicates that a shipment sent with this product/method shouldn't be transported by conveyors. type: boolean personalized_delivery: description: >- Indicates a subset of Deutsche Post shipping methods shipping to a consumer. type: boolean premium: description: >- Indicates whether the carrier identifies the shipments shipping process as premium. type: boolean priority: description: >- Indicates the priority of a shipment. Values: * ECONOMICAL(economical): cheap but slow * STANDARD(standard): regular * PRIORITY(priority): prioritzed delivery, might be the same as EXPRESS * EXPRESS(express): Express delivery enum: - economical - standard - priority - express - null type: - string - 'null' registered_delivery: description: Indicates that the delivery of this shipment will be registered. type: boolean returns: description: Indicates that this product/method can be used for return shipments type: boolean segment: description: >- Internal functionality we use to support different pricing for PostNL shipments for users of different segments enum: - a+ - a - b - c - d - null type: - string - 'null' service_area: description: >- Indicates the service area of this product/method, for example — where it can be used Values: * DOMESTIC (domestic): available for domestic (national) shipments * DOMESTIC_REMOTE (domestic_remote): available for shipments to domestic remote territories (e.g. overseas) * INTERNATIONAL (international): available for international shipments enum: - domestic - domestic_remote - international - null type: - string - 'null' signature: description: >- Indicates that a recipient signature will be required on delivery of a shipment sent with this product/method. type: boolean size: description: |- Indicates the size of a shipment. Note that the concept of a size may vary per carrier and per form factor. Values: * XS(xs) * S(s) * M(m) * L(l) * XL(xl) * XXL(xxl) enum: - xs - s - m - l - xl - xxl - null type: - string - 'null' sorted: description: >- Indicates whether the shipment(s) are handed over the carrier in a sorted fashion, decreasing costs. type: boolean surcharge: description: >- Indicates whether the carrier can surcharge the shipment later, based on (volumetric) weight. type: boolean tracked: description: Indicates that this shipment can be tracked. type: boolean tyres: description: >- Indicates that this shipping method/product can be used to ship tyres type: boolean weekend_delivery: description: |- Indicates whether deliveries with this method/product are available on the weekends Values: * SATURDAY (saturday) - can be delivered on Saturday * SUNDAY (sunday) - can be delivered on Sunday * WEEKENDS (weekends) - - can be delivered during the weekends' enum: - saturday - sunday - weekends - null type: - string - 'null' ers: type: boolean description: >- Indicates if a shipment with this method can be sent via the Easy Return Solution for e-commerce parcels platform. Many national carriers are part of this platform. pick_up: type: boolean description: >- Indicates that this shipping method/product will be picked up by the carrier labelless: type: boolean description: > Indicates that this shipping method/product can be announced with a QR code instead of a traditional label description: Shipping functionalities 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 optional-price: title: Optional price anyOf: - type: 'null' - $ref: '#/components/schemas/required-price' 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 required-price: title: Price object description: Price, consisting of a value and currency. allOf: - $ref: '#/components/schemas/Price' - type: object required: - value - currency 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 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. ````