openapi: 3.1.0 info: title: Return portal version: 2.0.0 description: The Return portal API provides you with the tools to manage your own return portal, and create returns through that portal. contact: name: Sendcloud API Support url: https://www.sendcloud.dev email: contact@sendcloud.com termsOfService: https://www.sendcloud.com/terms-conditions/ license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html servers: - url: https://panel.sendcloud.sc/api/v2 description: Sendcloud Production tags: - name: Return portal description: Sendcloud's Return portal paths: /brand/{brand_domain}/return-portal: parameters: - schema: type: string minLength: 1 example: my-shop name: brand_domain in: path required: true description: The domain of the brand configured for your return portal. get: summary: Retrieve return portal settings tags: - Returns Portal security: [] responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ReturnPortalSettings' examples: ReturnPortalSettings: summary: Return portal settings value: portal: reasons: - id: 1 description: Changed my mind support_url: https://www.sendcloud.com/contact/ return_policy_url: https://www.sendcloud.com/privacy-policy/ enable_branded_footer: false enable_branded_header: false layout: type: standard helper_text: 'Include # if present in your order number' background_image: null enable_paid_returns: false brand: id: 1 name: Sendcloud B.V color: '#112857' secondary_color: '#112855' website: https://www.sendcloud.com overlay_logo: {} screen_logo: url: https://media.sendcloud.sc/brands/1/Sendcloud.png print_logo: url: https://media.sendcloud.sc/brands/1/Sendcloud.png overlay_thumb: {} screen_thumb: https://media.sendcloud.sc/brands/1/a05d525e580da030907607d901e10288_thumbnail.png print_thumb: https://media.sendcloud.sc/brands/1/a05d525e580da030907607d901e10288_thumbnail.png notify_reply_to_email: info@sendcloud.com domain: sendcloud-shop notify_bcc_email: info@sendcloud.com hide_powered_by: false google_analytics_id: G-1234567890 features: tracking_page: true tracking_email: true tracking_sms: false tracking_whatsapp: false returns_portal: true customization_settings: header: faq_url: https://support.sendcloud.com/hc/en-us contact_url: https://sendcloud.com/contact shop_url: https://sendcloud.com/storefront font_color: '#212121' homepage_url: https://sendcloud.com background_color: '#ffffff' footer: city: Eindhoven street: Stadhuisplein country: Netherlands font_color: '#212121' postal_code: 5611 EM phone_number: '+310612345678' social_media: twitter: sendcloud facebook: SendCloudNL linkedin: sendcloud instagram: sendcloud pinterest: sendcloud support_email: contact@sendcloud.com background_color: '#ffffff' whatsapp_business: '+310612345678' enable_refunds: true refund_options: - code: money label: Money back require_message: false return_fee: '0.00' return_fee_currency: EUR delivery_options: - drop_off_point return_address: country: NL return_locations: - id: 21487 country_name: Netherlands country_state: string company_name: Sendcloud address_1: Stadhuisplein house_number: '10' address_2: string city: Eindhoven postal_code: 5611 EM senderaddress_labels: - string '404': $ref: '#/components/responses/404' operationId: sc-public-v2-scp-get-returns_portal_details description: Retrieve information about the settings you have configured for your Sendcloud-hosted Return portal, including branding details, delivery options and return methods. x-mint: href: /api/v2/return-portal/retrieve-return-portal-settings content: |- **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). Due to the public nature of this API, you could potentially use this data for your own self-hosted returns solution. parameters: - schema: type: string enum: - en-GB - de-DE - es-ES - fr-FR - nl-NL - it-IT - en-US example: en-US in: query name: language description: Loads the returns portal and the corresponding context translated to the selected language /brand/{brand_domain}/return-portal/outgoing: get: tags: - Returns Portal summary: Retrieve an outgoing parcel operationId: sc-public-v2-scp-get-outgoing security: [] x-mint: href: /api/v2/return-portal/retrieve-an-outgoing-parcel content: |- **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). On a successful lookup, along with the parcel data, you will receive two JWT tokens: one for the incoming parcel creation, and one for service points lookup. responses: '200': description: OK content: application/json: schema: type: object properties: data: type: object required: - parcel - products - carriers - national_carrier_contact - national_carrier - carrier_drop_off_finder - shipping_products properties: parcel: type: object description: The outgoing parcel for which you want to create a return. required: - id - address - address_2 - address_divided - house_number - city - company_name - country - email - name - postal_code - telephone - tracking_number - order_number - to_coordinates - collo_count - weight - carrier properties: id: type: - 'null' - integer description: The outgoing parcel ID. It can be `null` if you are creating returns using the Return portal without the outgoing parcel feature. minimum: 1 format: int64 address: type: string minLength: 1 description: The ougoing parcels originating address address_2: type: string description: The originating parcels second address (Optional) minLength: 0 address_divided: type: object description: The ougoing parcels address divided required: - street - house_number properties: street: type: string minLength: 1 description: The outgoing parcels street address house_number: type: string minLength: 1 description: The client's house number. house_number: type: string minLength: 1 description: The client's house number. city: type: string minLength: 1 company_name: type: string minLength: 0 description: The client's company name. country: type: object required: - iso_2 - iso_3 - name properties: iso_2: type: string minLength: 2 maxLength: 2 example: NL description: The clients's country in ISO 2 format. iso_3: type: string minLength: 3 maxLength: 3 example: NLD description: The clients's country in ISO 3 format. name: type: string minLength: 1 description: The clients's country in a readable format. to_state: type: - 'null' - string description: The clients's country state in a readable format. email: type: string minLength: 0 description: The client's email address. name: type: string minLength: 1 description: The client's name. postal_code: type: string minLength: 1 description: The client's postal code. telephone: type: string minLength: 0 description: The client's phone number. tracking_number: type: string minLength: 1 description: The parcels tracking number. order_number: type: string minLength: 0 description: The parcels order number. to_coordinates: type: object description: Coordinates of the closest service point. required: - latitude - longitude properties: latitude: type: number format: float longitude: type: number format: float collo_count: type: - 'null' - integer minimum: 1 description: The number of parcels to be returned. Can be at most equal to the number of parcels shipped. weight: type: string minLength: 1 description: Weight in float format carrier: type: object description: | The carrier the parcel was sent with required: - code properties: code: type: string minLength: 1 description: Identifier of this carrier products: type: array minItems: 0 description: The products that are part of this outgoing shipment. items: type: object properties: id: type: string description: Identifier of this item name: type: string description: Product name price: type: string description: Price in float format quantity: type: integer description: Number of items image_url: type: string format: uri description: URL pointing to an image of this item returnable: type: boolean description: Whether this item can be returned required: - id - name - price - quantity - returnable carriers: type: array uniqueItems: true minItems: 1 description: List of carriers available for this return items: type: object properties: code: type: string minLength: 1 description: Identifier of this carrier name: type: string minLength: 1 description: Human readable name for this carrier logo: type: object properties: full: type: string minLength: 1 description: Location of the full size logo for this carrier format: uri-reference icon: type: string minLength: 1 description: Location of the icon for this carrier format: uri-reference required: - full - icon required: - code - name service_point: $ref: '#/components/schemas/service-point' shop_distances: type: array description: List of distances to the nearest service points items: type: object properties: id: type: number description: Identifier of the service point example: 1 minimum: 1 distance: type: number example: 1 minimum: 1 description: Distance to the service point in meters national_carrier_contact: type: string minLength: 1 format: uri description: Contact page for the national carrier national_carrier: type: object description: Object describing the national carrier for the client's country required: - name - drop_off_finder properties: name: type: string minLength: 1 description: Name of the carrier drop_off_finder: type: string minLength: 1 description: Url for looking up service points for the carrier logo: type: object description: An object containing the logo and the icon of the carrier properties: full: type: string description: Full size logo of the carrier format: uri example: https://sendcloud-prod-scp-static-files.s3.amazonaws.com/ups/img/logo.svg icon: type: string description: A carrier icon format: uri example: https://sendcloud-prod-scp-static-files.s3.amazonaws.com/ups/img/icon.svg code: type: string example: ups description: The Sendcloud recognized carrier code carrier_drop_off_finder: type: object description: Key-value pairs of carrier codes and their respective lookup url for service points labelless_service_point: $ref: '#/components/schemas/service-point' shipping_products: type: array uniqueItems: true minItems: 1 description: List of all available shipping products for this return items: $ref: '#/components/schemas/ReturnShippingProduct' applicable_actions: description: List of policy rule actions applicable to this parcel. These will be applied when an incomming return is created. Please take note of these when building your interface. type: array items: $ref: '#/components/schemas/ReturnRule' service_points_token: type: string minLength: 1 description: Access token that can be used to fetch service points at `https://servicepoints.sendcloud.sc/api/v2/service-points` access_token: type: string minLength: 1 description: Access token that can be used when interacting with the Return portal API required: - data - service_points_token - access_token examples: OutgoingParcel: summary: Outgoing parcel value: data: parcel: id: 1 address: string address_2: string address_divided: street: string house_number: string house_number: string city: string company_name: string country: iso_2: NL iso_3: NLD name: string to_state: string email: string name: string postal_code: string telephone: string tracking_number: string order_number: string to_coordinates: latitude: -3.402823669209385e+38 longitude: -3.402823669209385e+38 collo_count: 1 weight: string carrier: code: string products: - id: string name: string price: string image_url: https://example.com/image.png quantity: 0 returnable: true carriers: - code: string name: string logo: full: ../dictionary icon: ../dictionary service_point: id: 10875349 code: '217165' is_active: true shop_type: null extra_data: partner_name: PostNL sales_channel: AFHAALPUNT terminal_type: NRS retail_network_id: PNPNL-01 name: Media Markt Eindhoven Centrum B.V. street: Boschdijktunnel house_number: '1' postal_code: 5611AG city: EINDHOVEN latitude: '51.441444' longitude: '5.475185' email: '' phone: '' homepage: '' carrier: postnl country: NL formatted_opening_times: '0': - 10:00 - 20:00 '1': - 10:00 - 20:00 '2': - 10:00 - 20:00 '3': - 10:00 - 20:00 '4': - 10:00 - 20:00 '5': - 10:00 - 18:00 '6': [] open_tomorrow: true open_upcoming_week: true distance: 381 shop_distances: - id: 1 distance: 1 national_carrier_contact: https://example.com national_carrier: name: string drop_off_finder: string logo: full: https://sendcloud-prod-scp-static-files.s3.amazonaws.com/ups/img/logo.svg icon: https://sendcloud-prod-scp-static-files.s3.amazonaws.com/ups/img/icon.svg code: ups carrier_drop_off_finder: {} labelless_service_point: id: 10875349 code: '217165' is_active: true shop_type: null extra_data: partner_name: PostNL sales_channel: AFHAALPUNT terminal_type: NRS retail_network_id: PNPNL-01 name: Media Markt Eindhoven Centrum B.V. street: Boschdijktunnel house_number: '1' postal_code: 5611AG city: EINDHOVEN latitude: '51.441444' longitude: '5.475185' email: '' phone: '' homepage: '' carrier: postnl country: NL formatted_opening_times: '0': - 10:00 - 20:00 '1': - 10:00 - 20:00 '2': - 10:00 - 20:00 '3': - 10:00 - 20:00 '4': - 10:00 - 20:00 '5': - 10:00 - 18:00 '6': [] open_tomorrow: true open_upcoming_week: true distance: 381 shipping_products: - name: PostNL Standard return carrier: postnl service_points_carrier: postnl functionalities: age_check: 0 b2b: true b2c: true boxable: true bulky_goods: true carrier_billing_type: country cash_on_delivery: true dangerous_goods: true delivery_attempts: 0 delivery_before: string delivery_deadline: best_effort direct_contract_only: true eco_delivery: true ers: true first_mile: dropoff flex_delivery: true form_factor: parcel fragile_goods: true fresh_goods: true harmonized_label: true id_check: true incoterm: ddp insurance: 0 labelless: true last_mile: home_delivery manually: true multicollo: true neighbor_delivery: true non_conveyable: true personalized_delivery: true premium: true priority: standard registered_delivery: true returns: true segment: a+ service_area: domestic signature: true size: s sorted: true surcharge: true tracked: true tyres: true weekend_delivery: saturday methods: - id: 1 name: PostNL Return functionalities: age_check: 0 b2b: true b2c: true boxable: true bulky_goods: true carrier_billing_type: country cash_on_delivery: true dangerous_goods: true delivery_attempts: 0 delivery_before: string delivery_deadline: best_effort direct_contract_only: true eco_delivery: true ers: true first_mile: dropoff flex_delivery: true form_factor: parcel fragile_goods: true fresh_goods: true harmonized_label: true id_check: true incoterm: ddp insurance: 0 labelless: true last_mile: home_delivery manually: true multicollo: true neighbor_delivery: true non_conveyable: true personalized_delivery: true premium: true priority: standard registered_delivery: true returns: true segment: a+ service_area: domestic signature: true size: s sorted: true surcharge: true tracked: true tyres: true weekend_delivery: saturday shipping_product_code: string properties: min_weight: 0 max_weight: 0 max_dimensions: length: 0 width: 0 height: 0 unit: string pickup_date: null code: string applicable_actions: - id: ship_with name: Ship with field: ship_with priority: 1 value: dhl:complete/dropoff,return,labelless condition: all: - id: from_country operator: eq value: NL service_points_token: string access_token: string '400': $ref: '#/components/responses/400' '404': $ref: '#/components/responses/404' '422': $ref: '#/components/responses/422' description: | Find an outgoing parcel via two mandatory query parameters: either the tracking number or the order number, and the postal code. parameters: - schema: type: string minLength: 1 in: query name: postal_code description: The postal code of the outgoing parcel. required: true - schema: type: string minLength: 1 in: query name: identifier required: true description: Either the tracking number or the order number of the outgoing parcel. - schema: type: boolean default: false in: query name: omit_service_points description: |- If true, exclude response fields with basic service point information: * service_point * labelless_service_point * shop_distances parameters: - schema: type: string minLength: 1 name: brand_domain in: path required: true description: The domain you defined in the brand settings. /brand/{brand_domain}/return-portal/incoming: parameters: - schema: type: string name: brand_domain in: path required: true description: The domain you defined in the brand settings. post: summary: Create a return operationId: sc-public-v2-scp-post-incoming x-mint: href: /api/v2/return-portal/create-a-return content: |- **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). The outgoing parcel and related data needed to make a request to this endpoint can be retrieved from the [Retrieve an outgoing parcel](/api/v2/return-portal/retrieve-an-outgoing-parcel) endpoint. This endpoint also returns the JWT Token needed for authentication with this endpoint. responses: '200': description: OK content: application/json: schema: description: '' type: object properties: poller_url: type: string minLength: 1 return: type: integer incoming_parcels: type: array items: type: integer payment_url: type: string description: 'The payment URL will be available when paid returns is enabled and a payment provider is connected. For more info on how it works please take a look at at our [help center](https://support.sendcloud.com/hc/en-us/articles/5987289174420-Charge-customers-for-a-return-fee-via-the-return-portal) article. ' required: - poller_url - return - incoming_parcels examples: ReturnCreated: summary: Return was created value: poller_url: https://panel.sendcloud.sc/api/v2/brand/sendcloud-development/return-portal/label/polling?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE2MzQyMjA3MDgsImlkIjoxMTg1MDgyfQ.vSkcEU2wChq5Tq5_lGSRLtC03S4ZG_HgRk5JU7i3ZH4 return: 1185082 incoming_parcels: - 133726727 payment_url: https://mollie.com/paymen-url/pm_213123123 '400': $ref: '#/components/responses/400' requestBody: content: application/json: schema: type: object properties: reason: type: integer description: The return reason identifier matching the ones provided from Sendcloud. message: type: string description: A message relating to the return. minLength: 0 outgoing_parcel: type: integer description: The ID of the outgoing parcel for this return. service_point: type: object description: The service point that the customer has selected for returning the parcel required: - id properties: id: type: integer description: The ID of the service point format: int64 refund: type: object description: Details about the refund the customer is requesting required: - refund_type - message properties: refund_type: type: object description: Identifier of the refund type required: - code properties: code: type: string enum: - money - credit - exchange message: type: string description: Additional information about the refund as written by the user delivery_option: type: string minLength: 1 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 enum: - drop_off_point - in_store - pickup products: type: array minItems: 0 description: The products or items being returned items: type: object required: - description - product_id - quantity - value properties: description: type: string description: A description of the item maxLength: 255 example: Shoes hs_code: type: string description: |- [Harmonized System Code](https://en.wikipedia.org/wiki/Harmonized_System). Providing a complete HS code with more characters increases the delivery rate. Required for international shipments. maxLength: 12 example: 4202 21 origin_country: type: string description: ISO-2 code of the country where the items were originally produced. See the complete list [here](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). maxLength: 2 format: iso-2 example: NL product_id: type: string description: The internal ID of the item maxLength: 255 example: '123456789' properties: type: object description: Extra properties for the item (for example, size or colour) example: size: M colour: red quantity: type: integer minimum: 1 description: Quantity of items shipped example: 1 sku: type: string description: The SKU of the item maxLength: 255 example: '123456789' value: type: number description: Value of a single item example: 10.5 weight: type: string minLength: 1 description: Weight of a single item in kilograms example: '19' return_reason: type: integer description: The identifier of the return reason minimum: 1 example: 1 return_message: type: string description: An optional message relating to the return example: The item was too small incoming_parcel: type: object required: - from_address_1 - from_city - from_company_name - from_country - from_email - from_house_number - from_name - from_postal_code - from_telephone properties: collo_count: type: integer default: 1 description: The number of parcels to be returned. Can be at most equal to the number of parcels shipped. from_address_1: type: string minLength: 1 description: The client’s address. from_address_2: type: string description: Additional address details. from_city: type: string minLength: 1 description: The client’s city. from_company_name: type: string description: The client’s company name. from_country: type: string minLength: 1 description: The clients’s country in ISO 2 format. from_email: type: string minLength: 1 description: The client’s email address. from_house_number: type: string minLength: 1 description: The client’s house number. Pass 'N/A' if there is no house number. from_country_state: type: string minLength: 1 description: The ISO 3166-2 identifier for the state, if applicable from_name: type: string minLength: 1 description: The client’s name. from_postal_code: type: string minLength: 1 description: The client’s postal code. from_telephone: type: string minLength: 1 description: The client’s phone number. selected_functionalities: type: object description: 'Shipping functionalities that need to be used for this return. ' properties: first_mile: type: string description: |- The chosen method for returning this parcel: * dropoff: At a drop-off point * pickup: Arrange a pick-up * pickup_dropoff: Either option enum: - dropoff - pickup - pickup_dropoff selected_carrier_code: type: string minLength: 1 description: The identifier of the carrier that needs to be used for this return. Available carriers are listed in the response from the `/brand/{brand_domain}/return-portal/outgoing` endpoint pickup_date: type: string description: The chosen date for the return parcel to be picked up images: type: array description: A list of images to attach to the return maxItems: 10 items: type: object required: - filename - product_id properties: filename: type: string format: uri example: https://example.com/images/f67153f9043c46e08a6b137d927a7010.png description: The filename of the image, retrieved when the image is uploaded product_id: type: string example: '123456' description: The ID of product that this image is related to. Required only if there are items in the return, and cannot be passed if there are no items in the return. description: type: string example: My broken camera, with a crack on the lens description: A description of the uploaded image customs_information: type: object description: Optional customs information that should be provided for international returns. This information is used for generating customs documents. example: customs_invoice_nr: INV-123 export_type: private invoice_date: '2023-08-24' discount_granted: '14.99' freight_costs: '4.65' insurance_costs: '3.60' other_costs: '1.20' 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_1: Maple Avenue house_number: '123' postal_code: '90210' city: Springfield country_code: US country_state: 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: customs_invoice_nr: type: string description: Customs invoice number example: INV-123 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). discount_granted: type: string description: Shipper's granted discount amount to user. example: '14.99' freight_costs: type: string description: Charges associated with the transportation of the goods to their destination paid by the receiver. example: '4.65' insurance_costs: type: string description: The costs of insurance coverage for the goods during transit paid by the receiver. example: '3.60' other_costs: type: string description: Additional costs or charges associated with the shipment that are not covered by freight and insurance paid by the receiver. example: '1.20' 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. maxLength: 1024 importer_of_record: type: object 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 maxLength: 75 company_name: type: string description: IOR company name maxLength: 50 address_1: type: string description: Address of IOR maxLength: 150 address_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 maxLength: 30 postal_code: type: string description: IOR postal code maxLength: 12 country_code: type: string description: IOR country. ISO 3166-1 alpha-2 code maxLength: 2 country_state: 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. 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_1 - city - postal_code - country_code tax_numbers: type: object description: Identification numbers and codes related to sender, receiver and importer of record provider. properties: sender: type: array description: Sender's list of identification number objects maxItems: 100 items: $ref: '#/components/schemas/TaxNumber' receiver: type: array description: Receiver's list of identification number objects maxItems: 100 items: $ref: '#/components/schemas/TaxNumber' importer_of_record: type: array description: Importer of record's list of identification number objects maxItems: 100 items: $ref: '#/components/schemas/TaxNumber' required: - sender - receiver - importer_of_record return_data: type: object description: Additional information that should be provided for return parcels. properties: return_postal_code: type: string 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 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 maxLength: 50 required: - customs_invoice_nr required: - reason - message - outgoing_parcel - refund - delivery_option - products - incoming_parcel examples: SingleReturn: summary: A single return value: reason: 0 message: string outgoing_parcel: 0 service_point: id: 10875349 refund: refund_type: code: money message: string delivery_option: drop_off_point products: - product_id: '1234' quantity: 1 description: golden pen value: 1 return_reason: 1 incoming_parcel: collo_count: 1 from_address_1: string from_address_2: string from_city: string from_company_name: string from_country: IT from_email: string from_house_number: string from_country_state: IT-AN from_name: string from_postal_code: string from_telephone: string selected_functionalities: first_mile: dropoff selected_carrier_code: string pickup_date: string description: OK description: Create a new return parcel based on an outgoing parcel. tags: - Return portal parameters: [] security: - JWTtoken: [] /brand/{brand_domain}/return-portal/label/polling: get: summary: Retrieve the status of a return operationId: sc-public-v2-scp-get-label_polling x-mint: href: /api/v2/return-portal/retrieve-the-status-of-a-return content: |- **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). Once a return parcel has been successfully created, a polling URL is included in the response. Creating a label depends on the response time of the carrier, so you need to make a request to this endpoint to see the status of the label. The URL you received contains a token with the `id`, so you don't need to provide any additional lookup details or authentication. - A `200` response will indicate that the label is ready and can be downloaded. - A `202` response will indicate that the label is not ready to be downloaded but the return data has been accepted. If you have paid returns enabled this status is used to indicate we are waiting for payment. For more information take a look at [this help center article](https://support.sendcloud.com/hc/en-us/articles/5987289174420-Charge-customers-for-a-return-fee-via-the-return-portal). - A `500` response means that the label announcement failed. responses: '200': description: OK content: application/json: schema: type: object properties: download_url: type: string description: A URL pointing to the downloadable label format: uri return: type: integer description: ID of the created return parcels: type: array description: ID(s) of the created parcels of the return items: type: integer tracking_numbers: type: array description: Tracking number(s) of the created parcels items: type: string customs_declaration_url: type: string format: uri description: If available the customs-declaration can be downloaded here required: - download_url - return - parcels - tracking_numbers examples: ReturnCreated: summary: Successful creation of a return value: download_url: https://panel.sendcloud.sc/api/v2/brand/my-brand/return-portal/label/download?token=xxxxxxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxxxx return: 123456 parcels: - 7654321 tracking_numbers: - 3SYZXG123456789 '202': description: Accepted '404': $ref: '#/components/responses/404' parameters: - schema: type: string in: query name: token description: Polling token, used to find the return description: Find out the label creation status for a return parcel. tags: - Return portal security: - JWTtoken: [] parameters: - schema: type: string name: brand_domain in: path required: true description: The domain of the brand configured for your return portal. /brand/{brand_domain}/return-portal/label/download: get: summary: Retrieve a return label description: Download a return label as a PDF tags: - Return portal x-mint: href: /api/v2/return-portal/retrieve-a-return-label content: |- **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). Once a return parcel has been successfully created and announced to the carrier, the label will be ready to download. This endpoint returns the return label file (in PDF format). You should not need to manually construct the URL for this endpoint, as it is returned in the response body for the [Retrieve the status of a return](/api/v2/return-portal/retrieve-the-status-of-a-return) endpoint. responses: '200': description: OK content: application/pdf: schema: type: string format: binary '404': $ref: '#/components/responses/404' operationId: sc-public-v2-scp-get-label_download security: - JWTtoken: [] parameters: - schema: type: string in: query name: token description: Token that is used to find the right parcel. required: true parameters: - schema: type: string name: brand_domain in: path required: true description: The domain of the brand configured for your return portal. /brand/{brand_domain}/return-portal/uploads: parameters: - schema: type: string name: brand_domain in: path required: true description: The brand domain, found in the brand or return portal settings post: summary: Create a file upload for the return portal description: Upload an image for use in the return portal. x-mint: href: /api/v2/return-portal/create-a-file-upload-for-the-return-portal content: |- **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). This endpoint allows users to upload media that may be used during the return creation purposes. The response from this endpoint contains filenames used to identify the files in later requests. Currently only images are supported. Note: - Files are only kept for 48 hours after upload, unless used somewhere else (for example, when creating a return). - The URLs returned in this response will only be available for 48 hours. - The endpoint allows a maximum of 10 files, so groups larger than that should be batched. - Files should be smaller than 10MB. This API is currently in in beta, and may change in the near future. operationId: sc-public-v2-scp-post-uploads tags: - Return portal security: - JWTtoken: [] requestBody: content: multipart/form-data: schema: type: object additionalProperties: type: string format: binary description: The files to be uploaded, with a maximum file size of 10MB. responses: '201': description: Created content: application/json: schema: type: array items: type: object required: - name - filename - path properties: filename: type: string description: An identifier for the file, used to reference the file in later requests. name: type: string description: The name sent when uploading the file. path: type: string format: uri description: A URL that can be used to view the uploaded file. Only valid for 48 hours. examples: FileUpload: summary: File was uploaded value: - filename: 1dca5757ed2a47dd89ddc99ce308e6b4.webp name: product-12345-abc path: https://cdn.example.com/link/1dca5757ed2a47dd89ddc99ce308e6b4.webp - filename: ed013a200348477bb2c79fc27bb33dc8.webp name: product-67891-cde path: https://cdn.example.com/link/ed013a200348477bb2c79fc27bb33dc8.webp '400': $ref: '#/components/responses/400' components: schemas: ReturnPortalSettings: type: object properties: portal: type: object required: - reasons - support_url - return_policy_url - brand - enable_refunds - refund_options - return_fee - return_fee_currency - delivery_options - return_address - enable_branded_footer - enable_branded_header - layout - enable_paid_returns properties: reasons: type: array uniqueItems: true minItems: 1 description: The selected return reasons for this portal items: $ref: '#/components/schemas/ReturnReasons' support_url: type: string description: The support URL you provided. example: https://www.sendcloud.com/contact/ format: uri return_policy_url: type: string description: The return policy URL you provided. example: https://www.sendcloud.com/privacy-policy/ format: uri brand: $ref: '#/components/schemas/brand' enable_refunds: type: boolean description: The choice for enabling refunds. refund_options: type: array uniqueItems: true minItems: 1 description: The selected refund options. items: type: object properties: code: type: string minLength: 1 enum: - money - credit - exchange description: |- | Code | label | |----------|-------------------------------------------------------------------| | money | Let your customers request their money back | | credit | Let your customers choose to receive a gift card or discount code | | exchange | Let your customer exchange their order with other items | example: money label: type: string minLength: 1 example: Money back require_message: type: boolean default: false required: - code - label - require_message return_fee: type: string minLength: 1 description: The set value for the return fee, in float format. example: '0.00' return_fee_currency: type: string minLength: 1 example: EUR description: Currency of the return fee in three-letter ISO 4217 format enum: - EUR - USD delivery_options: type: array 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 items: type: string example: drop_off_point enum: - drop_off_point - in_store - drop_off_labelless - pickup return_address: type: object description: Object describing the return address for this portal (country only). required: - country properties: country: type: string minLength: 1 example: NL description: country of the return address in two-letter ISO 3166 format enable_branded_footer: type: boolean default: false description: Defines if the branded footer is enabled. enable_branded_header: type: boolean default: false description: Defines if the branded header is enabled. layout: type: object description: Portal's layout and appearance settings. required: - type properties: type: type: string enum: - standard - background_image helper_text: type: string description: Extra information displayed underneath the return portal search bar. example: 'Include # if present in your order number' background_image: description: Background image url for portal when layout type is "background_image". type: - 'null' - string format: uri enable_paid_returns: type: boolean default: false description: Defines if the paid returns is enabled. return_locations: type: array uniqueItems: true minItems: 0 description: A list of return addresses marked as store locations. items: type: object properties: id: type: integer example: 21487 description: Identifier of this location country_name: type: string minLength: 1 example: Netherlands description: Full name of the country country_state: type: - string - 'null' description: Name of the state/province company_name: type: string minLength: 1 example: Sendcloud description: Name of the location address_1: type: string minLength: 1 example: Stadhuisplein description: Street address house_number: type: string minLength: 1 example: '10' description: House number address_2: type: string description: Additional address information city: type: string minLength: 1 example: Eindhoven description: Name of the city postal_code: type: string minLength: 1 example: 5611 EM description: Postal code senderaddress_labels: type: array description: List of the sender addresses this return location belongs to items: type: string required: - id - country_name - company_name - address_1 - house_number - address_2 - city - postal_code required: - portal - return_locations ReturnReasons: title: Return Reasons type: object description: | The available return reasons for a returns portal. | Return Reason ID | Description | | ---------------- | -------------------------------------------- | | 1 | Product did not match expectations | | 3 | Other (explain in message) | | 4 | Incorrect product ordered | | 6 | Product did not match description on website | | 7 | Wrong product shipped | | 8 | No reason | | 9 | Rent | | 10 | Does not work | | 11 | Changed my mind | | 12 | Did not meet expectations | | 13 | Excessive amount | | 14 | Better price available | | 15 | Accidental order | | 16 | No longer needed | | 17 | Sample products | | 18 | Looks different than expected | | 19 | Ordered more than one size | | 20 | Arrived too late | | 21 | Poor quality / Faulty | | 22 | Does not fit properly | | 23 | Does not suit me | | 24 | Incorrect product received | | 25 | Parcel damaged on arrival | | 26 | Wrong size ordered | | 27 | Wrong color ordered | | 28 | Does not function as expected | | 29 | Recycle or reuse packaging | | 30 | Size too large | | 31 | Size too small | | 32 | Holiday season return | properties: id: type: integer example: 1 minimum: 1 description: The Sendcloud unique identifier of the return reason enum: - 1 - 3 - 4 - 6 - 7 - 8 - 9 - 10 - 11 - 12 - 13 - 14 - 15 - 16 - 17 - 18 - 19 - 20 - 21 - 22 - 23 - 24 - 25 - 26 - 27 - 28 - 29 - 30 - 31 - 32 description: type: string enum: - Recycle or reuse packaging - Other (explain in message) - Incorrect product ordered - Product did not match description on website - Wrong product shipped - No reason - Rent - Does not work - Changed my mind - Did not meet expectations - Excessive amount - Better price available - Accidental order - No longer needed - Sample products - Looks different than expected - Ordered more than one size - Arrived too late - Poor quality / Faulty - Does not fit properly - Does not suit me - Incorrect product received - Parcel damaged on arrival - Wrong size ordered - Does not function as expected description: The return reason description example: Changed my mind ReturnShippingProduct: type: object title: Returns Shipping Product Object description: A Sendcloud return shipping product properties: name: type: string description: A human friendly name for the functionality. example: PostNL Standard return carrier: type: string description: The Sendcloud carrier code example: postnl service_points_carrier: type: string description: A servicepoints carrier code example: postnl functionalities: $ref: '#/components/schemas/shipping-functionalities' methods: type: array items: type: object properties: id: type: integer example: 1 format: int32 description: Unique identifier of the shipping method. name: type: string description: Name of the shipping method, it should give an idea what the shipping method can be used for. example: PostNL Return functionalities: description: Shipping functionalities specific to this shipping method allOf: - $ref: '#/components/schemas/shipping-functionalities' complete_functionalities: description: Shipping functionalities of this shipping method, including those of the parent shipping product allOf: - $ref: '#/components/schemas/shipping-functionalities' shipping_product_code: type: string properties: type: object properties: min_weight: type: integer max_weight: type: integer max_dimensions: type: object properties: length: type: integer width: type: integer height: type: integer unit: type: string pickup_date: type: - string - 'null' code: type: string ReturnRule: title: Return Rule Object type: object description: When creating a return via the Returns Portal some [return rules](https://app.sendcloud.com/v2/settings/return-rules/) might be applicable. properties: field: type: string example: ship_with enum: - ship_with - return_fee description: This specifies the field that will be updated. id: type: string example: ship_with enum: - ship_with - change_return_fee - parcel_not_returnable - item_not_returnable description: This identifies the rule that is being applied. name: type: string example: Ship with priority: type: integer description: The priority of this rule. The rule with higher priority number takes precedence. format: int32 value: type: string example: dhl:complete/dropoff,return,labelless condition: oneOf: - type: object title: any properties: any: type: array description: the rule should be applied when ANY of the condition are valid items: type: object properties: id: type: string description: This identifies the condition that is being applied. example: from_country enum: - from_country - item_name - reason operator: type: string example: eq enum: - in - not_in - ends_with - eq - ne - pattern_match - starts_with value: type: string example: NL required: - id - operator - value - type: object title: all properties: all: type: array description: the rule should be applied when ALL of the condition are valid items: type: object properties: id: type: string description: This identifies the condition that is being applied. example: reason enum: - reason - item_name - from_country operator: type: string example: eq enum: - in - not_in - ends_with - eq - ne - pattern_match - starts_with value: type: string example: NL required: - id - operator - value description: condition that should lead to the rule being applied required: - field - id - name - value - condition brand: description: A user's configured brand within Sendcloud type: object title: Brand Object properties: id: type: integer minimum: 1 example: 1 description: The unique identifier of the brand readOnly: true name: type: string minLength: 1 description: The brand name example: Sendcloud B.V color: type: string minLength: 7 description: Hex code of the primary brand color example: '#112857' maxLength: 7 pattern: ^#[a-fA-F0-9]{6} secondary_color: type: string minLength: 7 description: Hex code of the secondary brand color example: '#112855' maxLength: 7 pattern: ^#[a-fA-F0-9]{6} website: type: string minLength: 1 format: uri example: https://www.sendcloud.com description: The website of the specific brand, usually used for display purposes screen_logo: type: object description: The brand's logo used for display purposes minProperties: 0 maxProperties: 1 properties: url: type: string format: uri example: https://media.sendcloud.sc/brands/1/Sendcloud.png overlay_logo: type: object enum: - {} description: Deprecated. Returns an empty object to not break backward compatibility deprecated: true print_logo: type: object description: The brand's logo used for printing purposes (e.g. labels) minProperties: 0 maxProperties: 1 properties: url: type: string format: uri example: https://media.sendcloud.sc/brands/1/Sendcloud.png overlay_thumb: type: object enum: - {} nullable: true description: Deprecated. Returns an empty object to not break backward compatibility deprecated: true screen_thumb: type: string nullable: true format: uri example: https://media.sendcloud.sc/brands/1/a05d525e580da030907607d901e10288_thumbnail.png description: Thumbnail of the screen logo print_thumb: type: string nullable: true example: https://media.sendcloud.sc/brands/1/a05d525e580da030907607d901e10288_thumbnail.png format: uri description: Thumbnail of the print logo notify_reply_to_email: type: string nullable: true format: email example: info@sendcloud.com description: Email address used for `reply to` actions for tracking email notifications domain: type: string minLength: 1 description: A user-defined domain for use with the tracking page and the return portal features. example: sendcloud-shop notify_bcc_email: type: string nullable: true example: info@sendcloud.com format: email description: '[BCC email](https://en.wikipedia.org/wiki/Blind_carbon_copy) address used for `reply to` actions for tracking email notifications' hide_powered_by: type: boolean description: Indicates if the "powered by Sendcloud" message should be displayed on features which display the user's brand, such as the tracking page default: false google_analytics_id: type: string example: G-1234567890 pattern: ^G-\d{10}$ description: A user-defined string representing the Google Analytics ID maxLength: 15 features: type: object description: List of features activated for the brand properties: tracking_page: type: boolean description: True if the tracking page is published, false otherwise tracking_email: type: boolean description: True if the Tracking email feature is active and the brand has at least one email template active, false otherwise tracking_sms: type: boolean description: True if Tracking SMS feature is active and the brand has at least one SMS template active, false otherwise tracking_whatsapp: type: boolean description: True if Tracking WhatsApp feature is active and the brand has at least one WhatsApp template active, false otherwise returns_portal: type: boolean description: True if the returns portal is active, false otherwise customization_settings: type: object nullable: true description: Header and footer customization settings for the brand properties: header: type: object nullable: true description: Indicates information to be shown in the header of the tracking pages and return portal properties: faq_url: type: string example: https://support.sendcloud.com/hc/en-us format: uri description: Link to the shop's FAQ contact_url: type: string example: https://sendcloud.com/contact format: uri description: Link to the shop's contact page shop_url: type: string example: https://sendcloud.com/storefront format: uri description: Link to the webshop font_color: type: string example: '#212121' description: Font colour to be used for displaying header information homepage_url: type: string example: https://sendcloud.com format: uri description: Link to the shop's homepage background_color: type: string example: '#ffffff' description: Background colour to be used for displaying header information footer: type: object description: Indicates information to be shown in the footer of the tracking page and return portal properties: city: type: string example: Eindhoven street: type: string example: Stadhuisplein country: type: string example: Netherlands font_color: type: string example: '#212121' postal_code: type: string example: 5611EM phone_number: type: string example: '+310612345678' social_media: type: object description: Social media handle of the shop. The absolute URLs are not sent. properties: twitter: type: string example: sendcloud description: The Twitter handle of the webshop facebook: type: string example: SendCloudNL description: The Facebook handle of the webshop linkedin: type: string example: sendcloud description: The LinkedIn handle of the webshop instagram: type: string example: sendcloud description: The Instagram handle of the webshop pinterest: type: string example: sendcloud description: The Pinterest handle of the webshop support_email: type: string example: contact@sendcloud.com format: email description: An email address for the shop's customer support background_color: type: string example: '#ffffff' description: Background colour to be used for displaying footer information whatsapp_business: type: string description: The WhatsApp contact number of the business/brand. example: '+310612345678' required: - id - name - domain - features service-point: title: ServicePoint Object description: A Sendcloud service point object. type: object example: id: 10875349 code: '217165' is_active: true shop_type: null general_shop_type: servicepoint extra_data: partner_name: PostNL sales_channel: AFHAALPUNT terminal_type: NRS retail_network_id: PNPNL-01 name: Example Parcel Shop street: Voorbeeldstraat house_number: '12' postal_code: 5611AG city: EINDHOVEN latitude: '51.441444' longitude: '5.475185' email: '' phone: '' homepage: '' carrier: postnl country: NL formatted_opening_times: '0': - 10:00 - 20:00 '1': - 10:00 - 20:00 '2': - 10:00 - 20:00 '3': - 10:00 - 20:00 '4': - 10:00 - 20:00 '5': - 10:00 - 18:00 '6': [] open_tomorrow: true open_upcoming_week: true properties: id: type: integer description: The unique identifier of the service point. code: type: string description: A carrier-specific identifier for the service point. is_active: type: boolean description: |- Indicates whether the service point data was recently updated via scraping within a carrier-specific expiration period. This field reflects data freshness, not operational availability. To check if a service point is operationally open, use `open_tomorrow` or `open_upcoming_week` instead. shop_type: type: string nullable: true description: The carrier-specific shop type classification. May be `null` if the carrier does not provide this information. general_shop_type: type: string description: |- A normalized shop type indicating the general category of the service point. Carrier-specific shop types are mapped to a fixed set of values, such as `servicepoint`, `locker`, `post_office`, `carrier_depot`, etc. nullable: true extra_data: type: object description: Contains carrier-specific metadata about the service point. This field has no fixed structure — it may contain different fields depending on the carrier, or be empty. Do not rely on any specific keys being present. name: type: string description: The name of the service point location. street: type: string description: The street name of the service point address. house_number: type: string description: The house number of the service point address. postal_code: type: string description: The postal code of the service point address. city: type: string description: The city where the service point is located. latitude: type: string description: The geographic latitude of the service point. longitude: type: string description: The geographic longitude of the service point. email: type: string description: The contact email address of the service point. phone: type: string description: The contact phone number of the service point. homepage: type: string description: The homepage URL of the service point. carrier: type: string example: postnl description: The code of the carrier operating this service point. country: type: string example: NL description: The country where the service point is located, formatted as an ISO 3166-1 alpha-2 code. formatted_opening_times: type: object description: |- The opening hours for each day of the week, keyed by day number (`0` = Monday, `6` = Sunday). Each day contains an array of time range strings. An empty array indicates the service point is closed on that day. This field is dynamically computed for the **current week**. It takes the regular opening hours as a base and applies any exceptions reported by the carrier (e.g. reduced hours or closures on holidays). For example, if a service point is normally open 07:00–22:00 every day but has reduced hours on Christmas Eve and is closed on Christmas Day, those overrides will be reflected in the output for that week. required: - '0' - '1' - '2' - '3' - '4' - '5' - '6' properties: '0': type: array items: type: string example: 11:00 - 18:00 '1': type: array items: type: string example: 11:00 - 18:00 '2': type: array items: type: string example: 11:00 - 18:00 '3': type: array items: type: string example: 11:00 - 18:00 '4': type: array items: type: string example: 11:00 - 18:00 '5': type: array items: type: string example: 11:00 - 18:00 '6': type: array items: type: string example: 11:00 - 18:00 open_tomorrow: type: boolean description: |- Indicates whether the service point will be open tomorrow based on its operating schedule. This field is calculated from `formatted_opening_times` and should be used to determine operational availability. open_upcoming_week: type: boolean description: |- Indicates whether the service point will be open at least once during the next 7 days. This field is calculated from `formatted_opening_times` including any schedule exceptions, and should be used to determine operational availability. distance: type: number description: |- Distance between the reference point and the service point in meters. Only returned on the list endpoint when `latitude`/`longitude` or `address` query parameters are provided. required: - id - code - is_active - extra_data - name - street - house_number - postal_code - city - latitude - longitude - email - phone - homepage - carrier - country - formatted_opening_times - open_tomorrow - open_upcoming_week shipping-functionalities: title: Shipping Functionalities Object type: object properties: age_check: type: integer nullable: true description: Indicates whether the recipient must be above a certain age (e.g., to accept alcohol products). b2b: type: boolean description: Indicates whether the shipment is a b2b shipment. b2c: type: boolean description: Indicates whether the shipment is a b2c shipment. boxable: type: boolean description: Indicates whether the shipment fits in a box. bulky_goods: type: boolean description: Indicates whether the shipment is bulky, e.g. it does not fit in a box. carrier_billing_type: type: string nullable: true description: Indicates whether the shipment is billed on a country to country basis, or based on a shipping zone to shipping zone. Example is shipping from mainland Spain to the Canary Islands (a zone) or Netherlands to the Netherlands (country to country). enum: - country - zonal cash_on_delivery: type: boolean nullable: true description: Indicates whether the receiver of the shipment should pay for the shipment when receiving it. dangerous_goods: type: boolean description: Indicates whether the shipment can contain dangerous goods. delivery_attempts: type: integer nullable: true description: Indicates the number of delivery attempts the carrier should attempt before returning (or discarding) the parcel. delivery_before: type: string nullable: true description: 'Indicates whether shipment will be delivered before a certain time of the day (Example: before 12:00).' delivery_deadline: type: string nullable: true enum: - best_effort - nextday - sameday - within_24h - within_48h - within_72h example: best_effort description: 'Indicates the period of time in which the shipment will be delivered (Example: 24 hours, 28 hours).' direct_contract_only: type: boolean description: Indicates whether shipping is only possible using your own carrier contract, or if it is possible using Sendcloud contract rates. eco_delivery: type: boolean description: Indicates whether the shipping process will be environmently friendly. ers: type: boolean description: Indicates whether shipment will use the ERS (Easy Return Solution) system. first_mile: type: string nullable: true enum: - dropoff - fulfilment - pickup - pickup_dropoff example: dropoff description: Indicates how transportation of the first mile of the shipment will take place. Example is that the parcel is dropped of at a service point, or is picked up by the carrier. flex_delivery: type: boolean description: Indicates whether the receiver of the parcel can, before delivery takes place, choose where and when the shipment should be delivered. form_factor: type: string nullable: true enum: - letter - long - mailbox - pallet - parcel example: parcel description: Indicates the form factor of the parcel. Examples are letter, pallet, parcel. fragile_goods: type: boolean description: Indicates whether shipment can contain fragile goods (glass, electronics, etcetera). fresh_goods: type: boolean description: Indicates whether shipment can contain fresh goods (e.g. food with an expiration date). harmonized_label: type: boolean description: Indicates whether shipment label contains the customs information on as well. id_check: type: boolean description: Indicates whether the receiver should identify him/herself to the carrier driver, conforming the identity of the receiver. incoterm: type: string nullable: true enum: - dap - ddp - ddu - dap_np - dap_dp example: ddp description: Indicates what incoterm is used for an (international) shipment. Mainly used to determine if the receiver or the sender pays the customs duties. insurance: type: integer description: Indicates whether the shipment has carrier insurance or not. labelless: type: boolean description: Indicates whether a return shipment can be done using only a QR code or numerical number, needed by the end-consumer to return the parcel. In other words, no shipping label is required. last_mile: type: string nullable: true enum: - home_delivery - mailbox - pobox - service_point example: home_delivery description: Indicates what the last mile of the shipment looks like. For instance, the shipment can be delivered to a service point or a home address. manually: type: boolean description: Indicates a subset of Deutsche Post shipping methods where a consumer should manually attach the label to the parcel. multicollo: type: boolean description: 'Indicates whether the shipment can be a multi-collo shipment. Note: Not all carriers support multicollo shipment. See the supported carriers and more in our help center.' neighbor_delivery: type: boolean description: Indicates whether shipment is allowed to be delivered at the neighbours of the receiver. non_conveyable: type: boolean description: Indicates whether the shipment fits on a conveyor belt. personalized_delivery: type: boolean description: Indicates a subset of Deutsche Post shipping methods shipping to a consumer. premium: type: boolean description: Indicates whether the carrier identifies the shipments shipping process as premium. priority: type: string nullable: true enum: - economical - express - priority - standard example: standard description: Indicates the priority level of the shipment. Examples are Express or Standard. registered_delivery: type: boolean description: Indicates whether a Proof of Delivery (POD) is communicated to the sender. returns: type: boolean description: Indicates whether the shipment should be a return shipment or not. segment: type: string nullable: true enum: - a+ - a - b - c - d example: a+ description: Indicates the international pricing zone for PostNL shipments. service_area: type: string nullable: true enum: - domestic - domestic_remote - international example: domestic description: Indicates the service area of the shipment. Examples are domestic or international. signature: type: boolean description: Indicates whether the shipment requires a signature upon delivery. size: type: string nullable: true enum: - xs - s - m - l - xl - xxl example: s description: Indicates the allowed size of the shipment. sorted: type: boolean description: Indicates whether the shipment(s) are handed over the carrier in a sorted fashion, decreasing costs. surcharge: type: boolean description: Indicates whether the carrier can surcharge the shipment later, based on (volumetric) weight. tracked: type: boolean description: Indicates whether the shipment can be tracked online. tyres: type: boolean description: Indicates whether the shipment can be used to ship tyres. weekend_delivery: type: string nullable: true enum: - saturday - sunday - weekends example: saturday description: Indicates whether shipment can delivery in the weekend or on a specific weekend-day. 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 securitySchemes: JWTtoken: type: http scheme: bearer description: The JWT generated when starting the Return Portal process responses: '400': description: Bad Request content: application/json: 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 requested path example: api/v2/brand/devtest/return-portal/outgoing message: type: string description: A message describing the error example: The postal code you provided is invalid. '404': description: Not Found content: application/json: schema: type: object properties: error: type: object properties: code: type: integer example: 404 request: type: string example: api/v2/brand/brand_domain/return-portal message: type: string example: No ReturnsPortal matches the given query '422': description: There are errors in the imported order, so the return process cannot be started content: application/json: schema: type: object properties: error: type: object properties: code: type: string example: unprocessable_order_blob_data request: type: string message: type: string example: Order details cannot be processed.