openapi: 3.1.0
info:
title: Dynamic Checkout
description: |-
Boost your conversion rate and offer an unbeatable delivery experience to your customers via Sendcloud. [Dynamic Checkout](https://support.sendcloud.com/hc/en-us/articles/360057943512-Dynamic-Checkout) provides everything you need to optimize your checkout page and let your customers choose when and how they want to receive their orders.
Activate any of our [160+ supported carriers](https://www.sendcloud.com/carriers/) (including 10+ international carriers) to create a first class shipping experience. Customize the methods you want to offer **per delivery country** and choose which delivery options will appear on your checkout page:
- **Nominated day delivery** allows your customers to pick a preferred delivery day
- **Same-day delivery** lets you stay ahead of the competition with the fastest possible delivery services
- **Standard delivery** provides next-day, standard and international shipping options via a huge range of flexible shipping methods
- **Service point delivery** allows your customers to pick a preferred service point
Delivery options are configured directly via the Sendcloud platform, so you can create, customize and publish your checkout page in a matter of minutes.
>**Tip:** You can find the full documentation for setting up your [Dynamic Checkout](https://support.sendcloud.com/hc/en-us/sections/4404607546132-Dynamic-Checkout) configuration, and learn more about the different delivery options and supporting carriers, on our Help Center.
version: 2.0.0
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: Delivery options
description: Delivery options based on checkout configuration.
paths:
/checkout/configurations/{configuration_id}/delivery-options:
get:
summary: Retrieve a list of delivery options
operationId: sc-public-v2-checkout-get-delivery_options
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds:
- read:checkout
tags:
- Delivery options
x-mint:
href: /api/v2/dynamic-checkout/retrieve-a-list-of-delivery-options
content: |-
OAuth2 scopes required: `read:checkout`. 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).
To use this API, you first need to [create your own Dynamic Checkout configuration](https://support.sendcloud.com/hc/en-us/articles/360057944932-How-to-configure-Dynamic-Checkout) in the Sendcloud platform.
To get started, take the following steps:
1. Log in to your Sendcloud account and go to **Dynamic Checkout**.
2. Select your API integration from the **Shops** menu to customize your delivery options.
3. When you're done, click **Publish** to apply your configuration to your API integration.
This API allows you to let your customers pick delivery options. The options returned via this endpoint are based on the [delivery methods](https://support.sendcloud.com/hc/en-us/articles/360057944932-How-to-configure-Dynamic-Checkout#4) they previously configured, in addition to cart/order information, e.g. parcel weight, total order value, destination country, etc.
Then you can present the returned delivery options to your customer on your checkout page, where they can select their preferred option for their order.
## How do delivery options correspond to configured delivery methods?
This API returns one delivery option per carrier configured in Dynamic Checkout. If a delivery method is configured with multiple carriers, then multiple delivery options will be returned - one per carrier. In cases when delivery options correspond to the same delivery method, delivery options' ids will refer to the same delivery method id, leaving API users with a flexibility to perform grouping based on a delivery method id, if desired.
Only the [Service point delivery method](https://support.sendcloud.com/hc/en-us/articles/4414674483860) currently allows for selection of multiple carriers. Hence, multiple delivery options will be returned only for a delivery method of this type.
## How can I create a parcel out of the selected delivery option?
You'll need to make an API call to the [Create a parcel or parcels](/api/v2/parcels/create-a-parcel-or-parcels) endpoint, passing `request_label=true` and `shipping_method_id={checkout_identifier.value}`, where the `checkout_identifier` field refers to the identifier of the selected delivery option.
description: Get a list of delivery options to display in your checkout page, based on your Dynamic Checkout configuration in the Sendcloud platform.
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/DeliveryOptionsResponse'
examples:
NominatedDayDeliveryOption:
summary: Nominated day delivery option
value:
configuration_id: bae462c1-d659-48d0-aacd-fb7e3550de14
delivery_options:
- id: 068607a1-f591-47c6-af47-fcbb01dcdfd9
title: PostNL Delivery - Signature Required
internal_title: postnl sameday signature
description: Choose a delivery day yourself!
delivery_method_type: nominated_day_delivery
cut_off_time: '2022-08-08T15:00:00+01:00'
checkout_identifier:
type: method_id
value: 123
shipping_rate:
value: '8'
currency: EUR
carrier:
code: postnl
name: PostNL
logo_url: https://sendcloud-prod-scp-static-files.s3.amazonaws.com/postnl/img/logo.svg
delivery_dates:
- delivery_date: '2022-08-09T16:00:00+01:00'
parcel_handover_date: '2022-08-08T16:00:00+01:00'
- delivery_date: '2022-08-10T16:00:00+01:00'
parcel_handover_date: '2022-08-08T16:00:00+01:00'
- delivery_date: '2022-08-11T16:00:00+01:00'
parcel_handover_date: '2022-08-08T16:00:00+01:00'
lead_time_hours:
p10: 24
p20: 24
p30: 48
p40: 48
p50: 72
p60: 72
p70: 96
p80: 96
p90: 120
p95: 144
sustainability_rating: medium
is_order_overweight: false
allowed_weight:
min:
value: '0.001'
unit: kg
max:
value: '23.001'
unit: kg
is_delivery_zone_configured: true
is_delivery_zone_excluded: false
SameDayDeliveryOption:
summary: Same day delivery option
value:
configuration_id: bae462c1-d659-48d0-aacd-fb7e3550de14
delivery_options:
- id: ec9ce3b9-7d3f-4298-bc1c-8f3aaa8d27e9
title: Trunkrs Delivery - Sameday
internal_title: trunkrs delivery
description: Order now and get your delivery today!
delivery_method_type: same_day_delivery
cut_off_time: '2022-08-08T15:00:00+01:00'
checkout_identifier:
type: method_id
value: 123
shipping_rate:
value: '8'
currency: GBP
carrier:
code: trunkrs
name: Trunkrs
logo_url: https://sendcloud-prod-scp-static-files.s3.amazonaws.com/trunkrs/img/logo.svg
delivery_dates:
- delivery_date: '2022-08-08T20:00:00+01:00'
parcel_handover_date: '2022-08-08T16:00:00+01:00'
lead_time_hours:
p10: 0
p20: 0
p30: 0
p40: 0
p50: 0
p60: 0
p70: 0
p80: 24
p90: 24
p95: 24
sustainability_rating: low
is_order_overweight: false
allowed_weight:
min:
value: '0.001'
unit: kg
max:
value: '23.001'
unit: kg
is_delivery_zone_configured: true
is_delivery_zone_excluded: false
StandardDeliveryOption:
summary: Standard delivery option
value:
configuration_id: bae462c1-d659-48d0-aacd-fb7e3550de14
delivery_options:
- id: 431c1736-9a8f-480a-bf27-234016918417
title: DHL Delivery - Standard
internal_title: dhl standard
description: You get it when you get it ;)
delivery_method_type: standard_delivery
cut_off_time: '2022-08-08T15:00:00+01:00'
checkout_identifier:
type: method_id
value: 123
shipping_rate:
value: '3'
currency: USD
carrier:
code: dhl
name: DHL
logo_url: https://sendcloud-prod-scp-static-files.s3.amazonaws.com/dhl/img/logo.svg
delivery_dates: null
lead_time_hours:
p10: 48
p20: 48
p30: 72
p40: 72
p50: 96
p60: 96
p70: 120
p80: 120
p90: 144
p95: 168
sustainability_rating: high
is_order_overweight: false
allowed_weight:
min:
value: '0.001'
unit: kg
max:
value: '23.001'
unit: kg
is_delivery_zone_configured: true
is_delivery_zone_excluded: false
ServicePointDeliveryOptions:
summary: Service point delivery options
value:
configuration_id: bae462c1-d659-48d0-aacd-fb7e3550de14
delivery_options:
- id: es9ce3b9-7d3f-4298-bc1c-8f3aaa8d27d6
title: Servicepoint delivery
internal_title: postnl servicepoint delivery
description: Choose a service point for your delivery
delivery_method_type: service_point_delivery
cut_off_time: null
checkout_identifier:
type: method_id
value: 123
shipping_rate:
value: '8'
currency: EUR
carrier:
code: postnl
name: PostNL
logo_url: https://sendcloud-prod-scp-static-files.s3.amazonaws.com/postnl/img/logo.svg
delivery_dates: null
lead_time_hours: null
sustainability_rating: null
is_order_overweight: false
allowed_weight:
min:
value: '0.001'
unit: kg
max:
value: '23.001'
unit: kg
- id: es9ce3b9-7d3f-4298-bc1c-8f3aaa8d27d6
title: Servicepoint delivery
internal_title: dpd servicepoint delivery
description: Choose a service point for your delivery
delivery_method_type: service_point_delivery
cut_off_time: null
checkout_identifier:
type: method_id
value: 456
shipping_rate:
value: '8'
currency: EUR
carrier:
code: dpd
name: DPD
logo_url: https://sendcloud-prod-scp-static-files.s3.amazonaws.com/dpd/img/logo.svg
delivery_dates: null
lead_time_hours: null
sustainability_rating: null
is_order_overweight: false
allowed_weight:
min:
value: '0.001'
unit: kg
max:
value: '23.001'
unit: kg
is_delivery_zone_configured: true
is_delivery_zone_excluded: false
NoDeliveryOptionsDeliveryZoneExcluded:
summary: No delivery options due to the provided postal code matching delivery zone exclusion rules
value:
configuration_id: bae462c1-d659-48d0-aacd-fb7e3550de14
delivery_options: []
is_delivery_zone_configured: true
is_delivery_zone_excluded: true
'400':
$ref: '#/components/responses/Error400BadRequest'
'404':
$ref: '#/components/responses/Error404NotFound'
parameters:
- $ref: '#/components/parameters/ConfigurationID'
- $ref: '#/components/parameters/Weight'
- $ref: '#/components/parameters/Value'
- $ref: '#/components/parameters/FromCountry'
- $ref: '#/components/parameters/ToCountry'
- $ref: '#/components/parameters/CheckoutIdentifierType'
- $ref: '#/components/parameters/ToPostalCode'
- $ref: '#/components/parameters/ParcelLength'
- $ref: '#/components/parameters/ParcelWidth'
- $ref: '#/components/parameters/ParcelHeight'
- $ref: '#/components/parameters/CheckoutMetadata'
components:
schemas:
DeliveryOptionsResponse:
title: Delivery Options Response Object
description: A delivery options response
type: object
properties:
configuration_id:
type: string
format: uuid
example: bae462c1-d659-48d0-aacd-fb7e3550de14
description: Checkout configuration id from which delivery options will be processed and retrieved
readOnly: true
delivery_options:
type: array
description: List of available delivery options based on the current cart/order information provided at the time of the request
uniqueItems: true
example:
- id: ec9ce3b9-7d3f-4298-bc1c-8f3aaa8d27e9
title: Trunkrs Delivery - Sameday
internal_title: trunkrs delivery
description: Order now and get your delivery today!
delivery_method_type: same_day_delivery
cut_off_time: '2022-08-08T15:00:00+01:00'
checkout_identifier:
type: method_id
value: 123
shipping_rate:
value: '8'
currency: GBP
carrier:
code: trunkrs
name: Trunkrs
logo_url: https://sendcloud-prod-scp-static-files.s3.amazonaws.com/trunkrs/img/logo.svg
delivery_dates:
- delivery_date: '2022-08-08T20:00:00+01:00'
parcel_handover_date: '2022-08-08T16:00:00+01:00'
lead_time_hours:
p10: 0
p20: 0
p30: 0
p40: 0
p50: 0
p60: 0
p70: 0
p80: 24
p90: 24
p95: 24
sustainability_rating: low
is_order_overweight: false
allowed_weight:
min:
value: '0.001'
unit: kg
max:
value: '23.001'
unit: kg
items:
$ref: '#/components/schemas/DeliveryOption'
readOnly: true
is_delivery_zone_configured:
type: boolean
example: true
description: Indicates whether the selected delivery country corresponds to a configured delivery zone in the checkout configuration
readOnly: true
is_delivery_zone_excluded:
type: boolean
example: false
description: |
Indicates whether the matched delivery zone is explicitly excluded by exclusion rules in the checkout settings. For instance, a specific location or an entire region can be excluded based on postal code exclusion rules, resulting in an empty list of delivery options
readOnly: true
required:
- configuration_id
- delivery_options
- is_delivery_zone_configured
- is_delivery_zone_excluded
ErrorObject:
title: Error Object
type: object
required:
- error
properties:
error:
type: object
required:
- request
- code
- message
properties:
request:
type: string
code:
type: integer
enum:
- 400
- 401
- 404
message:
type: string
DeliveryOption:
title: Delivery Option
type: object
description: Delivery option that is available at the time of the request based on the passed cart/order details. The delivery option is computed from the configured [delivery method type](https://support.sendcloud.com/hc/en-us/articles/360057944932-How-to-configure-Dynamic-Checkout#4).
properties:
id:
type: string
format: uuid
example: 068607a1-f591-47c6-af47-fcbb01dcdfd9
description: Delivery method id which fits/is available for the current cart/order and can be used as a delivery option
readOnly: true
title:
type: string
example: PostNL Delivery - Signature Required
minLength: 1
description: Delivery method/option public title
readOnly: true
internal_title:
type: string
example: postnl sameday signature
minLength: 1
description: Delivery method/option internal title
readOnly: true
description:
type:
- string
- 'null'
example: Order now and get your delivery today!
minLength: 0
description: Delivery method/option description
readOnly: true
delivery_method_type:
type: string
enum:
- standard_delivery
- same_day_delivery
- nominated_day_delivery
- service_point_delivery
description: Matched [delivery method type](https://support.sendcloud.com/hc/en-us/articles/360057944932-How-to-configure-Dynamic-Checkout#4)
example: same_day_delivery
readOnly: true
cut_off_time:
type:
- string
- 'null'
example: '2022-08-08T15:00:00+01:00'
description: The time until which a delivery option is valid and can be selected by the end buyer. It returns the corresponding delivery method [cut-off time](https://support.sendcloud.com/hc/en-us/articles/4404548941460#6), as configured by the merchant in Dynamic Checkout.
format: date-time
readOnly: true
checkout_identifier:
type: object
description: Defines the way of getting the shipping label via Sendcloud. Currently, we only support the `method_id` type, therefore, in every delivery option you will find the `checkout_identifier` object. This contains the shipping method ID, which is used in the [Create a parcel or parcels](/api/v2/parcels/create-a-parcel-or-parcels) endpoint and to retrieve the shipping label.
minProperties: 2
required:
- type
- value
properties:
type:
type: string
enum:
- method_id
description: Checkout identifier type which will be used to get the shipping label.
readOnly: true
value:
type: integer
minimum: 1
example: 3542
description: Checkout identifier corresponding value. For example, if the type is `method_id` the value will represent the id of the method as `3542`
readOnly: true
readOnly: true
shipping_rate:
type: object
description: The shipping rate for the specific retrieved delivery method, taking into account weight based rates and the `free_from` value. [Shipping rates](https://support.sendcloud.com/hc/en-us/articles/4414673031700-How-to-add-Dynamic-Checkout-rates) can be configured in the Sendcloud platform via the Dynamic Checkout tab.
required:
- value
- currency
properties:
value:
type:
- string
- 'null'
minLength: 1
example: '8'
description: |-
Rate price which is calculated based on the given cart/order details and the configured delivery methods for the passed Dynamic Checkout configuration.
* `value > 0` If [shipping rates](https://support.sendcloud.com/hc/en-us/articles/4414673031700-How-to-add-Dynamic-Checkout-rates) for the currently matched delivery method are enabled and configured, and the cart/order weight matches one of the configured shipping rate weight classes.
* `value = 0` If cart/order value > shipping rate `free_from` value or if value set to 0 explicitly on the shipping rate.
* `value is null` If shipping rates for the currently matched delivery method isn't enabled and configured.
readOnly: true
currency:
type: string
description: Rate currency, which is based on the passed checkout configuration id
example: EUR
readOnly: true
readOnly: true
carrier:
type: object
description: Matched carrier based on the passed cart/order details and the configured delivery methods [shipping product functionalities](https://support.sendcloud.com/hc/en-us/articles/4404557152788#2).
minProperties: 3
maxProperties: 3
required:
- code
- name
- logo_url
properties:
code:
$ref: '#/components/schemas/carrier'
name:
type: string
example: PostNL
description: Carrier friendly name
minLength: 1
readOnly: true
logo_url:
type: string
format: uri
example: https://sendcloud-prod-scp-static-files.s3.amazonaws.com/postnl/img/logo.svg
description: Carrier logo URL
minLength: 12
readOnly: true
readOnly: true
delivery_dates:
type:
- array
- 'null'
maxItems: 14
uniqueItems: true
description: |-
Available delivery dates which can be presented in the shop checkout page, so that the end customer can choose a date on which to have their parcel delivered.
Returned dates are timezone aware, and based on the delivery method [timezone configuration](https://support.sendcloud.com/hc/en-us/articles/4404776025236-Dynamic-Checkout-Standard-delivery-#2).
Delivery dates are calculated based on:
1. Carrier delivery days
2. Configured parcel handover days in the Sendcloud platform
3. Configured cut off time in the Sendcloud platform
4. Any holidays configured in the Sendcloud platform
* If `delivery_method_type=standard_delivery` or `delivery_method_type=service_point_delivery`, `delivery_dates` will be returned as `null`. The parcel can be handed over by the merchant to the carrier at any time.
* If `delivery_method_type=same_day_delivery`, `delivery_dates` will have **only one option**.
* If `delivery_method_type=nominated_day_delivery`, `delivery_dates` will have up to **14 options** and dates will be sorted from soonest to furthest.
items:
type: object
maxProperties: 2
minProperties: 2
properties:
delivery_date:
type: string
example: '2022-08-09T16:00:00+01:00'
description: Define when the parcel will be delivered to the customer
format: date-time
readOnly: true
parcel_handover_date:
type: string
example: '2022-08-08T16:00:00+01:00'
description: Define when the parcel will be handed over to the carrier by the merchant
format: date-time
readOnly: true
required:
- delivery_date
- parcel_handover_date
readOnly: true
readOnly: true
lead_time_hours:
type: object
description: |-
Estimated shipping lead times, in hours,
representing how long it typically takes from when the parcel is shipped to when the first delivery attempt is made.
This data is useful for tracking and optimizing delivery times.
These figures are based on historical data and are not specific to any individual parcel.
The estimates are broken down by percentiles (`p10` to `p95`),
which indicate how many hours it takes for different percentages of parcels to be delivered.
For example:
- If `p50` is **72**, it means that **50%** of parcels are delivered within **72 hours** or less.
- If `p90` is **120**, it means that **90%** of parcels are delivered within **120 hours** or less.
properties:
p10:
type: integer
description: Estimated delivery time in hours for the 10th percentile.
example: 1
p20:
type: integer
description: Estimated delivery time in hours for the 20th percentile.
example: 1
p30:
type: integer
description: Estimated delivery time in hours for the 30th percentile.
example: 2
p40:
type: integer
description: Estimated delivery time in hours for the 40th percentile.
example: 2
p50:
type: integer
description: Estimated delivery time in hours for the 50th percentile (median).
example: 3
p60:
type: integer
description: Estimated delivery time in hours for the 60th percentile.
example: 3
p70:
type: integer
description: Estimated delivery time in hours for the 70th percentile.
example: 4
p80:
type: integer
description: Estimated delivery time in hours for the 80th percentile.
example: 4
p90:
type: integer
description: Estimated delivery time in hours for the 90th percentile.
example: 5
p95:
type: integer
description: Estimated delivery time in hours for the 95th percentile.
example: 6
required:
- p10
- p20
- p30
- p40
- p50
- p60
- p70
- p80
- p90
- p95
nullable: true
readOnly: true
sustainability_rating:
type: string
enum:
- low
- medium
- high
description: 'A string representing how environmentally friendly the delivery option is, with possible values being: **low**, **medium**, and **high**, based on factors such as delivery location, delivery time, and the type of delivery vehicle.'
example: medium
nullable: true
readOnly: true
is_order_overweight:
type: boolean
example: false
description: Indicates whether the total order weight exceeds the maximum allowed weight for the selected delivery option.
readOnly: true
allowed_weight:
type: object
description: Weight range allowed for this delivery option.
properties:
min:
$ref: '#/components/schemas/Weight'
description: Minimum allowed parcel dimensions for this option.
max:
$ref: '#/components/schemas/Weight'
description: Maximum allowed parcel dimensions for this option.
readOnly: true
required:
- id
- title
- internal_title
- description
- delivery_method_type
- cut_off_time
- checkout_identifier
- shipping_rate
- carrier
- delivery_dates
- lead_time_hours
- sustainability_rating
- is_order_overweight
- allowed_weight
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
carrier:
type: string
title: Carrier Code
enum:
- amazon
- bol
- bpost
- brt
- budbee
- chronopost
- cirro
- colisprive
- colissimo
- correos
- correos_express
- ctt_express
- dbschenker
- delivengo
- dhl
- dhl_2_man_handling
- dhl_de
- dhl_ecommerce
- dhl_express
- dhl_parcel_gb
- dhl_parcel_iberia
- dp
- dpd
- dpd_at
- dpd_fr
- dpd_gb
- dpd_local
- evri_international
- fadello
- fairsenden
- fedex
- fedexcrossborder
- fietskoeriers
- geodis
- glovo
- gls_de
- gls_es
- gls_eu
- gls_it
- gls_nl
- hermes_at
- hermes_c2c_gb
- hermes_de
- hermes_gb
- hived
- homerr
- hurby
- inpost_es
- inpost_gb
- inpost_it
- inpost_pl
- lettresuivie
- mhi
- mondial_relay
- mrw
- nacex
- paack
- parcelforce
- plx
- postat
- poste_italiane
- poste_it_delivery
- postnl
- postnl_fulfilment
- postnl_large
- postnord
- rjp
- rjpv2
- royal_mail
- sandd
- sendcloud
- seur
- skymail
- spring
- storeshippers
- tipsa
- tnt_it
- transforce
- trunkrs
- ups
- van_straaten
- viatim
- yodel
description: A carrier represented by a Sendcloud code
example: postnl
WeightUnit:
title: Mass Units Object
type: string
enum:
- kg
- g
- lbs
- oz
example: g
Weight:
title: Weight
type: object
description: Weight in the specified unit
properties:
value:
type: string
description: Weight value
example: '3.6'
unit:
$ref: '#/components/schemas/WeightUnit'
required:
- value
- unit
FastAPI401Error:
title: Unauthorized Error Object
type: object
description: Unauthorized. The client’s request lacks valid authentication credentials for the target resource.
properties:
request:
type: string
status:
type: integer
enum:
- 401
errors:
type: array
items:
type: object
properties:
code:
type: string
enum:
- unauthorized
message:
type: string
required:
- request
- status
- errors
example:
request: /api/v2/checkout/configurations/9f021a0c-94d1-4c4c-8b63-3c930953d620/delivery-options
status: 401
errors:
- code: unauthorized
message: Invalid credentials
Oathkeeper401Error:
title: OAuth2 Unauthorized Object
description: Unauthorized. The client’s request lacks valid authentication credentials for the target resource.
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
properties:
code:
type: number
enum:
- 401
status:
type: string
enum:
- Unauthorized
message:
type: string
request:
type: string
reason:
type: string
example:
error:
code: 401
status: Unauthorized
reason: Access token is not active
message: Access credentials are invalid
responses:
Error400BadRequest:
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorObject'
examples:
ValidationError:
summary: Validation Error
value:
error:
code: 400
request: api/v2/checkout/465e2fe8-4589-4ae2-b49c-0c64153e5169/delivery-options
message: 'from_country: "This field is required."'
Error401Unauthorized:
$ref: '#/components/responses/FastAPI401'
Error403Forbidden:
description: Forbidden
Error404NotFound:
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorObject'
examples:
NotFound:
summary: Not found
value:
error:
request: api/v2/checkout/465e2fe8-4589-4ae2-b49c-0c64153e5169/delivery-options
code: 404
message: Not found.
FastAPI401:
description: The HTTP 401 Unauthorized error indicates that the request made by the client lacks valid authentication credentials for the target resource. This may be due to missing, incorrect, or expired authentication tokens. This status code is often accompanied by a WWW-Authenticate header, which provides information on how to authorize correctly. To rectify this issue, the client should re-authenticate with valid credentials. If the error persists, the client may not have permission to access the requested resource.
headers:
www-authenticate:
schema:
type: string
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/FastAPI401Error'
- $ref: '#/components/schemas/Oathkeeper401Error'
parameters:
ConfigurationID:
name: configuration_id
in: path
schema:
type: string
format: uuid
example: 465e2fe8-4589-4ae2-b49c-0c64153e5169
description: Checkout configuration id from which delivery options will be retrieved
required: true
Weight:
name: weight
in: query
schema:
type: integer
example: 2500
minimum: 1
description: Total order/cart weight in grams
required: true
Value:
name: value
in: query
schema:
type: string
example: '45.90'
minLength: 1
description: Total order/cart price value
required: true
FromCountry:
name: from_country
in: query
schema:
$ref: '#/components/schemas/country-codes'
description: The sender country of the shipment, as an [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
required: true
ToCountry:
name: to_country
in: query
schema:
$ref: '#/components/schemas/country-codes'
description: The receiver country of the shipment, as an [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
required: true
CheckoutIdentifierType:
name: checkout_identifier_type
in: query
required: false
schema:
type: string
default: method_id
enum:
- method_id
description: Defines the way of getting the shipping label via Sendcloud. Currently, we only support the `method_id` type, therefore, in every delivery option you will find the `checkout_identifier` object. This contains the shipping method ID, which is used in the [Create a parcel or parcels](/api/v2/parcels/create-a-parcel-or-parcels) and to retrieve the shipping label.
ToPostalCode:
name: to_postal_code
in: query
required: false
schema:
type: string
example: 5611EM
maxLength: 15
description: Postal code of the recipient. This field can be used in combination with Checkout Rules to show or hide delivery options in certain locations.
ParcelLength:
name: parcel_length
in: query
required: false
schema:
type: number
example: 48
description: 'Parcel length in centimeters. Examples: "48" or "52.3"'
ParcelWidth:
name: parcel_width
in: query
required: false
schema:
type: number
example: 48
description: 'Parcel width in centimeters. Examples: "48" or "52.3"'
ParcelHeight:
name: parcel_height
in: query
required: false
schema:
type: number
example: 48
description: 'Parcel height in centimeters. Examples: "48" or "52.3"'
CheckoutMetadata:
name: checkout_metadata
in: query
required: false
schema:
type: string
example: demo_sku_12345
maxLength: 128
description: Arbitrary text data that can be used in combination with Checkout Rules to show or hide delivery options based on the value provided. For example, it can be used to filter delivery options based on the product SKU
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