Sendcloud Returns API v3

openapi: 3.1.0
info:
  title: Returns
  version: 3.0.0
  contact:
    name: Sendcloud API Support
    url: https://www.sendcloud.dev
    email: [email protected]
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  description: >-
    The Sendcloud **Returns API** lets you create standalone returns easily and
    efficiently, so you can seamlessly incorporate returns into your existing
    workflow, ERP or WMS system. This API can be used in conjunction with other
    core Sendcloud features or independently.
servers:
  - url: https://panel.sendcloud.sc/api/v3
    description: Sendcloud Production
tags:
  - name: Returns
    description: Sendcloud's Returns API
paths:
  /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.


          You can provide a list of items and item descriptions to be included
          in the return via the `parcel_items` field (optional).


          <Info>
            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.
          </Info>


          ## The `ship_with` object


          This object is used to select a shipping method for the return. There
          are two ways of selecting a shipping method:


          - By providing a `shipping_option_code` (find the code using the
          [Shipping options API](/api/v3/shipping-options)).

          - By providing a `shipping_product_code` and a set of
          `functionalities`. 
            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.

          The `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.


          <Warning>
            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.
          </Warning>


          ## Retrieve return shipping products


          In 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.


          You 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.


          It'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.


          ## Add return reasons


          You 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.


          | Return Reason ID | Description                                  |

          | ---------------- | -------------------------------------------- |

          | 1                | Product did not match expectations           |

          | 3                | Other (explain in message)                   |

          | 4                | Incorrect product ordered                    |

          | 6                | Product did not match description on website |

          | 7                | Wrong product shipped                        |

          | 8                | No reason                                    |

          | 9                | Rent                                         |

          | 10               | Does not work                                |

          | 11               | Changed my mind                              |

          | 12               | Did not meet expectations                    |

          | 13               | Excessive amount                             |

          | 14               | Better price available                       |

          | 15               | Accidental order                             |

          | 16               | No longer needed                             |

          | 17               | Sample products                              |

          | 18               | Looks different than expected                |

          | 19               | Ordered more than one size                   |

          | 20               | Arrived too late                             |

          | 21               | Poor quality / Faulty                        |

          | 22               | Does not fit properly                        |

          | 23               | Does not suit me                             |

          | 24               | Incorrect product received                   |

          | 25               | Parcel damaged on arrival                    |

          | 26               | Wrong size ordered                           |

          | 27               | Wrong color ordered                          |

          | 28               | Does not function as expected                |

          | 29               | Recycle or reuse packaging                   |

          | 30               | Size too large                               |

          | 31               | Size too small                               |

          | 32               | Holiday season return                        |


          ## Retrieve the shipping label for this return


          Once the parcel for the created return is announced, you can download
          the shipping label for it.


          Find 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.


          The 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.


          To 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'
      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: [email protected]
                        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: [email protected]
                        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
  /returns/{id}:
    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. 


          The 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: []
    parameters:
      - schema:
          type: integer
          example: 1751075
        name: id
        in: path
        required: true
        description: The internal Sendcloud id of this return
  /returns/{id}/cancel:
    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.


          You 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.


          <Note>
            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).
          </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: []
    parameters:
      - schema:
          type: integer
          example: 1751075
        name: id
        in: path
        required: true
        description: The Sendcloud unique identifier of this return
  /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.


          When 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.


          <Info>
            The `parcel_items` field is **mandatory** if you're creating a return from outside the EU.
          </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'
      operationId: sc-public-v3-scp-post-returns_validate
      security:
        - HTTPBasicAuth: []
        - OAuth2ClientCreds: []
  /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.


          This 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.


          <Info>
            **Note:** The `parcel_items` field is mandatory if you're creating a return from outside the EU.
          </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: []
components:
  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.
  schemas:
    Return:
      title: Return Object
      type: object
      description: A Sendcloud return object
      properties:
        from_address:
          $ref: '#/components/schemas/address-with-required-fields'
        to_address:
          $ref: '#/components/schemas/address-with-required-fields'
        shipping_product:
          $ref: '#/components/schemas/shipping-products-ref'
        shipping_option:
          title: Shipping Option Code
          type: object
          description: Sendcloud shipping option code
          properties:
            code:
              type:
                - string
                - 'null'
              description: >-
                The shipping option code, as provided by the [Shipping options
                API](/api/v3/shipping-options/return-a-list-of-available-shipping-options).
              example: postnl:standard/signature
        dimensions:
          $ref: '#/components/schemas/dimension'
        weight:
          $ref: '#/components/schemas/weight'
        collo_count:
          type: integer
          default: 1
          minimum: 1
          description: The number of collos this return consists of
        parcel_items:
          type: array
          description: List of items contained in this return. Required outside the EU.
          items:
            $ref: '#/components/schemas/parcel-item-returns-details'
        send_tracking_emails:
          type: boolean
          default: false
          description: >-
            When `true`, Sendcloud will send out the default track and trace
            emails
        brand_id:
          type: integer
          description: The ID of the brand this Return belongs to.
          example: 1
          minimum: 1
        label_url:
          type:
            - string
            - 'null'
          description: >-
            URL to download the label. This can be `null` because it might not
            be announced yet. **Deprecated** in favour of the `label` field.
          example: https://panel.sendcloud.sc/api/v3/parcels/8/documents/label
          deprecated: true
        label:
          type: object
          description: URLs to download the label, if the parcel has been announced.
          properties:
            normal_printer:
              type: array
              items:
                type: string
                format: url
              description: >-
                URLs to download the label as an A4 PDF. The array always
                contains 4 identical URLs for backward compatibility with the v2
                positional label layout.
              example:
                - >-
                  https://panel.sendcloud.sc/api/v3/parcels/8/documents/label?paper_size=a4
                - >-
                  https://panel.sendcloud.sc/api/v3/parcels/8/documents/label?paper_size=a4
                - >-
                  https://panel.sendcloud.sc/api/v3/parcels/8/documents/label?paper_size=a4
                - >-
                  https://panel.sendcloud.sc/api/v3/parcels/8/documents/label?paper_size=a4
            label_printer:
              type: string
              description: URL to download the label as an A6 PDF
              format: url
              example: https://panel.sendcloud.sc/api/v3/parcels/8/documents/label
        label_cost:
          $ref: '#/components/schemas/price'
        insurance:
          type: boolean
          description: Whether the return parcel is insured
        tracking_number:
          type:
            - string
            - 'null'
          description: This can be null because it might not be announced yet.
          example: 3SSEND12345678
        tracking_url:
          type:
            - string
            - 'null'
          description: >-
            URL to track your return. This can be null because it might not be
            announced yet.
          example: >-
            https://tracking.eu-central-1-0.sendcloud.sc/forward?carrier=sendcloud&code=3SSEND12345678&destination=NL&lang=en-gb&source=NL&type=letter&verification=1001+VV&servicepoint_verification=&created_at=2022-07-27
        is_cancellable:
          type: boolean
          description: Whether the incoming parcel of this return can be cancelled
        status_history:
          type: array
          description: List with the timeline of your return status
          minItems: 1
          items:
            $ref: '#/components/schemas/detailed-tracking-blob-status'
        created_at:
          type: string
          description: Date and time of creation of this return
          format: date-time
          example: '2022-08-09T14:32:21.463473+02:00'
        delivered_at:
          type:
            - number
            - 'null'
          example: 1734946171662
          description: >-
            A unix timestamp indicating the delivery time of this return.
            **Deprecated** in favour of the `delivered_at_iso` field.
          deprecated: true
        delivered_at_iso:
          type:
            - string
            - 'null'
          format: date-time
          description: Date and time of delivery of this return
          example: '2022-08-09T14:32:21.463473+02:00'
        reason:
          $ref: '#/components/schemas/return-reason'
        refund:
          $ref: '#/components/schemas/return-refund'
          type:
            - object
            - 'null'
        return_fee:
          $ref: '#/components/schemas/price-with-any-currency'
          type:
            - object
            - 'null'
          description: The fee associated with this return
        order_number:
          type: string
          description: Order number filled by the us

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