> ## 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 a return > Retrieve the details of a specific return by its unique identifier. **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). ## OpenAPI ````yaml /.openapi/v2/returns/openapi.yaml get /returns/{id} openapi: 3.1.0 info: title: Returns version: 2.0.0 contact: name: Sendcloud API Support url: https://www.sendcloud.dev email: contact@sendcloud.com description: >- This API is responsible for providing details regarding your returns, including details of the original outgoing parcel, the incoming parcel and the returned items. license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html servers: - url: https://panel.sendcloud.sc/api/v2 description: Production security: [] tags: - name: Webhooks description: Webhooks responsible for updating payment statuses - name: Returns description: Returns paths: /returns/{id}: parameters: - schema: type: integer example: 1 name: id in: path required: true description: The unique identifier of this return object get: tags: - Returns summary: Retrieve a return description: Retrieve the details of a specific return by its unique identifier. operationId: sc-public-v2-scp-get-return_by_id responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Return' examples: RetrieveReturn: summary: Retrieve a single return value: id: 1 created_at: '2022-06-07T16:36:49.419457+02:00' reason: 1 outgoing_parcel: 1 incoming_parcel: 1 message: Not good enough for me refund: total_refund: '"10.00"' refunded_at: 1654683771746 message: Exchange for size M refund_type: code: money label: Money back require_message: true is_cancellable: true return_fee: 3.5 return_fee_currency: EUR label_cost: 6.95 label_currency: EUR items_cost: 48.95 delivered_at: '2022-06-07T16:36:49.419457+02:00' delivery_option: drop_off_point store_location: 1 images: [] rule_modifications: - rule_name: my_ship_with_rule field: ship_with value: PostNL Return action: ship_with friendly_name: Return method priority: 1 item_id: null outgoing_parcel_data: tracking_url: >- https://tracking.sendcloud.sc/forward?carrier=dhl&code=JVGL1234567800000049 tracking_number: JVGL1234567800000049 parcel_status: 11 global_status_slug: delivered brand_name: My Brand order_number: EU2548657452 from_email: contact@sendcloud.com deleted: true collo_count: 1 from_country: NL from_name: Jane Doe shipping_method: 994 extra_data: {} incoming_parcel_data: tracking_url: >- https://tracking.sendcloud.sc/forward?carrier=dhl&code=JVGL1234567800000049 tracking_number: JVGL1234567800000049 parcel_status: 11 global_status_slug: delivered brand_name: My Brand order_number: EU2548657452 from_email: contact@sendcloud.com deleted: true collo_count: 1 from_country: NL from_name: Jane Doe shipping_method: 994 extra_data: {} rules: - name: my_ship_with_rule priority: 1 item_id: null modifications: - field: ship_with value: PostNL Return action: ship_with friendly_name: Return method incoming_parcel_status: id: 1 message: Delivered global_status_slug: delivered '404': $ref: '#/components/responses/404' deprecated: true security: - HTTPBasicAuth: [] - OAuth2ClientCreds: [] components: schemas: Return: type: object description: >- An object representing a Return. This includes details of the original outgoing parcel, the incoming parcel and the returned items. title: Return Object properties: id: type: integer description: The unique identifier of this Return object minimum: 1 example: 1 created_at: type: string description: The creation date of this Return, in ISO 8601 format format: date-time example: '2022-06-07T16:36:49.419457+02:00' reason: type: integer description: Identifier of the reason for this return minimum: 1 example: 1 outgoing_parcel: type: integer description: Identifier of the original outgoing Parcel object minimum: 1 example: 1 incoming_parcel: type: integer description: Identifier of the incoming return Parcel object minimum: 1 example: 1 message: type: string description: Return reason message as written by the customer example: Not good enough for me refund: type: object description: The type of compensation the customer chose for the returned items properties: total_refund: type: string description: Total amount that needs to be refunded, in floating point format example: '"10.00"' refunded_at: type: integer description: Timestamp of when the refund was issued minimum: 0 example: 1654683771746 message: type: string description: Additional information about the refund as written by the user example: Exchange for size M refund_type: type: object properties: code: type: string enum: - money - credit - exchange description: Identifier of the refund type label: type: string description: Human readable identifier of the refund type example: Money back require_message: type: boolean description: >- Whether this refund type requires an additional message from the customer is_cancellable: type: boolean description: Whether the incoming return parcel can still be cancelled return_fee: type: number description: The fee associated with this return minimum: 0 example: 3.5 return_fee_currency: type: string description: Currency of the return fee in three-letter ISO 4217 format example: EUR label_cost: type: number description: Cost of the label for the incoming return parcel minimum: 0 example: 6.95 label_currency: type: string description: Currency of the label cost in three-letter ISO 4217 format example: EUR items_cost: type: number description: Total cost of the returned items minimum: 0 example: 48.95 delivered_at: type: string description: Delivery date of the incoming return parcel format: date-time example: '2022-06-07T16:36:49.419457+02:00' delivery_option: type: string 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 - drop_off_labelless - in_store - pickup store_location: type: integer description: The identifier of the in-store return address minimum: 1 example: 1 outgoing_parcel_data: $ref: '#/components/schemas/ReturnParcel' incoming_parcel_data: allOf: - $ref: '#/components/schemas/ReturnParcel' - properties: customs_information: $ref: '#/components/schemas/IncomingParcelCustomsInformation' incoming_parcel_status: type: object description: Object describing the status of the incoming return parcel properties: id: type: integer description: Identifier of the Parcel Status object minimum: 1 example: 1 message: type: string description: Human readable status description example: Delivered global_status_slug: type: string description: Lookup key for the Parcel Status example: delivered images: type: array description: A list of images attached to a return items: type: object title: Return Image Object required: - uploaded_image example: uploaded_image: https://s3-eu-central-1.amazonaws.com/returns-media/image.png thumbnail_image: https://s3-eu-central-1.amazonaws.com/returns-media/image.png product_id: '123456' description: My broken camera, with a crack on the lens properties: uploaded_image: type: string format: uri example: https://s3-eu-central-1.amazonaws.com/returns-media/image.png description: The temporary publicly accessible URL of the image thumbnail_image: type: string format: uri example: https://s3-eu-central-1.amazonaws.com/returns-media/image.png description: The temporary publicly accessible URL of the image thumbnail product_id: type: string example: '123456' description: The ID of product that this image is attached to description: type: string example: My broken camera, with a crack on the lens description: A description of the uploaded image rule_modifications: type: array description: List of return rules applied to this Return items: type: object properties: rule_name: type: string description: Name of the rule that has been applied field: type: string description: Field that this rule affects value: description: >- New value of the field based on this rule. The type depends on the field type. action: type: string description: Action taken based on this rule friendly_name: type: string description: Human-readable name for the action priority: type: integer description: >- Priority of this rule. The rule with a higher priority value takes precedence. minimum: 0 item_id: type: string nullable: true description: >- Item that this rule has been applied to. It will be `null` if the rule is applied to the whole return. ReturnParcel: type: object description: An object representing the details of a Parcel properties: tracking_url: type: string description: >- URL to the tracking page of the carrier, to follow the status updates of the parcel example: >- https://tracking.sendcloud.sc/forward?carrier=dhl&code=JVGL1234567800000049 format: uri tracking_number: type: string description: Tracking number of the parcel as created by the carrier example: JVGL1234567800000049 parcel_status: type: integer description: Identifier of the Parcel Status example: 11 minimum: 1 global_status_slug: type: string description: Lookup key for the Parcel Status example: delivered brand_name: type: string description: Name of the brand associated with this Parcel example: My Brand order_number: type: string description: Identifier of the order associated with this Parcel example: EU2548657452 from_email: type: string description: Email address of the sender of this Parcel format: email example: contact@sendcloud.com deleted: type: boolean description: Whether this Parcel was marked as deleted collo_count: type: integer description: Number of individual Parcel objects associated with this shipment minimum: 1 example: 1 from_country: type: string description: Originating country of this Parcel in two-letter ISO 3166 format example: NL from_name: type: string description: Name of the sender of this Parcel example: Jane Doe shipping_method: type: integer description: Identifier of the Shipping Method chosen for this Parcel minimum: 1 example: 994 extra_data: type: object description: Arbitrary data about this parcel rules: type: array deprecated: true description: >- List of policy rules applied to this Parcel. DEPRECATED, Use `rule_modifications` field of the Return object instead. items: type: object properties: modifications: type: array description: List of modifications as a result of applied rules items: type: object description: >- Object describing the modification performed after a rule was applied properties: field: type: string description: The field that was changed value: description: >- The value the field was changed to. The type depends on the field type title: Return Parcel Object IncomingParcelCustomsInformation: title: Return Parcel Customs Information type: object description: Customs information related to the Parcel. example: customs_invoice_nr: INV-123 customs_shipment_type: 4 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 customs_shipment_type: type: integer description: >- Customs shipment type. For Returns, this field is always set to 4 which corresponds to RETURNED_GOODS. example: 4 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 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. 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 - customs_shipment_type 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: '404': description: Not Found content: application/json: schema: type: object properties: error: type: object properties: code: type: integer request: type: string message: type: string securitySchemes: HTTPBasicAuth: type: http description: >- Basic Authentication using API key and secrets is currently the main authentication mechanism. scheme: basic OAuth2ClientCreds: type: oauth2 description: >- OAuth2 is a standardized protocol for authorization that allows users to share their private resources stored on one site with another site without having to provide their credentials. OAuth2 Client Credentials Grant workflow. This workflow is typically used for server-to-server interactions that require authorization to access specific resources. flows: clientCredentials: tokenUrl: https://account.sendcloud.com/oauth2/token/ scopes: api: Default OAuth scope required to access Sendcloud API. ````