Sendcloud Returns API

openapi: 3.2.0
info:
  title: Sendcloud Returns API
  version: 3.0.0
  description: 'Operations tagged Returns across 2 of this provider''s published API definitions: sendcloud-shipments-openapi.yml, sendcloud-v3-returns-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://panel.sendcloud.sc/api/v3
  description: Sendcloud Production
tags:
- name: Returns
paths:
  /addresses/validate:
    post:
      summary: Validate an address
      tags:
      - Returns
      operationId: sc-public-v3-scp-post-validate_address
      security:
      - HTTPBasicAuth: []
      description: "This address validation endpoint allows you to validate shipping addresses before using them.\nBy validating addresses in advance, you can ensure that the shipping information is accurate and complete,\nreducing the risk of delivery issues and improving overall shipping efficiency.\nProviding the carrier helps to tailor the address validation process according to specific carrier requirements.\nUsing additional validation methods can further enhance the accuracy of the address verification.\n\nThe default Sendcloud validation, will always be applied, has in 2 steps:\n1. checks the address against the carrier limits\n(e.g. maximum length of the address line, existence of the postal code for the country, etc.). \nsee also [Carrier address limits](/docs/shipments/address-field-limits#address-field-limits).\n\n2. optimizes (washes) the address to fit within the carrier limits.\n(e.g. deduplication of address lines, abbreviations, etc.)"
      x-mint:
        href: /api/v3/address/validate
        content: 'This address validation endpoint allows you to validate shipping addresses before using them.

          By validating addresses in advance, you can ensure that the shipping information is accurate and complete,

          reducing the risk of delivery issues and improving overall shipping efficiency.

          Providing the carrier helps to tailor the address validation process according to specific carrier requirements.

          Using additional validation methods can further enhance the accuracy of the address verification.


          The default Sendcloud validation, will always be applied, has in 2 steps:

          1. checks the address against the carrier limits

          (e.g. maximum length of the address line, existence of the postal code for the country, etc.).

          see also [Carrier address limits](/docs/shipments/address-field-limits#address-field-limits).


          2. optimizes (washes) the address to fit within the carrier limits.

          (e.g. deduplication of address lines, abbreviations, etc.)'
      responses:
        '200':
          description: Address validation successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/address-washer-response'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors'
              examples:
                Failed:
                  summary: Failed to validate the address
                  value:
                    errors:
                    - detail: This field is required.
                      status: '400'
                      source:
                        pointer: /address/carrier_code
                      code: required
      parameters:
      - schema:
          type: string
          example: 550e8400-e29b-41d4-a716-446655440000
        in: header
        description: If you are <a href="https://www.sendcloud.com/ecosystem/" target="_blank"> an official Sendcloud Tech Partner</a>, you can provide this additional request header for the system to recognize you. Sendcloud Partner UUID is provided to Sendcloud partners. The token is not required but if the header is set, the system will try to validate it. An unknown UUID will cause the 404 return, whilst an invalid one will return 400.
        name: Sendcloud-Partner-Id
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/address-washer-request'
    servers:
    - url: https://panel.sendcloud.sc/api/v3
      description: Sendcloud Production
  /returns:
    post:
      tags:
      - Returns
      summary: Create a return
      description: Create a standalone return
      x-mint:
        href: /api/v3/returns/create-a-return
        content: "The Create a return endpoint is the heart of the Returns API; it allows you to create a stand-alone return, based mainly on the `to` and `from_address`, parcel `weight` and the `ship_with` object.\n\nYou can provide a list of items and item descriptions to be included in the return via the `parcel_items` field (optional).\n\n<Info>\n  The `parcel_items` field is **mandatory** if you're creating a return from outside the EU. This is because information about the parcel contents must be provided in order to generate the required customs documents.\n</Info>\n\n## The `ship_with` object\n\nThis object is used to select a shipping method for the return. There are two ways of selecting a shipping method:\n\n- By providing a `shipping_option_code` (find the code using the [Shipping options API](/api/v3/shipping-options)).\n- By providing a `shipping_product_code` and a set of `functionalities`. \n  Functionalities are used to filter the right shipping method within the product. Find this data using the [Retrieve a list of shipping products](/api/v2/shipping-products/retrieve-a-list-of-shipping-products) endpoint.\n\nThe `contract` attribute refers to the ID of a direct contract you have with the carrier. Get the IDs for your contracts from the [Retrieve a list of contracts](/api/v3/contracts/retrieve-a-list-of-contracts) endpoint.\n\n<Warning>\n  If you have more than one active contract for a specific carrier, you must fill the `contract` attribute with your desired contract ID in your request.\n</Warning>\n\n## Retrieve return shipping products\n\nIn your request, you must provide an appropriate `shipping_product_code` and a set of `functionalities` inside the `ship_with` object. To find a suitable product, refer to the [Retrieve a list of shipping products](/api/v2/shipping-products/retrieve-a-list-of-shipping-products) endpoint.\n\nYou can filter for a return method by flagging the `returns` field as `true`,  and by including the `from_country` and `to_country` fields. The more fields you specify, the more refined the results will be. This helps you find the most appropriate shipping product for your return parcel.\n\nIt's also possible to filter based on your preferred [shipping functionality](/api/v2/shipping-products/retrieve-a-list-of-shipping-functionalities), e.g. `age_check=18`, `delivery_before`, etc.\n\n## Add return reasons\n\nYou can (optionally) assign a **return reason** to `parcel_items` by providing a`return_reason_id` and entering a value from the key below. Assigning return reasons to items provides you with analyzable data you can use to predict return trends or identify issues with particular products.\n\n| Return Reason ID | Description                                  |\n| ---------------- | -------------------------------------------- |\n| 1                | Product did not match expectations           |\n| 3                | Other (explain in message)                   |\n| 4                | Incorrect product ordered                    |\n| 6                | Product did not match description on website |\n| 7                | Wrong product shipped                        |\n| 8                | No reason                                    |\n| 9                | Rent                                         |\n| 10               | Does not work                                |\n| 11               | Changed my mind                              |\n| 12               | Did not meet expectations                    |\n| 13               | Excessive amount                             |\n| 14               | Better price available                       |\n| 15               | Accidental order                             |\n| 16               | No longer needed                             |\n| 17               | Sample products                              |\n| 18               | Looks different than expected                |\n| 19               | Ordered more than one size                   |\n| 20               | Arrived too late                             |\n| 21               | Poor quality / Faulty                        |\n| 22               | Does not fit properly                        |\n| 23               | Does not suit me                             |\n| 24               | Incorrect product received                   |\n| 25               | Parcel damaged on arrival                    |\n| 26               | Wrong size ordered                           |\n| 27               | Wrong color ordered                          |\n| 28               | Does not function as expected                |\n| 29               | Recycle or reuse packaging                   |\n| 30               | Size too large                               |\n| 31               | Size too small                               |\n| 32               | Holiday season return                        |\n\n## Retrieve the shipping label for this return\n\nOnce the parcel for the created return is announced, you can download the shipping label for it.\n\nFind the documentation on how to retrieve a label for a parcel on the [Retrieve a parcel document](/api/v3/parcel-documents/retrieve-a-parcel-document) endpoint.\n\nThe url for downloading the label is also available on the Return object (Only if the parcel is announced). To retrieve a return, take a look at the [Retrieve a return](/api/v3/returns/retrieve-a-return) endpoint.\n\nTo learn more about all the options for retrieving labels and customs declaration documents, refer to the [Parcel documents API](/api/v3/parcel-documents) documentation."
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  return_id:
                    type: integer
                    description: The sendcloud return id
                    minimum: 1
                  parcel_id:
                    type: integer
                    minimum: 1
                    description: The sendcloud incoming parcel id
                  multi_collo_ids:
                    type: array
                    description: A list with all the related sendcloud incoming parcel ids in the collo
                    items:
                      type: integer
                      minimum: 1
                required:
                - return_id
                - parcel_id
                - multi_collo_ids
              examples:
                example-1:
                  value:
                    return_id: 12345
                    parcel_id: 67880
                    multi_collo_ids: []
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors_2'
      operationId: sc-public-v3-scp-post-returns_create_new_return
      security:
      - HTTPBasicAuth: []
      - OAuth2ClientCreds: []
      parameters:
      - $ref: '#/components/parameters/SendcloudPartnerId'
      requestBody:
        $ref: '#/components/requestBodies/CreateReturn'
    get:
      tags:
      - Returns
      summary: Retrieve a list of returns
      description: Retrieve a list of returns which have been created under your API credentials.
      x-mint:
        href: /api/v3/returns/retrieve-a-list-of-returns
        content: 'The response includes return data for each parcel, plus up-to-date tracking history.


          The returned data is paginated and has a default number of items per page of `40`, which can be controlled by the `page_size` query param.


          You can filter the results to only include return parcels created within a specific time frame using the `from_date` and `to_date` parameters, or based on the `parent_parcel_status`.'
      parameters:
      - $ref: '#/components/parameters/Cursor'
      - name: from_date
        in: query
        schema:
          type: string
          example: '2022-04-06 00:00:00'
        description: Excludes all returns before this datetime
        example: '2022-04-06 00:00:00'
        required: true
      - name: to_date
        in: query
        schema:
          type: string
          example: '2022-04-07 00:00:00'
        description: Excludes all returns after this datetime
        example: '2022-04-07 00:00:00'
        required: true
      - name: parent_parcel_status
        in: query
        schema:
          type: string
          example: announced
          enum:
          - ready-to-send
          - announced
          - to-sorting
          - delayed
          - sorted
          - unsorted
          - sorting
          - delivery-failed
          - delivery-forced
          - delivered
          - awaiting-customer-pickup
          - announced-uncollected
          - collect-error
          - unsorted2
          - undeliverable
          - shipment-on-route
          - driver-on-route
          - picked-up-by-driver
          - collected-by-customer
          - no-label
          - announcing
          - cancelling-upstream
          - cancelling
          - cancelled
          - cancelled-upstream
          - unknown
          - announcement-failed
          - at-customs
          - at-sorting-centre
          - refused-by-recipient
          - returned-to-sender
          - delivery-method-changed
          - delivery-date-changed
          - delivery-address-changed
          - exception
          - address-invalid
        description: Search for returns with this parent status
        required: false
      - schema:
          type: number
          minimum: 1
          maximum: 40
          example: 10
        in: query
        name: page_size
        description: Refers to the number of items per page
      operationId: sc-public-v3-scp-get-returns_get_returns
      security:
      - HTTPBasicAuth: []
      - OAuth2ClientCreds: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  next:
                    type: string
                    description: A cursor-based pagination url to go forward
                  previous:
                    type: string
                    description: A cursor-based pagination url to go backwards
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Return'
              examples:
                Success:
                  value:
                    next: http://panel.sendcloud.sc/api/v3/returns?cursor=cD0z&page_size=1
                    previous: http://panel.sendcloud.sc/api/v3/returns?cursor=cD0z&page_size=2
                    data:
                    - created_at: '2022-07-18T15:34:21.869312+02:00'
                      is_cancellable: false
                      label_cost:
                        value: 6.15
                        currency: EUR
                      delivered_at: 1734946171662
                      delivered_at_iso: '2022-07-18T15:34:21.869312+02:00'
                      shipping_product:
                        code: postnl:standard/return
                      shipping_option:
                        code: postnl:standard/signature
                      collo_count: 1
                      brand_id: 1
                      tracking_number: JVGL1234567800001339
                      dimensions:
                        length: 3
                        width: 3
                        height: 3
                        unit: cm
                      parcel_items: []
                      insurance: false
                      label_url: https://panel.sendcloud.sc/api/v3/parcels/7/documents/label
                      label:
                        label_printer: https://panel.sendcloud.sc/api/v3/parcels/7/documents/label
                        normal_printer:
                        - https://panel.sendcloud.sc/api/v3/parcels/7/documents/label?paper_size=a4
                        - https://panel.sendcloud.sc/api/v3/parcels/7/documents/label?paper_size=a4
                        - https://panel.sendcloud.sc/api/v3/parcels/7/documents/label?paper_size=a4
                        - https://panel.sendcloud.sc/api/v3/parcels/7/documents/label?paper_size=a4
                      tracking_url: https://tracking.eu-central-1-0.sendcloud.sc/forward?carrier=postnl&code=JVGL1234567800001339&destination=NL&lang=en-us&source=NL&type=parcel&verification=5611+JV&servicepoint_verification=&created_at=2022-07-18
                      send_tracking_emails: false
                      weight:
                        value: 1
                        unit: kg
                      from_address:
                        name: Gregory van der Poel
                        address_line_1: Merchant Street
                        address_line_2: ''
                        house_number: '1'
                        postal_code: 5611 LX
                        city: Eindhoven
                        country_code: NL
                        email: merchant@email.com
                      to_address:
                        name: Customer3
                        po_box: ''
                        address_line_1: Customer Street3
                        address_line_2: ''
                        house_number: '12'
                        postal_code: 5611 JV
                        city: Eindhoven
                        state_province_code: Noord Brabant
                        country_code: NL
                        email: customer@email.com
                      reason:
                        id: 1
                        description: Product did not match expectations
                      refund:
                        refund_type: exchange
                        message: Exchange for size M
                      return_fee:
                        value: 1.5
                        currency: EUR
                      order_number: ''
                      status_history:
                      - carrier_update_timestamp: '2022-07-18T15:34:21.862840+02:00'
                        parcel_status_history_id: '1'
                        parent_status: Ready to Ship
                        carrier_code: some-carrier-code
                        carrier_message: some-carrier-message
                      customs_invoice_nr: ''
                      customs_shipment_type: 2
    servers:
    - url: https://panel.sendcloud.sc/api/v3
      description: Sendcloud Production
  /returns/{id}:
    parameters:
    - schema:
        type: integer
        example: 1751075
      name: id
      in: path
      required: true
      description: The internal Sendcloud id of this return
    get:
      tags:
      - Returns
      summary: Retrieve a return
      description: Retrieve information about a specific return parcel based on the return `id`.
      x-mint:
        href: /api/v3/returns/retrieve-a-return
        content: "This endpoint allows you to retrieve information about a specific return parcel based on the return `id`. A return `id` is assigned to every return you create in Sendcloud, and can be retrieved for all return parcels via the [Retrieve a list of returns](/api/v3/returns/retrieve-a-list-of-returns) endpoint. \n\nThe returned object contains all relevant information about the return parcel, including up-to-date tracking information."
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Return'
        '404':
          description: Not Found
      operationId: sc-public-v3-scp-get-returns_get_details
      security:
      - HTTPBasicAuth: []
      - OAuth2ClientCreds: []
    servers:
    - url: https://panel.sendcloud.sc/api/v3
      description: Sendcloud Production
  /returns/{id}/cancel:
    parameters:
    - schema:
        type: integer
        example: 1751075
      name: id
      in: path
      required: true
      description: The Sendcloud unique identifier of this return
    patch:
      tags:
      - Returns
      summary: Request cancellation of a return
      description: You can request cancellation for a return by providing the return `id` to this endpoint.
      x-mint:
        href: /api/v3/returns/request-cancellation-of-a-return
        content: "Not all carriers support upstream label cancellation via an API request, therefore this endpoint will only send a cancellation **request**. A successful response indicates that the request is received and the carrier supports label cancellation.\n\nYou can check the `parent_status` of the return via the [Retrieve a return](/api/v3/returns/retrieve-a-return) endpoint to confirm whether the actual cancellation was successful.\n\n<Note>\n  You can find more information about carriers which do not support label cancellation requests in our [help center](https://support.sendcloud.com/hc/en-us/articles/4461608475284-How-to-cancel-a-return-shipment).\n</Note>"
      requestBody:
        content: {}
      parameters:
      - name: id
        in: path
        schema:
          type: integer
        required: true
        description: The internal Sendcloud id of this return
        example: 1751075
      responses:
        '202':
          description: Cancellation has successfully been requested
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Message detailing more if the cancellation request was successful or not
                    example: Cancellation requested successfully
                required:
                - message
              examples:
                example-1:
                  value:
                    message: Cancellation requested successfully
        '404':
          description: Not Found
        '409':
          description: Conflict
          headers: {}
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                        code:
                          type: integer
                        message:
                          type: string
                required:
                - errors
              examples:
                Conflict:
                  value:
                    errors:
                    - field: returns
                      code: 409
                      message: Return is not cancellable.
      operationId: sc-public-v3-scp-patch-returns_cancel
      security:
      - HTTPBasicAuth: []
      - OAuth2ClientCreds: []
    servers:
    - url: https://panel.sendcloud.sc/api/v3
      description: Sendcloud Production
  /returns/validate:
    post:
      tags:
      - Returns
      summary: Validate a return
      description: Check if a return can be announced **without** actually creating the return, or announcing it with the carrier.
      x-mint:
        href: /api/v3/returns/validate-a-return
        content: "This endpoint allows you to validate whether a return can be announced **without** actually creating the return or announcing it with the carrier. You can structure the request body exactly as you would if you were making a request to the [Create a return](/api/v3/returns/create-a-return) endpoint.\n\nWhen you make the request, the response will indicate whether the parcel is valid and can be announced. Validation is based mainly on the `to` and `from` address, the parcel `weight` and the shipping product `id` provided.\n\n<Info>\n  The `parcel_items` field is **mandatory** if you're creating a return from outside the EU.\n</Info>"
      parameters:
      - $ref: '#/components/parameters/SendcloudPartnerId'
      requestBody:
        $ref: '#/components/requestBodies/CreateReturn'
      responses:
        '200':
          description: Your return passed all validation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReturnValidation'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors_2'
      operationId: sc-public-v3-scp-post-returns_validate
      security:
      - HTTPBasicAuth: []
      - OAuth2ClientCreds: []
    servers:
    - url: https://panel.sendcloud.sc/api/v3
      description: Sendcloud Production
  /returns/announce-synchronously:
    post:
      tags:
      - Returns
      summary: Create a return synchronously
      description: Create a return synchronously, i.e. wait for a response from the carrier before continuing.
      x-mint:
        href: /api/v3/returns/create-a-return-synchronously
        content: "This endpoint will create a return, similarly to the [Create a return](/api/v3/returns/create-a-return) endpoint, but via a synchronous API request. This means that the API will wait for a response from the carrier before you can continue.\n\nThis endpoint is primarily used for **debugging purposes** in the event that a return parcel announcement fails, as it will retrieve the carrier announcement error. Creating a return synchronously can impact the performance of the endpoint, as the process will take longer than calls to the [Create a return](/api/v3/returns/create-a-return) endpoint.\n\n<Info>\n  **Note:** The `parcel_items` field is mandatory if you're creating a return from outside the EU.\n</Info>"
      parameters:
      - $ref: '#/components/parameters/SendcloudPartnerId'
      requestBody:
        $ref: '#/components/requestBodies/CreateReturn'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  return_id:
                    type: integer
                    description: The sendcloud return id
                    minimum: 1
                  parcel_id:
                    type: integer
                    minimum: 1
                    description: The sendcloud incoming parcel id
                  multi_collo_ids:
                    type: array
                    description: A list with all the related sendcloud incoming parcel ids in the collo
                    items:
                      type: integer
                      minimum: 1
                required:
                - return_id
                - parcel_id
                - multi_collo_ids
              examples:
                example-1:
                  value:
                    return_id: 12345
                    parcel_id: 67880
                    multi_collo_ids: []
        '400':
          $ref: '#/components/responses/400'
      operationId: sc-public-v3-scp-post-returns_create_new_return_synchronously
      security:
      - HTTPBasicAuth: []
      - OAuth2ClientCreds: []
    servers:
    - url: https://panel.sendcloud.sc/api/v3
      description: Sendcloud Production
components:
  schemas:
    raw-address:
      title: Raw address
      type: object
      description: Raw address object
      properties:
        address_line_1:
          type: string
          example: Stadhuisplein
          description: First line of the address
        house_number:
          type: string
          example: '50'
          description: House number of the address
        address_line_2:
          type: string
          description: Additional address information, e.g. 2nd level
          example: Apartment 17B
        postal_code:
          type: string
          example: 1013 AB
          description: Zip code of the address
          minLength: 1
        city:
          type: string
          example: Eindhoven
          description: City of the address
          minLength: 1
        po_box:
          type:
          - string
          - 'null'
          description: Code required in case of PO Box or post locker delivery
        state_province_code:
          type: string
          example: IT-RM
          description: The character state code of the customer represented as ISO 3166-2 code. This field is required for certain countries. See [international shipping](/docs/shipments/international-shipping#required-fields-for-international-shipments) for details.
        country_code:
          type: string
          example: NL
          description: The country code of the customer represented as ISO 3166-1 alpha-2
          minLength: 1
    ErrorObject:
      title: Error
      type: object
      description: Error in a JSON:API error format
      properties:
        id:
          type: string
          description: A unique identifier for the error.
        links:
          type: object
          description: A set of hyperlinks that provide additional information about the error.
          properties:
            about:
              type: string
              description: A URL that provides additional information about the error.
        status:
          type: string
          format: int32
          description: The HTTP status code of the error.
          minLength: 1
        code:
          type: string
          description: A unique error code for the error, in snake case format.
          minLength: 1
          enum:
          - unknown_field
          - invalid
          - forbidden
          - invalid_choice
          - min_value
          - 'null'
          - not_found
          - required
          - not_a_list
          - non_field_errors
          - authentication_failed
          - validation_error
          - parcel_announcement_error
        title:
          type: string
          description: A short, human-readable summary of the error.
          minLength: 1
        detail:
          type: string
          description: A human-readable explanation of the error.
          minLength: 1
        source:
          type: object
          description: An object that identifies the source of the error within the request payload.
          properties:
            pointer:
              type: string
              description: A `JSON` pointer to the location of the error within the request payload.
            parameter:
              type: string
              description: The name of the `query` parameter that caused the error.
            header:
              type: string
              description: The name of the `header` parameter that caused the error.
        meta:
          type: object
          description: Additional metadata about the error.
    address-washer-response:
      title: Address Washer Response
      description: Address Washer Response object model
      type: object
      properties:
        input_address_is_valid:
          type: boolean
          description: Indicates if the input address is valid.
        results:
          description: The results of the address validation.
          type: array
          items:
            type: object
            properties:
              address:
                $ref: '#/components/schemas/raw-address'
              recommended:
                type: boolean
                description: Indicates if the address is recommended after validation.
              analysis:
                type: object
                description: Analysis details of the address validation.
                properties:
                  validation_result:
                    type: object
                    description: The result of the validation process.
                    properties:
                      is_valid:
                        type: boolean
                        description: Indicates if the address is valid.
                      reasons:
                        type: array
                        description: List of rea

# --- truncated at 32 KB (100 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sendcloud/refs/heads/main/openapi/sendcloud-returns-api-openapi.yml