> ## Documentation Index > Fetch the complete documentation index at: https://sendcloud.dev/llms.txt > Use this file to discover all available pages before exploring further. # Create a return > Create a new return parcel based on an outgoing parcel. **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. ## OpenAPI ````yaml /.openapi/v2/return-portal/openapi.yaml post /brand/{brand_domain}/return-portal/incoming 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/incoming: parameters: - schema: type: string name: brand_domain in: path required: true description: The domain you defined in the brand settings. post: tags: - Return portal summary: Create a return description: Create a new return parcel based on an outgoing parcel. operationId: sc-public-v2-scp-post-incoming parameters: [] 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 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' security: - JWTtoken: [] components: schemas: 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 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. securitySchemes: JWTtoken: type: http scheme: bearer description: The JWT generated when starting the Return Portal process ````