openapi: 3.1.0
info:
title: Shipments Address Returns API
version: 3.0.0
description: The Shipments API allows you to create and announce, retrieve, and cancel outgoing shipments and their associated parcels within the Sendcloud platform.
contact:
name: Sendcloud API Support
email: contact@sendcloud.com
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
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'
/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
/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: []
/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: []
/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: []
/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: []
components:
schemas:
address-with-required-fields:
title: Address Object
type: object
description: Sendcloud Address object
oneOf:
- $ref: '#/components/schemas/address'
required:
- name
- address_line_1
- postal_code
- city
- country_code
address-washer-request:
title: Address Washer Request
description: Address Washer Request object model
type: object
properties:
address:
$ref: '#/components/schemas/raw-address'
carrier_code:
description: The code of the carrier to be used for the address validation. Only carriers available to your account can be used.
type: string
example: trunkrs
validation_methods:
description: 'An array of optional address validation methods to be applied
The default Sendcloud validation will always be applied.
'
type: array
items:
$ref: '#/components/schemas/address-validation-method-enum'
example:
- here
required:
- address
- carrier_code
errors:
title: Errors
description: A standardized format for errors in [JSON:API](https://jsonapi.org/format/#error-objects) responses.
type: array
items:
allOf:
- $ref: '#/components/schemas/ErrorObject'
- required:
- status
- code
- detail
weight:
title: Weight
type: object
description: Weight in the specified unit
properties:
value:
type: number
description: Weight value
exclusiveMinimum: 0
example: 14.5
unit:
$ref: '#/components/schemas/weight-units'
required:
- value
- unit
shipping-products-ref:
title: Shipping Product Code
type: object
properties:
code:
type: string
description: Sendcloud shipping product code
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
# --- truncated at 32 KB (99 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sendcloud/refs/heads/main/openapi/sendcloud-returns-api-openapi.yml