> ## Documentation Index > Fetch the complete documentation index at: https://sendcloud.dev/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve an outgoing parcel > Find an outgoing parcel via two mandatory query parameters: either the tracking number or the order number, and the postal code. **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. ## OpenAPI ````yaml /.openapi/v2/return-portal/openapi.yaml get /brand/{brand_domain}/return-portal/outgoing 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 security: [] tags: - name: Return portal description: Sendcloud's Return portal paths: /brand/{brand_domain}/return-portal/outgoing: parameters: - schema: type: string minLength: 1 name: brand_domain in: path required: true description: The domain you defined in the brand settings. get: tags: - Returns Portal summary: Retrieve an outgoing parcel description: > Find an outgoing parcel via two mandatory query parameters: either the tracking number or the order number, and the postal code. operationId: sc-public-v2-scp-get-outgoing 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 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' security: [] components: schemas: 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 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 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. 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. ````