> ## Documentation Index
> Fetch the complete documentation index at: https://sendcloud.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Request a label for a single order synchronously
> 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.
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.
## OpenAPI
````yaml /.openapi/v3/ship-an-order/openapi.yaml post /orders/create-label-sync
openapi: 3.1.0
info:
title: Ship an Order
version: 3.0.0
contact:
name: Sendcloud API Support
email: contact@sendcloud.com
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
security: []
tags:
- name: Ship an Order
description: OrderLabelAPI
paths:
/orders/create-label-sync:
post:
tags:
- Ship an Order
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.
operationId: sc-public-v3-orders_labels-post-create_labels_sync
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:
$ref: '#/components/schemas/label-sync'
type: object
description: Parcel ID, tracking details and generated label.
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:
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:
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'
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
components:
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:
create-labels-sync:
title: Create labels synchronously
description: >
Payload for creating labels for orders.
Note that if the `sender_address_id` is not specified, the API will use
the default [sender address](/docs/getting-started/sender-addresses)
associated with your account.
type: object
allOf:
- $ref: '#/components/schemas/create-labels-base'
- type: object
required:
- order
- integration_id
properties:
order:
type: object
oneOf:
- $ref: '#/components/schemas/OrderSelectorOrderIdRequired'
- $ref: '#/components/schemas/OrderSelectorOrderNumberRequired'
label_details:
type: object
properties:
mime_type:
type: string
default: application/pdf
enum:
- application/pdf
- application/zpl
- image/png
example: application/zpl
description: The returned format of the label.
dpi:
type: integer
default: 72
enum:
- 72
- 150
- 203
- 300
- 600
example: 72
description: >-
DPI refers to the printing resolution of your shipping
labels. It's important that labels are printed at a high
enough resolution to ensure the clarity of address details
and the barcode for scanning purposes.
Refer to the following table for DPI settings per file
format:
File format | Default DPI | Valid DPI
----------- | ----------- | ---------
pdf | 72 | 72
png | 300 | 150, 300
ZPL labels are not affected by the DPI setting, as the
resolution is determined by the carrier itself. Most
carriers use a resolution of 203 DPI. Zebra printers need to
be configured to print at the specific DPI of the label if
they have higher resolution capabilities.
label-sync:
title: Reference to label
type: object
description: Holds the reference to created label.
allOf:
- $ref: '#/components/schemas/label-base'
- type: object
properties:
parcel_id:
type: integer
description: The ID of the parcel the label belongs to.
example: 420
label_details:
type: object
properties:
file:
type: string
format: byte
description: The base64 representation of the label file.
mime_type:
type: string
default: application/pdf
enum:
- application/pdf
- application/zpl
- image/png
example: application/zpl
description: The returned format of the label.
dpi:
type: integer
default: 72
enum:
- 72
- 150
- 203
- 300
- 600
example: 72
description: >-
DPI refers to the printing resolution of your shipping
labels. It's important that labels are printed at a high
enough resolution to ensure the clarity of address details
and the barcode for scanning purposes.
Refer to the following table for DPI settings per file
format:
File format | Default DPI | Valid DPI
----------- | ----------- | ---------
pdf | 72 | 72
png | 300 | 150, 300
ZPL labels are not affected by the DPI setting, as the
resolution is determined by the carrier itself. Most
carriers use a resolution of 203 DPI. Zebra printers need to
be configured to print at the specific DPI of the label if
they have higher resolution capabilities.
documents:
type: array
uniqueItems: true
description: >-
An array of documents. A parcel can contain multiple documents,
for instance labels and a customs form. This field returns an
array of all the available documents for this parcel.
readOnly: true
items:
$ref: '#/components/schemas/documents'
tracking_number:
type: string
description: Tracking number of the shipment.
readOnly: true
tracking_url:
type: string
description: Tracking url of this shipment.
readOnly: true
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:
$ref: '#/components/schemas/ship-with'
type: object
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
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
label-base:
type: object
properties:
shipment_id:
type: string
description: The ID of the shipment that was created for the provided order.
example: '511'
order_id:
type: string
description: The ID of your order.
example: 593c853e-ca90-4ab4-953c-fd2f47dd8dc3
order_number:
type: string
description: A human-readable order number.
example: ORD-2024-01414
ship_with:
$ref: '#/components/schemas/ship-with'
type: object
documents:
title: Documents Object
type: object
description: Documents object for a parcel
properties:
type:
type: string
deprecated: true
description: The type of the document. See the list below for available types.
enum:
- label
- cn23
- cp71
- commercial-invoice
- cn23-default
- air-waybill
- qr
document_type:
type: string
description: The type of the document. See the list below for available types.
enum:
- label
- customs-declaration
- air-waybill
size:
type: string
description: The paper size of the document.
enum:
- a6
- a4
link:
type: string
description: >-
A link to the document, which allows downloading of the document in
PDF, PNG and ZPL and various DPI.
errors:
title: Errors
type: object
description: A standardized format for errors in JSON:API responses.
properties:
errors:
type:
- array
- object
items:
type: object
allOf:
- $ref: '#/components/schemas/ErrorObject'
required:
- status
- code
- detail
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
ErrorObject:
title: Error
type: object
description: Error in a JSON:API error format
properties:
id:
type: string
description: A unique identifier for the error.
links:
type: object
description: >-
A set of hyperlinks that provide additional information about the
error.
properties:
about:
type: string
description: A URL that provides additional information about the error.
status:
type: string
format: int32
description: The HTTP status code of the error.
minLength: 1
code:
type: string
description: A unique error code for the error, in snake case format.
minLength: 1
enum:
- unknown_field
- invalid
- forbidden
- invalid_choice
- min_value
- 'null'
- not_found
- required
- not_a_list
- non_field_errors
- authentication_failed
- validation_error
- parcel_announcement_error
title:
type: string
description: A short, human-readable summary of the error.
minLength: 1
detail:
type: string
description: A human-readable explanation of the error.
minLength: 1
source:
type: object
description: >-
An object that identifies the source of the error within the request
payload.
properties:
pointer:
type: string
description: >-
A `JSON` pointer to the location of the error within the request
payload.
parameter:
type: string
description: The name of the `query` parameter that caused the error.
header:
type: string
description: The name of the `header` parameter that caused the error.
meta:
type: object
description: Additional metadata about the error.
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.
responses:
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
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.
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.
````