> ## 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 list of shipping methods
> Returns a detailed list of all the shipping methods which are available to you under your Sendcloud credentials.
**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).
You can use this endpoint to find a specific shipping method `id`, which you can then use in your request to the [Create a parcel or parcels](/api/v2/parcels/create-a-parcel-or-parcels) endpoint.
When creating a parcel via the [Create a parcel or parcels](/api/v2/parcels/create-a-parcel-or-parcels) endpoint, if a shipping method `id` value is present, and if the `request_label` parameter has the value `true`, then a shipping label is created and the parcel is announced.
The shipping methods returned from this endpoint are based on the following factors:
1. The carriers you have [enabled](/docs/getting-started/) in your Sendcloud account;
2. (Optional) The direct [carrier contracts](/docs/getting-started/carrier-contracts/) you have connected;
3. Your [sender address](/docs/getting-started/sender-address/)
**Tip:** Via this endpoint you can only retrieve shipping methods based on three parameters: `sender_address`, `service_point_id` and `is_return`. If you need to filter the results because you require a method which contains a specific shipping functionality or other criteria, you can refer to the [Retrieve a list of shipping products](/api/v2/shipping-products/retrieve-a-list-of-shipping-products) endpoint.
In order to view **remote surcharges**, you are required to provide the `to_country` and `to_postal_code`. Similarly, to access **zonal prices**, you need to provide `to_country`, `from_postal_code` and `to_postal_code`. This information ensures accurate and customized pricing based on the specific location, enabling you to understand any additional charges associated with remote areas and access pricing based on their designated zones.
## Specifying a sender address
You can have multiple sender addresses stored in your Sendcloud account. This endpoint will return the shipping methods associated with your **default** sender address, **unless** you provide a specific `sender_address` `id`.
**Tip:** You can find the `id` for each of your sender addresses via the [Retrieve a sender address](/api/v2/sender-addresses/retrieve-a-sender-address) endpoint.
For example, your default sender address may be based in the Netherlands, but you have a second sender address based in Austria. If you don't specify a `sender_address` `id`, this endpoint will **only** return shipping methods applicable for shipments from the Netherlands.
To see shipping methods applicable for Austria, e.g. from DPD Austria, specify the `id` for your Austrian sender address in the HTTP request. The retrieved results will now include carriers such as Post AT, DPD Austria, etc, depending on your [enabled carriers](/docs/getting-started/).
```http Example request method and URL
GET https://panel.sendcloud.sc/api/v2/shipping_methods?sender_address={ID}
```
## Find a service point delivery shipping method
If you want to retrieve a list of shipping methods which are applicable for **service point delivery**, provide a `service_point_id` as a query parameter. You can find an appropriate `service_point_id` via the [Service points API](/api/v2/service-points).
## Find a suitable shipping method for a return
Return shipping methods are treated differently than methods for outgoing parcels. If you want to filter the results to show only the methods which you can apply to return parcels, include the query parameter `is_return=true`.
## Invalid shipment ID error message
If you try to [Create a parcel](/api/v2/parcels/create-a-parcel-or-parcels) but receive the error message "Invalid shipment id", this could be because the specified `id` relates to a shipping method which is not possible for the given destination address.
For example, if you need to ship a parcel internationally but the specific shipping method only supports national (domestic) shipping, then you would need to lookup a new shipping method `id` which supports method of delivery and change the request.
## OpenAPI
````yaml /.openapi/v2/shipping-methods/openapi.yaml get /shipping_methods
openapi: 3.1.0
info:
title: Shipping methods
version: 2.0.0
description: >-
The Shipping methods API allows you to retrieve available shipping methods
for your Sendcloud account and get detailed information about each one.
contact:
name: Sendcloud API Support
url: https://www.sendcloud.dev
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/v2
description: Sendcloud Production
security: []
tags:
- name: Shipping Methods
paths:
/shipping_methods:
parameters: []
get:
tags:
- Shipping Methods
summary: Retrieve a list of shipping methods
description: >-
Returns a detailed list of all the shipping methods which are available
to you under your Sendcloud credentials.
operationId: sc-public-v2-scp-get-all_shipping_methods
parameters:
- schema:
type: string
in: query
name: sender_address
description: >-
The ID of the sender address for which you would like to know the
available shipping methods. If you want to retrieve all available
shipping methods, please use `all` as a value for this parameter.
Required if the carrier is zonal.
- schema:
type: integer
in: query
name: service_point_id
description: >-
The ID of the service point for which you would like to know the
available shipping methods.
- schema:
type: boolean
in: query
name: is_return
description: >-
If set to `true` the endpoint will return shipping methods which can
be used for making a return shipment.
- schema:
type: string
maxLength: 12
example: '01000'
in: query
name: from_postal_code
description: Postal code of the sender. Required if the carrier is zonal.
- schema:
type: string
maxLength: 12
example: '01000'
in: query
description: >-
Postal code of the recipient. Required if the carrier is zonal. Also
required to see if remote surcharges apply.
name: to_postal_code
- schema:
$ref: '#/components/schemas/country-codes'
in: query
name: to_country
description: >-
A country ISO 2 code for the recipient country. Required if the
carrier is zonal. Also required to see if remote surcharges apply.
- schema:
type: integer
in: query
name: cursor
description: >-
If `limit` is set, the result is divided into pages, `cursor` allows
you to iterate over these pages. Next and previous page urls are
returned in the result as well.
- schema:
type: integer
in: query
name: limit
description: >-
Sets amount of results to be returned per page, if not set all
results are returned.
responses:
'200':
description: OK
content:
application/json:
schema:
description: ''
type: object
properties:
shipping_methods:
type: array
uniqueItems: true
minItems: 1
description: Array of available shipping methods.
items:
$ref: '#/components/schemas/shipping-method'
required:
- shipping_methods
examples:
RetrieveShippingMethods:
summary: Retrieve a list of shipping methods
value:
next: null
previous: null
shipping_methods:
- id: 8020
name: DHLForYou Drop Off - Agecheck 18+
carrier: dhl
min_weight: '0.001'
max_weight: '23.001'
service_point_input: none
price: 0
countries:
- id: 2
name: Netherlands
price: 9.75
iso_2: NL
iso_3: NLD
lead_time_hours: 24
price_breakdown:
- type: price_without_insurance
label: Label
value: 8.55
- type: fuel
label: Fuel surcharge (14.00%)
value: 1.2
- id: 8021
name: DHLForYou - Agecheck 18+
carrier: dhl
min_weight: '0.001'
max_weight: '23.001'
service_point_input: none
price: 0
countries:
- id: 2
name: Netherlands
price: 10.01
iso_2: NL
iso_3: NLD
lead_time_hours: 24
price_breakdown:
- type: price_without_insurance
label: Label
value: 8.78
- type: fuel
label: Fuel surcharge (14.00%)
value: 1.23
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
components:
schemas:
country-codes:
type: string
title: Country Code Object
enum:
- AW
- AF
- AO
- AI
- AX
- AL
- AD
- AE
- AR
- AM
- AS
- AQ
- TF
- AG
- AU
- AT
- AZ
- BI
- BE
- BJ
- BQ
- BF
- BD
- BG
- BH
- BS
- BA
- BL
- BY
- BZ
- BM
- BO
- BR
- BB
- BN
- BT
- BV
- BW
- CF
- CA
- CC
- CH
- CL
- CN
- CI
- CM
- CD
- CG
- CK
- CO
- KM
- CV
- CR
- CU
- CW
- CX
- KY
- CY
- CZ
- DE
- DJ
- DM
- DK
- DO
- DZ
- EC
- EG
- ER
- EH
- ES
- EE
- ET
- FI
- FJ
- FK
- FR
- FO
- FM
- GA
- GB
- GE
- GG
- GH
- GI
- GN
- GP
- GM
- GW
- GQ
- GR
- GD
- GL
- GT
- GF
- GU
- GY
- HK
- HM
- HN
- HR
- HT
- HU
- ID
- IM
- IN
- IO
- IE
- IR
- IQ
- IS
- IL
- IT
- JM
- JE
- JO
- JP
- KZ
- KE
- KG
- KH
- KI
- KN
- KR
- KW
- LA
- LB
- LR
- LY
- LC
- LI
- LK
- LS
- LT
- LU
- LV
- MO
- MF
- MA
- MC
- MD
- MG
- MV
- MX
- MH
- MK
- ML
- MT
- MM
- ME
- MN
- MP
- MZ
- MR
- MS
- MQ
- MU
- MW
- MY
- YT
- NA
- NC
- NE
- NF
- NG
- NI
- NU
- NL
- 'NO'
- NP
- NR
- NZ
- OM
- PK
- PA
- PN
- PE
- PH
- PW
- PG
- PL
- PR
- KP
- PT
- PY
- PS
- PF
- QA
- RE
- RO
- RU
- RW
- SA
- SD
- SN
- SG
- GS
- SH
- SJ
- SB
- SL
- SV
- SM
- SO
- PM
- RS
- SS
- ST
- SR
- SK
- SI
- SE
- SZ
- SX
- SC
- SY
- TC
- TD
- TG
- TH
- TJ
- TK
- TM
- TL
- TO
- TT
- TN
- TR
- TV
- TW
- TZ
- UG
- UA
- UM
- UY
- US
- UZ
- VA
- VC
- VE
- VG
- VI
- VN
- VU
- WF
- WS
- YE
- ZA
- ZM
- ZW
- IC
- XK
description: A country represented by its ISO 3166-1 alpha-2 code
example: NL
shipping-method:
title: Shipping Method Object
description: A Sendcloud shipping method
type: object
properties:
id:
type: integer
minimum: 1
description: Unique identifier of the shipping method.
format: int64
name:
type: string
minLength: 1
description: >-
Name of the shipping method, it should give an idea what the
shipping method can be used for.
carrier:
type: string
minLength: 1
description: >-
A `carrier_code` which will indicate which carrier provides the
shipping method.
min_weight:
type: string
minLength: 5
description: Minimum allowed weight of the parcel for this shipping method.
max_weight:
type: string
minLength: 5
description: Maximum allowed weight of the parcel for this shipping method.
service_point_input:
type: string
minLength: 1
enum:
- required
- none
description: >-
Will be either `required` when the shipping method is meant to ship
a parcel to a service point, or `none` when this is not the case.
price:
type: integer
description: A legacy property which will always be `0`, should not be used!
format: int64
minimum: 0
maximum: 0
deprecated: true
countries:
type: array
description: A list of countries that you can ship to with the shipping method.
items:
type: object
properties:
id:
type: integer
format: int64
minimum: 1
description: Countries that you can ship to with the shipping method.
name:
type: string
description: Name of the country.
price:
type: number
description: >-
Indicates what it will cost to use the shipping method. Will
be 0 if the user has enabled a direct contract for
corresponding the carrier.
iso_2:
type: string
minLength: 2
maxLength: 2
example: NL
description: ISO 3166-1 alpha-2 code of the country.
iso_3:
type: string
example: NLD
minLength: 3
maxLength: 3
description: ISO 3166-1 alpha-3 code of the country.
lead_time_hours:
type: integer
description: Lead time of the shipping method in hours
nullable: true
price_breakdown:
$ref: '#/components/schemas/shipping-price-breakdown'
required:
- id
- name
- carrier
- min_weight
- max_weight
- service_point_input
- price
shipping-price-breakdown:
title: Shipping Price Breakdown Object
description: A Sendcloud shipping price breakdown.
type: array
items:
type: object
properties:
type:
type: string
example: price_without_insurance
description: Type of the price. It is an identifier of category of the price.
label:
type: string
example: Initial price per parcel
description: >-
This label is a friendly name for type of the price type and can
be used to represent it.
value:
type: number
format: float
example: 6.4
description: Price amount of the breakdown item.
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.
````