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
tags:
- name: Shipping Methods
paths:
/shipping_methods:
get:
summary: Retrieve a list of shipping methods
tags:
- Shipping Methods
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
operationId: sc-public-v2-scp-get-all_shipping_methods
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds:
- read:shipping-method
x-mint:
href: /api/v2/shipping-methods/retrieve-a-list-of-shipping-methods
content: |-
OAuth2 scopes required: `read:shipping-method`. See [Scopes for OAuth apps](/api/v3/scopes).
**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.
description: Returns a detailed list of all the shipping methods which are available to you under your Sendcloud credentials.
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
example: '01000'
maxLength: 12
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.
parameters: []
/shipping_methods/{id}:
parameters:
- schema:
type: integer
name: id
in: path
required: true
description: Shipping method id
get:
summary: Retrieve a shipping method
tags:
- Shipping Methods
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
shipping_method:
$ref: '#/components/schemas/shipping-method'
examples:
RetrieveShippingMethod:
summary: Retrieve a shipping method
value:
shipping_method:
id: 117
name: DHLForYou Drop Off
carrier: dhl
min_weight: '0.001'
max_weight: '20.000'
service_point_input: none
price: 0
countries:
- id: 1
name: Belgium
price: 7.9
iso_2: BE
iso_3: BEL
lead_time_hours: 24
- id: 2
name: Netherlands
price: 5.2
iso_2: NL
iso_3: NLD
lead_time_hours: 24
'404':
description: Not Found
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
request:
type: string
code:
type: integer
message:
type: string
examples:
NotFound:
summary: Not Found
value:
error:
request: api/v2/shipping_methods/0
code: 404
message: Not found.
operationId: sc-public-v2-scp-get-shipping_method_by_id
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds:
- read:shipping-method
x-mint:
href: /api/v2/shipping-methods/retrieve-a-shipping-method
content: |-
OAuth2 scopes required: `read:shipping-method`. See [Scopes for OAuth apps](/api/v3/scopes).
**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).
As described in the [Retrieve a list of shipping methods](/api/v2/shipping-methods/retrieve-a-list-of-shipping-methods) endpoint, to retrieve information about a shipping method which operates in a different country than your default sender address, provide a different `sender_address` `id`.
To see zonal carrier shipping methods, you need to provide the `to_country`, `from_postal_code` and `to_postal_code` query parameters.
description: Get information about a shipping method based on its `id` and your default sender address.
parameters:
- schema:
type: string
in: query
name: sender_address
description: The ID of the sender address for which you would like to know if the given shipping method is available.
- schema:
type: integer
in: query
name: service_point_id
description: The ID of the service point for which you would like to know if the given shipping method is available.
- schema:
type: boolean
in: query
name: is_return
description: If set to `true` the endpoint will return the shipping method only if it is a return shipping method.
- schema:
type: string
maxLength: 12
example: '01000'
in: query
name: from_postal_code
description: Postal code of the sender.
- schema:
type: string
example: '01000'
maxLength: 12
in: query
description: Postal code of the recipient.
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.
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:
read:analytics: View your shipping analytics
read:audit-log: View your account's audit log
read:brand: View your brands
write:brand: Manage your brands
write:carrier: Configure carriers and contracts
read:checkout: View your dynamic checkout configurations and templates
read:event-subscription: View your event subscriptions
write:event-subscription: Create and manage your event subscriptions
read:integration: View your integrations
write:integration: Connect and manage integrations
read:invoice: View your invoices
read:notification: View your notifications
write:notification: Manage your notifications
read:operational-settings: View your warehouses, shipping lanes, and other operational settings
write:operational-settings: Manage your warehouses, shipping lanes, and other operational settings
read:order: View your orders
write:order: Import and process your orders
read:organization: View organization settings
write:organization: Change organization settings
read:parcel: View your shipments and their tracking status
write:parcel: Create, announce, and cancel shipments
read:pickup: View carrier pickups and the options available for scheduling them
write:pickup: Schedule and manage carrier pickups
read:price: View shipping prices
write:product: Manage your product catalog
read:return: View your returns
write:return: Create and manage returns
read:return-settings: View your return settings
write:return-settings: Configure your return settings
read:service-point: View carrier service points
read:shipping-method: View shipping methods, products and prices
read:shipping-rule: View your shipping rules
write:shipping-rule: Create and manage shipping rules
read:support-ticket: View your support tickets
write:support-ticket: Manage your support tickets
read:tracking-message: View your tracking notifications
write:tracking-message: Manage your tracking notifications
read:tracking-page: View your tracking page
write:tracking-page: Customize your tracking page
read:user: Read your basic account information
schemas:
ShippingMethod:
$ref: '#/components/schemas/shipping-method'
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-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.
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