Composite v3 flow that turns an existing order into a shipment, requests a label, and returns a usable parcel in one call.
Sendcloud Ship an Order API v3 is one of 20 APIs that Sendcloud publishes on the APIs.io network, described by a machine-readable OpenAPI specification.
Tagged areas include Orders, Shipping, and Fulfillment. The published artifact set on APIs.io includes API documentation and an OpenAPI specification.
openapi: 3.1.0
info:
title: Ship an Order
version: 3.0.0
contact:
name: Sendcloud API Support
email: [email protected]
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
description: |
The Sendcloud Ship an Order API
## What can you do with this API?
- [Create Labels for orders](/docs/orders/ship-an-order/).
servers:
- url: https://panel.sendcloud.sc/api/v3
description: Sendcloud Production
tags:
- name: Ship an Order
description: OrderLabelAPI
paths:
/orders/create-labels-async:
post:
tags:
- Ship an Order
operationId: sc-public-v3-orders_labels-post-create_labels_async
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
summary: Request a label for one or more orders asynchronously
description: >-
Request a label for a single or multiple orders. This endpoint will fail
gracefully if some orders cannot be processed, returning any
successfully created labels along with error details for the orders that
failed.
x-mint:
href: >-
/api/v3/ship-an-order/request-a-label-for-one-or-more-orders-asynchronously
content: >-
To retrieve your documents or view announcement errors, use the `id`
of the relevant shipment with the [Retrieve a
shipment](/api/v3/shipments/retrieve-a-shipment) endpoint.
To apply shipping rules to the orders, make sure to set
`apply_shipping_rules` to `true`.
This endpoint will attempt to generate labels for each order. If a
request for one label errors, it will still attempt to generate the
other labels. Because of this, the response might return a mix of
labels and errors. Use the errors `source` `pointer` field to see
which labels encountered a problem.
<Note>
If you create orders via the [Orders
API](/api/v3/orders/create-update-orders-in-batch) and then
immediately request labels, the orders may not yet be available. Order
saving is **asynchronous**. A successful `201` response from the
Orders API does not guarantee the order is immediately ready for
shipping. Before calling this endpoint, verify the order exists by
retrieving it with the [Retrieve an
order](/api/v3/orders/retrieve-an-order) endpoint.
</Note>
parameters:
- $ref: '#/components/parameters/SendcloudPartnerId'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/create-labels-async'
examples:
CreateSingleLabelAsync:
summary: Create a label for a specific order.
description: Create a single shipping label for the order you want to ship.
value:
integration_id: 70
orders:
- order_number: ORDER-25763
apply_shipping_rules: false
CreateLabelUsingSenderAddressIDAsync:
summary: Create a label for a specific order using a sender address ID.
description: >-
Create a single shipping label where the sender address is
being supplied through ID.
value:
integration_id: 70
sender_address_id: 17
orders:
- order_number: ORDER-25763
CreateLabelUsingBrandIDAsync:
summary: Create a label for a specific order using a brand ID.
description: >-
Create a single shipping label where the brand is being set
through ID.
value:
integration_id: 70
brand_id: 42
orders:
- order_number: ORDER-25763
CreateLabelUsingShipWithAsync:
summary: >-
Create a label for a specific order using a specific shipping
option.
description: >-
Create a single shipping label where the carrier and the
shipping functionalities are defined by the supplied
shipping_option_code.
value:
integration_id: 70
ship_with:
type: shipping_option_code
properties:
contract_id: 517
shipping_option_code: postnl:standard
orders:
- order_number: ORDER-25763
CreateLabelsAsync:
summary: Create a label for a multiple orders.
description: >-
Create shipping labels for orders you want to sent to your
customers.
value:
integration_id: 70
orders:
- order_number: ORDER-257633
apply_shipping_rules: false
- order_id: d59e8b1c-04ca-4b38-90cf-e11083506e22
CreateMulticolloLabelAsync:
summary: Create multiple labels for an order.
description: >-
Create shipping labels for order you want to sent in multiple
parcels.
value:
integration_id: 70
orders:
- order_number: ORDER-25763
parcels:
- parcel_items:
- item_id: '5552'
quantity: 1
- item_id: '5555'
quantity: 2
dimensions:
length: '5.00'
width: '15.00'
height: '20.00'
unit: cm
weight:
value: '1.320'
unit: kg
- parcel_items:
- item_id: '5552'
quantity: 1
- item_id: '763'
quantity: 12
dimensions:
length: '10.00'
width: '12.00'
height: '30.00'
unit: cm
weight:
value: '2.2'
unit: kg
apply_shipping_rules: false
responses:
'202':
description: Information about the created parcels.
content:
application/json:
schema:
type: object
properties:
data:
type: array
description: >-
An array containing the created parcel IDs and other order
information.
minItems: 0
items:
$ref: '#/components/schemas/label-async'
errors:
type:
- array
items:
type: object
allOf:
- $ref: '#/components/schemas/ErrorObject'
required:
- status
- code
- detail
examples:
AllLabelsSuccessful:
description: All the requested labels were successfully generated.
value:
data:
- parcel_id: 420
parcels_ids:
- 420
shipment_id: '511'
order_id: 593c853e-ca90-4ab4-953c-fd2f47dd8dc3
order_number: ORD-2024-00174
- parcel_id: 4428
parcels_ids:
- 4428
shipment_id: '512'
order_id: '23458265234'
order_number: ORD-2024-00166
MulticolloLabelsSuccessful:
description: A single order shipped in multiple parcels.
value:
data:
- parcel_id: 420
parcels_ids:
- 420
- 421
- 422
shipment_id: '511'
order_id: 593c853e-ca90-4ab4-953c-fd2f47dd8dc3
order_number: ORD-2024-00174
SomeLabelsContainErrors:
description: >-
Some labels were generated, while others encountered an
error.
value:
data:
- parcel_id: 420
parcels_ids:
- 420
shipment_id: '511'
order_id: 593c853e-ca90-4ab4-953c-fd2f47dd8dc3
order_number: ORD-2024-00174
errors:
- status: '400'
code: validation_error
title: Invalid order
detail: The order has no valid shipping address.
source:
pointer: /data/attributes/orders/[1]
SenderAddressIDDoesNotExist:
description: Sender Address does not exist.
value:
errors:
- status: '404'
code: invalid
detail: Does not exist.
source:
pointer: /data/attributes/sender_address_id
LabelsSuccessfulWithShipWith:
description: >-
All the requested labels were successfully generated using
the provided `ship_with` option.
value:
data:
- parcel_id: 420
shipment_id: '511'
order_id: 593c853e-ca90-4ab4-953c-fd2f47dd8dc3
order_number: ORD-2024-00174
ship_with:
type: shipping_option_code
properties:
contract_id: 517
shipping_option_code: postnl:standard
- parcel_id: 4428
shipment_id: '512'
order_id: '23458265234'
order_number: ORD-2024-00166
ship_with:
type: shipping_option_code
properties:
contract_id: 517
shipping_option_code: postnl:standard
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
examples:
InvalidOrderId:
summary: The provided order_id is not a valid string.
value:
errors:
- detail: Input should be a valid string
status: '400'
source:
pointer: /data/attributes/orders/0/order_id
code: invalid
'404':
$ref: '#/components/responses/NotFound'
/orders/create-label-sync:
post:
tags:
- Ship an Order
operationId: sc-public-v3-orders_labels-post-create_labels_sync
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
summary: Request a label for a single order synchronously
description: >-
Request a label for a single order and wait for the results. The label
and any other documents will be provided in the response to this
request.
x-mint:
href: /api/v3/ship-an-order/request-a-label-for-a-single-order-synchronously
content: >-
<Note>
If you create orders via the [Orders
API](/api/v3/orders/create-update-orders-in-batch) and then
immediately request a label, the order may not yet be available. Order
saving is **asynchronous**. A successful `201` response from the
Orders API does not guarantee the order is immediately ready for
shipping. Before calling this endpoint, verify the order exists by
retrieving it with the [Retrieve an
order](/api/v3/orders/retrieve-an-order) endpoint.
</Note>
parameters:
- $ref: '#/components/parameters/SendcloudPartnerId'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/create-labels-sync'
examples:
CreateSingleLabelSync:
summary: Create a label for a specific order.
description: Create a shipping label for the order you want to ship.
value:
integration_id: 70
label_details:
mime_type: application/pdf
dpi: 72
order:
order_number: ORDER-25763
apply_shipping_rules: false
CreateLabelUsingShipWithSync:
summary: >-
Create a label for a specific order using a specific shipping
option.
description: >-
Create a single shipping label where the carrier and the
shipping functionalities are defined by the supplied
`shipping_option_code`.
value:
integration_id: 70
ship_with:
type: shipping_option_code
properties:
contract_id: 517
shipping_option_code: postnl:standard
order:
- order_number: ORDER-25763
CreateLabelUsingSenderAddressIDSync:
summary: Create a label for a specific order using a sender address ID.
description: Create a shipping label using a specific sender address.
value:
integration_id: 70
sender_address_id: 17
label_details:
mime_type: application/pdf
dpi: 72
orders:
- order_number: ORDER-25763
CreateLabelUsingBrandIDSync:
summary: Create a label for a specific order using a brand ID.
description: Create a single shipping label using a specific brand.
value:
integration_id: 70
brand_id: 42
label_details:
mime_type: application/pdf
dpi: 72
order:
order_number: ORDER-25763
responses:
'201':
description: Parcel ID along with generated label.
content:
application/json:
schema:
type: object
properties:
data:
type: object
description: Parcel ID, tracking details and generated label.
$ref: '#/components/schemas/label-sync'
examples:
LabelSuccessfulWithShipWith:
description: >-
All requested labels are being generated with the provided
`ship_with`.
value:
data:
- parcel_id: 420
shipment_id: '511'
order_id: 593c853e-ca90-4ab4-953c-fd2f47dd8dc3
order_number: ORD-2024-00174
ship_with:
type: shipping_option_code
properties:
contract_id: 517
shipping_option_code: postnl:standard
tracking_number: ABCD1234567890
tracking_url: >-
https://test.shipping-portal.com/tracking/?tracking_number=abcd1234567890&country=nl&postal_code=1234AB
label:
file: <base64-encoded-pdf-data>
mime_type: application/pdf
dpi: 72
documents:
- type: label
size: a6
link: >-
https://panel.sendcloud.sc/api/v3/parcels/1234567890/documents/label
- parcel_id: 4428
shipment_id: '512'
order_id: '23458265234'
order_number: ORD-2024-00166
ship_with:
type: shipping_option_code
properties:
contract_id: 517
shipping_option_code: postnl:standard
tracking_number: ABCD1234567890
tracking_url: >-
https://test.shipping-portal.com/tracking/?tracking_number=abcd1234567890&country=nl&postal_code=1234AB
label:
file: <base64-encoded-pdf-data>
mime_type: application/pdf
dpi: 72
documents:
- type: label
size: a6
link: >-
https://panel.sendcloud.sc/api/v3/parcels/1234567890/documents/label
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
components:
responses:
NotFound:
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
examples:
PageNotFound:
summary: The page you have requested could not be found.
value:
errors:
- status: '404'
code: not_found
title: Not found
detail: The page you have requested could not be found.
BadRequest:
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
examples:
InvalidOrderId:
summary: The provided order_id is not a valid string.
value:
errors:
- status: '400'
code: invalid
title: Invalid
detail: Input should be a valid string.
source:
pointer: /data/attributes/order/order_id
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.
parameters:
SendcloudPartnerId:
in: header
name: Sendcloud-Partner-Id
description: >-
If you are an official [Sendcloud Tech
Partner](https://www.sendcloud.com/ecosystem/), send your unique
Sendcloud Partner UUID as a request header for the system to recognize
you.
The header is not required but if it is set, the system will check it.
An unknown or invalid UUID will cause a 400 error.
schema:
type: string
schemas:
shipping-option-code-properties:
title: Shipping option properties Object
description: >-
Contains the required properties to be sent when API client informs the
shipping method and carrier to be used
type: object
properties:
shipping_option_code:
type:
- string
- 'null'
description: >-
The shipping option that will be or is used for shipping your
parcel. The code can be retrieved via the [Create a list of shipping
options](/api/v3/shipping-options/create-a-list-of-shipping-options)
endpoint. When `ship_with.type` is set to `shipping_option_code`,
this field is mandatory.
example: postnl:standard/insured=3000
contract_id:
type:
- integer
- 'null'
minimum: 1
description: >-
The selected shipping contract. If you haven't specified a contract
for shipping your parcel, we will automatically select the default
contract for the carrier that matches your shipping option. You can
retrieve your contract IDs from the [Retrieve a list of
contracts](/api/v3/contracts/retrieve-a-list-of-contracts) endpoint.
Otherwise, the default direct contract will be automatically
selected.
ship-with:
title: Ship with object
type: object
description: >
The ship with object can be used to define how you would like to send
your shipment.
You can use a `shipping_option_code`. This is a unique identifier that
displays what carrier and what set of shipping functionalities you want
to use.
examples:
- type: shipping_option_code
properties:
shipping_option_code: postnl:standard/insured=3000
contract_id: 517
properties:
type:
type: string
description: >
The way the shipping method and carrier will be selected. Nowadays
the only possible value is 'shipping_option_code', which requires
client to also send the `shipping_option_code` inside properties.
enum:
- shipping_option_code
example: shipping_option_code
properties:
$ref: '#/components/schemas/shipping-option-code-properties'
required:
- type
- properties
create-labels-base:
type: object
required:
- integration_id
properties:
integration_id:
type: integer
description: The ID of the integration your orders belong to.
example: 70
sender_address_id:
type: integer
example: 192
description: >-
The ID of the sender address you would like to ship from. If not
specified, your default sender address will be used.
A sender address can be added through the [Sendcloud
platform](https://app.sendcloud.com/v2/settings/addresses/sender)
and be retrieved using the [Retrieve a list of sender
addresses](/api/v3/sender-addresses/retrieve-a-list-of-sender-addresses)
endpoint.
brand_id:
type: integer
example: 42
description: >-
The ID of the brand. Brands can be added through the [Sendcloud
platform](https://app.sendcloud.com/v2/settings/brands/list) and be
retrieved using the [Retrieve a list of
brands](/api/v2/brands/retrieve-a-list-of-brands) endpoint.
> **Note:** The Brands API is currently only available in API v2.
This reference will be updated when a v3 version becomes available.
minimum: 1
ship_with:
type: object
$ref: '#/components/schemas/ship-with'
components:
schemas:
OrderSelectorOrderIdRequired:
type: object
properties:
order_id:
type: string
minLength: 1
maxLength: 64
description: >-
An external order ID assigned by the shop system. Used to
identify an order to be shipped.
order_number:
type: string
minLength: 1
maxLength: 255
description: >-
An identification of an order in a shop system (often unique).
Used to identify an order to be shipped.
apply_shipping_rules:
type: boolean
description: Apply shipping rules for this order.
default: false
example: false
required:
- order_id
OrderSelectorOrderNumberRequired:
type: object
properties:
order_id:
type: string
minLength: 1
maxLength: 64
description: >-
External order ID assigned by shop system. Used to identify an
order to be shipped.
order_number:
type: string
minLength: 1
maxLength: 255
description: >-
An identification of an order in a shop system (often unique).
Used to identify an order to be shipped.
apply_shipping_rules:
type: boolean
description: Apply shipping rules to this order.
default: false
example: false
required:
- order_number
dimension-units:
type: string
title: Dimensional units
enum:
- cm
- mm
- m
- yd
- ft
- in
example: mm
str-dimensions:
title: Dimensions
type: object
description: Dimensions in the specified unit
properties:
length:
type: string
description: length in specified unit
example: '15'
width:
type: string
description: width in specified unit
example: '20.5'
height:
type: string
description: height in specified unit
example: '37'
unit:
$ref: '#/components/schemas/dimension-units'
required:
- length
- width
- height
- unit
weight-units:
type: string
title: Mass Units Object
enum:
- kg
- g
- lbs
- oz
example: g
str-weight:
title: Weight
type: object
description: Weight in the specified unit
properties:
value:
type: string
description: Weight value
example: '14.5'
unit:
$ref: '#/components/schemas/weight-units'
required:
- value
- unit
parcel-common-with-optional-fields:
title: Parcel common with optional fields Object
description: Parcel common with optional fields model
type: object
properties:
dimensions:
$ref: '#/components/schemas/str-dimensions'
description: >-
While dimensions are generally optional, some carriers require them
to be present. If this is the case, an error will be thrown.
weight:
$ref: '#/components/schemas/str-weight'
OrderItem:
type: object
properties:
item_id:
type: string
description: >-
The order item's external ID in the shop system. This `item_id` can
be obtained via the [Retrieve an
order](/api/v3/orders/retrieve-an-order) endpoint.
example: '5552'
minLength: 1
quantity:
type: integer
description: Quantity of items shipped.
minimum: 1
example: 1
required:
- item_id
- quantity
CreateLabelParcel:
type: object
allOf:
- $ref: '#/components/schemas/parcel-common-with-optional-fields'
- type: object
properties:
parcel_items:
type: array
description: List of items/products from the order that the parcel contains.
maxItems: 1000
items:
$ref: '#/components/schemas/OrderItem'
required:
- parcel_items
create-labels-parcels:
title: Multicollo parcels array Object
description: >-
Multicollo parcels array model used for splitting shipped object into
multiple parcels
type: object
properties:
parcels:
description: >-
Represents each package in the shipment. Each carrier can have its
own limit for the number of parcels per shipment, otherwise there is
a default maximum of 50 parcels. If left empty, one parcel will be
created from an entire order.
type: array
items:
$ref: '#/components/schemas/CreateLabelParcel'
minItems: 1
maxItems: 50
components:
schemas:
OrderItem:
type: object
properties:
item_id:
type: string
description: >-
The order item's external ID in the shop system. This
`item_id` can be obtained via the [Retrieve an
order](/api/v3/orders/retrieve-an-order) endpoint.
example: '5552'
minLength: 1
quantity:
type: integer
description: Quantity of items shipped.
minimum: 1
example: 1
required:
- item_id
- quantity
CreateLabelParcel:
type: object
allOf:
- $ref: '#/components/schemas/parcel-common-with-optional-fields'
- type: object
properties:
parcel_items:
type: array
description: >-
List of items/products from the order that the parcel
contains.
maxItems: 1000
items:
$ref: '#/components/schemas/OrderItem'
required:
- parcel_items
OrderSelectorOrderIdRequired:
type: object
properties:
order_id:
type: string
minLength: 1
maxLength: 64
description: >-
An external order ID assigned by the shop system. Used to identify
an order to be shipped.
order_number:
type: string
minLength: 1
maxLength: 255
description: >-
An identification of an order in a shop system (often unique). Used
to identify an order to be shipped.
apply_shipping_rules:
type: boolean
description: Apply shipping rules for this order.
default: false
example: false
required:
- order_id
OrderSelectorOrderNumberRequired:
type: object
properties:
order_id:
type: string
minLength: 1
maxLength: 64
description: >-
External order ID assigned by shop system. Used to identify an order
to be shipped.
order_number:
type: string
minLength: 1
maxLength: 255
description: >-
An identification of an order in a shop system (often unique). Used
to identify an order to be shipped.
apply_ship
# --- truncated at 32 KB (43 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sendcloud/refs/heads/main/openapi/sendcloud-v3-ship-an-order-openapi.yml