Sendcloud Integrations API v2
Legacy v2 Integrations surface managing connectors to commerce platforms.
OpenAPI Specification
openapi: 3.1.0
info:
title: Integrations
contact:
name: Sendcloud API Support
email: [email protected]
url: https://www.sendcloud.dev
version: 2.0.0
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
description: >-
The Integrations API allows you to retrieve, update and add orders to custom
webshop integrations.
servers:
- url: https://panel.sendcloud.sc/api/v2
description: Sendcloud Production
tags:
- name: Integrations
- name: Shipments
paths:
/integrations:
get:
summary: Retrieve a list of integrations
operationId: sc-public-v2-orders-get-retrieve_a_list_of_integrations
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
x-mint:
href: /api/v2/integrations/retrieve-a-list-of-integrations
content: >-
<Warning>
**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).
</Warning>
The information returned includes the shop name and URL, the date, and
the time of the last order fetch. The response indicates whether
service point delivery is enabled for this integration, and for which
carriers.
description: >-
Retrieve information about all the shop integrations currently connected
to your Sendcloud account.
parameters:
- schema:
type: string
in: query
name: ordering
description: Specifies the field used to order the resulting response
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Integration'
examples:
RetrieveIntegrationList:
summary: Retrieve a list of integrations
value:
- id: 123
shop_name: 'Integration #1'
shop_url: https://example.com
system: api / amazon / magento
failing_since: '2019-08-24T14:15:22Z'
last_fetch: '2019-08-24T14:15:22Z'
last_updated_at: '2019-08-24T14:15:22Z'
service_point_enabled: true
service_point_carriers:
- ups
webhook_active: true
webhook_url: https://example.com
tags:
- Integrations
/integrations/{id}:
get:
summary: Retrieve an integration
operationId: sc-public-v2-orders-get-retrieve_an_integration
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
x-mint:
href: /api/v2/integrations/retrieve-an-integration
content: >-
<Warning>
**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).
</Warning>
The information returned includes the shop name and URL, the date and
the time of the last order fetch. The response will also indicate
whether service point delivery is enabled for this integration, and
for which carriers.
description: Retrieve information about a specific integration using its `id`.
tags:
- Integrations
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Integration'
examples:
RetrieveIntegration:
summary: Retrieve an integration
value:
id: 123
shop_name: 'Integration #1'
shop_url: https://example.com
system: api / amazon / magento
failing_since: '2019-08-24T14:15:22Z'
last_fetch: '2019-08-24T14:15:22Z'
last_updated_at: '2019-08-24T14:15:22Z'
service_point_enabled: true
service_point_carriers:
- ups
webhook_active: true
webhook_url: https://example.com
'404':
$ref: '#/components/responses/404-Integrations'
put:
summary: Update an integration
operationId: sc-public-v2-orders-put-update_an_integration
x-mint:
href: /api/v2/integrations/update-an-integration
content: >-
<Warning>
**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).
</Warning>
Using this endpoint, you can change the webshop name and URL, edit the
list of carriers you want to enable for service point delivery and
enable or disable service point delivery by setting
`service_point_enabled` to `true` or `false`.
Unlike the [Partially update an
integration](/api/v2/integrations/partially-update-an-integration)
endpoint, you must send all fields, even those you don't want to
change.
You can obtain an integration `id` via the [Retrieve a list of
integrations](/api/v2/integrations/retrieve-a-list-of-integrations)
endpoint.
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
description: Update settings for a specific integration using its `id`.
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/IntegrationUpdate'
examples:
UpdateIntegration:
summary: Update an integration
value:
shop_name: 'Integration #1'
shop_url: https://example.com
last_updated_at: '2019-08-24T14:15:22Z'
service_point_enabled: true
service_point_carriers:
- ups
webhook_active: true
webhook_url: https://example.com
description: OK
'400':
$ref: '#/components/responses/400-Integration'
'404':
$ref: '#/components/responses/404-Integrations'
tags:
- Integrations
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/IntegrationUpdate'
examples:
UpdateIntegration:
summary: Update an Integration
value:
shop_name: 'Integration #1'
shop_url: https://example.com
service_point_enabled: true
service_point_carriers:
- ups
webhook_active: true
webhook_url: https://example.com
description: ''
patch:
operationId: sc-public-v2-orders-patch-partial_update_an_integration
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
x-mint:
href: /api/v2/integrations/partially-update-an-integration
content: >-
<Warning>
**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).
</Warning>
Using this endpoint, you can change the webshop name and URL, edit the
list of carriers you want to enable for service point delivery and
enable or disable service point delivery by setting
`service_point_enabled` to `true` or `false`.
Unlike the [Update an
integration](/api/v2/integrations/update-an-integration) endpoint, you
can send only the fields you want to update.
You can obtain an integration `id` via the [Retrieve a list of
integrations](/api/v2/integrations/retrieve-a-list-of-integrations)
endpoint.
description: Partially update settings for a specific integration using its `id`.
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/IntegrationUpdate'
examples:
UpdateIntegration:
summary: Update an Integration
value:
shop_name: 'Integration #1'
shop_url: https://example.com
last_updated_at: '2019-08-24T14:15:22Z'
service_point_enabled: true
service_point_carriers:
- ups
webhook_active: true
webhook_url: https://example.com
partial_update:
summary: Partial update of an Integration
value:
service_point_enabled: true
service_point_carriers:
- ups
description: OK
'400':
$ref: '#/components/responses/400-Integration'
'404':
$ref: '#/components/responses/404-Integrations'
tags:
- Integrations
summary: Partially update an integration
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/IntegrationUpdate'
examples:
UpdateIntegration:
summary: Update an integration
value:
shop_name: 'Integration #1'
shop_url: https://example.com
last_updated_at: '2019-08-24T14:15:22Z'
service_point_enabled: true
service_point_carriers:
- ups
webhook_active: true
webhook_url: https://example.com
partial_update:
summary: Partial update of an Integration
value:
service_point_enabled: true
service_point_carriers:
- ups
delete:
summary: Delete an integration
operationId: sc-public-v2-orders-delete-delete_an_integration
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
x-mint:
href: /api/v2/integrations/delete-an-integration
content: |-
<Warning>
**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).
</Warning>
description: Delete a shop integration from the Sendcloud system.
responses:
'204':
description: No Content
'404':
$ref: '#/components/responses/404-Integrations'
tags:
- Integrations
parameters:
- schema:
type: integer
name: id
in: path
required: true
description: The id of the integration
/integrations/{id}/shipments:
get:
operationId: sc-public-v2-orders-get-retrieve_a_list_of_shipments
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
x-mint:
href: /api/v2/integrations/retrieve-a-list-of-shipments
content: >-
<Warning>
**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).
</Warning>
Note that the orders **are not** affected by [shipping
rules](https://support.sendcloud.com/hc/en-us/articles/360025143571-Automate-your-workflow-using-Sendcloud-Shipping-Rules)
at the time of retrieval, unless enabled explicitly.
This endpoint is paginated, meaning that you can navigate through the
`results` via the URLs provided within the `next` and `previous`
fields.
x-sendcloud-paginated: true
x-sendcloud-paginated-discriminator: results
description: >-
Retrieve a list of orders that were imported from a specific webshop
integration.
parameters:
- $ref: '#/components/parameters/cursor-parameter'
- name: start_date
in: query
required: false
description: >-
Displays orders from the given `start_date`, including the set date.
It defaults to one year ago.
schema:
type: string
format: date
- name: end_date
in: query
required: false
description: >-
Displays orders up to the given `end_date`, including the set date.
It defaults to the current date.
schema:
type: string
format: date
- name: external_order_ids
in: query
required: false
description: >-
Filters results to shipments where their `external_order_id` matches
one of the user provided ones.
schema:
type: array
items:
type: string
- name: external_shipment_ids
in: query
required: false
description: >-
Filters results to shipments where their `external_shipments_id`
matches one of the user provided ones.
schema:
type: array
items:
type: string
- name: shipping_rules
in: query
required: false
description: >-
Enable shipping rules when retrieving orders. This will have an
impact on the `allowed_shipping_methods`.
schema:
type: boolean
- name: order_number
in: query
required: false
description: Filters results to shipments on `order_number`.
schema:
type: string
- name: sender_address
in: query
required: false
description: >-
Allows to specify a sender address id to display proper
`allowed_shipping_methods`.
schema:
type: integer
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
next:
type: string
format: uri
description: >-
Cursor based pagination url to go forward. By following
this URL you can get a next batch of shipments
previous:
type: string
format: uri
description: >-
Cursor based pagination url to go backwards. By following
this URL you can get a previous batch of shipments
results:
type: array
items:
$ref: '#/components/schemas/ShipmentBlobOrder'
examples:
RetrieveShipmentList:
summary: Retrieve a list of shipments
value:
next: https://example.com
previous: https://example.com
results:
- address: Lansdown Glade
address_2: string
allowed_shipping_methods:
- 0
barcode: string
city: Oss
company_name: string
country: AW
created_at: '2019-08-24T14:15:22Z'
currency: EUR
customs_invoice_nr: '120'
customs_shipment_type: 0
email: [email protected]
external_order_id: '555413'
external_shipment_id: '777413'
house_number: '15'
integration: 0
name: John Doe
order_number: OXSDFGHTD-12
order_status:
id: fulfilled
message: Fulfilled
parcel_items:
- description: Very orange color
hs_code: '01013000'
origin_country: AW
product_id: '1458734634'
properties:
size: small
colour: red
quantity: 2
sku: WW-DR-GR-XS-001
value: '3.5'
weight: '1'
mid_code: NLOZR92MEL
material_content: 100% Cotton
intended_use: Personal use
payment_status:
id: paid
message: Paid
postal_code: '5341'
sender_address: 12345
shipment_uuid: 6b436cb2-65a4-482c-9d25-38be7868ff00
shipping_method: 12345
shipping_method_checkout_name: string
telephone: string
to_post_number: string
to_service_point: 0
to_state: string
total_order_value: string
updated_at: '2019-08-24T14:15:22Z'
weight: string
checkout_payload:
sender_address_id: 0
shipping_product:
code: postnl:standard
name: PostNL Standard
selected_functionalities:
age_check: 18
last_mile: home_delivery
first_mile: pickup_dropoff
multicollo: true
form_factor: parcel
service_area: domestic
weekend_delivery: saturday
delivery_deadline: best_effort
direct_contract_only: false
delivery_method_type: string
delivery_method_data:
delivery_date: '2019-08-24T14:15:22Z'
formatted_delivery_date: string
parcel_handover_date: '2019-08-24T14:15:22Z'
width: string
height: string
length: string
customs_details:
discount_granted: '3.99'
insurance_costs: '9.99'
freight_costs: '5.99'
other_costs: '2.99'
tax_numbers:
sender:
- tax_number:
name: VAT
country: NL
value: NL987654321B02
receiver:
- tax_number:
name: VAT
country: DE
value: DE123456789B03
importer_of_records:
- tax_number:
name: VAT
country: NL
value: NL975318642B01
shipment_created_at: '2019-09-25T14:15:22Z'
shipment_updated_at: '2019-09-25T14:15:22Z'
'404':
$ref: '#/components/responses/404-Shipments'
summary: Retrieve a list of shipments
tags:
- Shipments
post:
operationId: sc-public-v2-orders-post-create_a_list_of_shipments
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
x-mint:
href: /api/v2/integrations/create-a-list-of-shipments
content: >-
<Warning>
**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).
</Warning>
<Info>
This endpoint is only available for official Sendcloud partners.
</Info>
This endpoint allows you to insert shipments (or 'orders') into an API
integration from your shop system, and have them appear in your
Sendcloud account. Imported orders will appear in the Sendcloud
platform under the **Incoming order overview** with the status "Ready
to process". This allows you to easily generate parcels and create
shipping labels via the API or directly from the Sendcloud platform.
The validation for this endpoint is more relaxed, therefore we
recommend this method over the [Create a parcel or
parcels](/api/v2/parcels/create-a-parcel-or-parcels) endpoint for
third-party integrators.
This is an **UPSERT** endpoint which attempts to be idempotent given
specific fields to ensure that orders are not duplicated. If there's
an existing match in our database for specific fields
(`external_order_id` and `external_shipment_id`), then the shipment
will be updated. The system will only update orders that have had
their `updated_at` (ISO 8601 DateTime) timestamp changed.
The `external_shipment_id` field is used to split orders across
multiple shipments, however, this field is not supported by all shop
systems. If your shop system supports the distribution of product
items within an order across multiple shipments, you can use the
shipment data to create multiple entries. If your shop does not
support this feature, you can set the `external_shipment_id` value to
`null`.
Batches are limited to 100 orders at once. This endpoint should accept
most values in any of the available fields, but in the case of
erroneous data, an error message will be returned directly. Your
requests should almost always succeed unless the field structure is
not correct.
description: >-
Insert shipments (or 'orders') into an API integration from your shop
system, and have them appear in your Sendcloud account.
responses:
'200':
description: >-
List with references to created shipments, or the errors that
occurred while creating the shipment.
When a shipment can't be created, the response will contain an entry
for the object with the errors.
This object will have a path to each field containing errors,
listing the error(s) it contains.
content:
application/json:
schema:
type: array
items:
oneOf:
- $ref: '#/components/schemas/ShipmentCreateUpdateLog'
- $ref: '#/components/schemas/ShipmentErrorLog'
examples:
CreateUpdateShipments:
summary: Create or update a list of shipments
value:
- external_order_id: '1175584'
external_shipment_id: '777413'
shipment_uuid: 6b436cb2-65a4-482c-9d25-38be7868ff00
status: created
- error:
checkout_payload:
delivery_method_data:
delivery_date:
- This field is required.
external_order_id: '1184635'
external_shipment_id: ''
status: error
'400':
description: Bad Request
'404':
$ref: '#/components/responses/404-Shipments'
summary: Create or update a list of shipments
tags:
- Shipments
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ShipmentBlobOrderCreate'
examples:
CreateUpdateShipments:
summary: Create or update a list of shipments
value:
- address: Lansdown Glade
address_2: string
city: Oss
company_name: string
country: AW
created_at: '2019-08-24T14:15:22Z'
currency: EUR
customs_invoice_nr: '120'
customs_shipment_type: 0
email: [email protected]
external_order_id: '555413'
external_shipment_id: '777413'
house_number: '15'
name: John Doe
order_number: OXSDFGHTD-12
order_status:
id: fulfilled
message: Fulfilled
parcel_items:
- description: Very orange color
hs_code: '01013000'
origin_country: AW
product_id: '1458734634'
properties:
size: small
colour: red
quantity: 2
sku: WW-DR-GR-XS-001
value: '3.5'
weight: '1'
mid_code: NLOZR92MEL
material_content: 100% Cotton
intended_use: Personal use
payment_status:
id: paid
message: Paid
postal_code: '5341'
shipping_method: 12345
shipping_method_checkout_name: string
telephone: string
to_post_number: string
to_service_point: 0
to_state: string
total_order_value: string
updated_at: '2019-08-24T14:15:22Z'
weight: string
checkout_payload:
sender_address_id: 0
shipping_product:
code: postnl:standard
name: PostNL Standard
selected_functionalities:
age_check: 18
last_mile: home_delivery
first_mile: pickup_dropoff
multicollo: true
form_factor: parcel
service_area: domestic
weekend_delivery: saturday
delivery_deadline: best_effort
direct_contract_only: false
delivery_method_type: string
delivery_method_data:
delivery_date: '2019-08-24T14:15:22Z'
formatted_delivery_date: string
parcel_handover_date: '2019-08-24T14:15:22Z'
width: string
height: string
length: string
customs_details:
discount_granted: '3.99'
insurance_costs: '9.99'
freight_costs: '5.99'
other_costs: '2.99'
tax_numbers:
sender:
- tax_number:
name: VAT
country: NL
value: NL987654321B02
receiver:
- tax_number:
name: VAT
country: DE
value: DE123456789B03
importer_of_records:
- tax_number:
name: VAT
country: NL
value: NL975318642B01
description: ''
parameters:
- name: id
in: path
required: true
schema:
type: integer
description: The id of the integration to which the shipments belong
/integrations/{id}/shipments/delete:
post:
tags:
- Shipments
summary: Delete a shipment
operationId: sc-public-v2-orders-post-delete_a_shipment
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
x-mint:
href: /api/v2/integrations/delete-a-shipment
content: >-
<Warning>
**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).
</Warning>
The `order_status` and `payment_status` fields we retrieve from
integrations are not mapped in our system, meaning that orders will
not be automatically updated or deleted if the values for these fields
change after an order is placed.
You can delete an order by providing either a `shipment_uuid`, or a
combination of the `external_order_id` and `external_shipment_id`
properties.
description: >-
Allows you to delete a shipment from Sendcloud, e.g. if it has been
canceled or deleted in your shop system.
requestBody:
description: >-
You must provide either a shipment_uuid or the combination of
external_order_id and external_shipment_id to this endpoint.
content:
application/json:
schema:
oneOf:
- type: object
properties:
shipment_uuid:
type: string
format: uuid
# --- truncated at 32 KB (92 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sendcloud/refs/heads/main/openapi/sendcloud-v2-integrations-openapi.yml