Sendcloud Integrations API v3
Manage connectors between Sendcloud and external commerce / WMS / marketplace platforms (Shopify, WooCommerce, Magento, Amazon, Etsy, etc.).
OpenAPI Specification
openapi: 3.1.0
info:
title: Integrations
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 Integrations API lets you manage some aspects of your integrations, and
set and retrieve available shop order statuses.
servers:
- url: https://panel.sendcloud.sc/api/v3
description: Sendcloud Production
tags:
- name: Integrations
description: IntegrationsAPI
- name: Exception logs
description: Integration exception logs API
paths:
/integrations/{id}:
parameters:
- schema:
type: integer
minimum: 1
name: id
in: path
required: true
description: Filtering on the Sendcloud integration ID
delete:
summary: Delete an integration
description: Safely delete one of your integrations from the Sendcloud system
x-mint:
href: /api/v3/integrations/delete-an-integration
responses:
'204':
description: No content
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
examples:
OrderDoesNotExist:
summary: Integration does not exist
value:
errors:
- status: 404
code: not_found
title: Not Found
detail: >-
The Integration could not be found with the search
criteria given
operationId: sc-public-v3-integrations-delete-delete_integration
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
tags:
- Integrations
patch:
summary: Update certain parts of an integration
description: >-
Update the shop name, shop URL, service point settings, webhook
settings, and feedback type of an integration.
x-mint:
href: /api/v3/integrations/update-certain-parts-of-an-integration
content: >-
You can update certain parts of an integration with this endpoint:
- Update the shop name of an integration
- Update the shop URL of an integration
- Enable service points and select the appropriate service point
carriers
- Enable webhooks and set the webhook URL
- Change the type of feedback you would like the integration to follow
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/integration-model'
examples:
UpdatingShopName:
summary: Update the shop name on your integration
description: Update the shop name on your integration.
value:
shop_name: My Webshop
EnableServicePointsIntegration:
summary: Update an integration to enable service points.
description: Update an integration to enable service points.
value:
service_point_enabled: true
service_point_carriers:
- ups
- dhl
EnableWebhooksForAnIntegration:
summary: Update an integration to enable webhook feedback.
description: >
Update an integration to enable Sendcloud to call your webhook
to provide parcel status feedback.
value:
webhook_active: true
webhook_url: https://mywebshop.com/feedback
UpdateFeedbackType:
summary: Update type of feedback an integration will use.
description: |
Update type of feedback an integration will use.
value:
feedback_type: none
responses:
'204':
description: No content
'400':
description: Webhook URL required when enable webhook is set to `true`.
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
examples:
WebhookDoesNotExist:
summary: Webhook url missing
value:
errors:
- status: '400'
code: invalid
title: Invalid
detail: >-
Webhook URL required when enable webhook is set to
true
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
examples:
IntegrationDoesNotExist:
summary: Integration does not exist
value:
errors:
- status: 404
code: not_found
title: Not Found
detail: >-
The Integration could not be found with the search
criteria given
operationId: sc-public-v3-integrations-patch-update_integration
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
tags:
- Integrations
get:
summary: Retrieve an integration
description: Get a valid integration from the Sendcloud system
x-mint:
href: /api/v3/integrations/retrieve-an-integration
responses:
'200':
description: Retrieved integration corresponding to the provided integration_id
content:
application/json:
schema:
title: Integration Get Response
type: object
description: >-
Integration object as represented in the response of the get
request.
properties:
data:
type: object
$ref: '#/components/schemas/integration-response-model'
examples:
Response:
value:
data:
id: 23452345
shop_name: 'Integration #1'
shop_url: https://www.my-shop-integration.com/
type: api
started_failing_at: '2023-11-10T16:16:42Z'
last_fetched_at: '2023-11-10T16:15:09Z'
created_at: '2023-11-04T14:15:22Z'
updated_at: '2023-11-08T12:23:56Z'
service_point_enabled: true
service_point_carriers:
- ups
- dhl
webhook_active: true
webhook_url: >-
https://my-shop-integration.integrator/api/webhooks/sendcloud
feedback_type: eager
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
examples:
OrderDoesNotExist:
summary: Integration does not exist
value:
errors:
- status: 404
code: not_found
title: Not Found
detail: >-
The Integration could not be found with the search
criteria given
operationId: sc-public-v3-integrations-get-retrieve_integration
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
tags:
- Integrations
/integrations:
get:
summary: Retrieve a list of integrations
description: >-
Retrieve all valid integrations from the Sendcloud system for a given
user.
x-mint:
href: /api/v3/integrations/retrieve-a-list-of-integrations
parameters:
- in: query
name: sort
schema:
type: string
description: >
Set the order for the response items:
- Sorting is supported by the `integration_type`, `created_at`,
`updated_at`, `last_fetch`, and `failing_since` attributes in the
response object.
- To sort the response in descending order, add the prefix `-` to
the query param value.
- By default, the items will be ordered by `last_fetch` and then
`created_at`.
example: updated_at
responses:
'200':
description: All valid integrations from the Sendcloud System for a given user.
content:
application/json:
schema:
title: Integration List Response
type: object
description: >-
Integration object as represented in the response of the list
request.
properties:
data:
items:
$ref: '#/components/schemas/integration-response-model'
examples:
Response:
value:
data:
- id: 23452345
shop_name: 'Integration #1'
shop_url: https://www.my-shop-integration.com/
type: api
started_failing_at: '2023-11-10T16:16:42Z'
last_fetched_at: '2023-11-10T16:15:09Z'
created_at: '2023-11-04T14:15:22Z'
updated_at: '2023-11-08T12:23:56Z'
service_point_enabled: true
service_point_carriers:
- ups
- dhl
webhook_active: true
webhook_url: >-
https://my-shop-integration.integrator/api/webhooks/sendcloud
feedback_type: eager
operationId: sc-public-v3-integrations-get-list_integrations
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
tags:
- Integrations
/integrations/logs:
get:
summary: Retrieve all integration exception logs
operationId: sc-public-v3-integrations-get-retrieve_integrations_logs
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
x-mint:
href: /api/v3/integrations/retrieve-all-integration-exception-logs
content: >-
Integration exception logs might be generated, for example:
- if some resource cannot be found
- if API credentials are no longer valid
Each log record may contain information about the request and
response, the status code and code exception, and can be used as a
reference to identify issues between Sendcloud and a webshop.
Pagination is cursor-based. Use the `cursor` query parameter to
navigate through pages. The `Link` response header contains the URL
for the next page when more results are available.
description: >-
Retrieve all integration exception logs. These logs are created when
integrations have problems making API requests to shop systems.
tags:
- Exception logs
parameters:
- in: query
name: cursor
schema:
type: string
format: date-time
description: >-
Cursor for pagination. Use the value from the `Link` response header
to fetch the next page.
example: '2023-03-01T02:02:00+01:00'
- in: query
name: page_size
schema:
type: integer
minimum: 1
maximum: 100
default: 25
description: Number of results per page.
example: 25
responses:
'200':
description: OK
headers:
Link:
schema:
type: string
description: >-
Contains the URL for the next page of results (RFC 5988).
Example:
`<https://panel.sendcloud.sc/api/v3/integrations/logs?cursor=2023-03-01T02:02:00&page_size=25>;
rel="next"`
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/integration-log'
examples:
RetrieveIntegrationLogs:
summary: Retrieve a list of integration logs
value:
data:
- id: 123
base_url: https://example.com
full_url: https://example.com/order-note.json
method: POST
response_code: 495
response:
headers:
Cache-Control: max-age=3600
Content-Type: text/html; charset=utf-8
Connection: keep-alive
body: |
<!doctype html>
<html>
<head>
<title>SSL Certificate Error</title>
</head>
</html>
request:
headers:
Cache-Control: max-age=3600
Content-Type: text/html; charset=utf-8
Connection: keep-alive
payload:
order_note:
note: Success
created_at: '2023-03-01T02:02:00+01:00'
exception_type: requests.exceptions.SSLError
exception: An SSL error occurred
protected: false
additional_data: ''
/integrations/{id}/logs:
parameters:
- schema:
type: integer
name: id
in: path
required: true
description: The id of the integration
get:
summary: Retrieve exception logs for a specific integration
operationId: sc-public-v3-integrations-get-retrieve_integration_logs
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
x-mint:
href: >-
/api/v3/integrations/retrieve-exception-logs-for-a-specific-integration
content: >-
Integration exception logs might be generated, for example:
- if some resource cannot be found
- if API credentials are no longer valid
Each log record may contain information about the request and
response, the status code and code exception, and can be used as a
reference to identify issues between Sendcloud and a webshop.
Pagination is cursor-based. Use the `cursor` query parameter to
navigate through pages. The `Link` response header contains the URL
for the next page when more results are available.
description: >-
Retrieve exception logs for a specific integration. These logs are
created when integrations have problems making API requests to shop
systems.
tags:
- Exception logs
parameters:
- in: query
name: cursor
schema:
type: string
format: date-time
description: >-
Cursor for pagination. Use the value from the `Link` response header
to fetch the next page.
example: '2023-03-01T02:02:00+01:00'
- in: query
name: page_size
schema:
type: integer
minimum: 1
maximum: 100
default: 25
description: Number of results per page.
example: 25
responses:
'200':
description: OK
headers:
Link:
schema:
type: string
description: >-
Contains the URL for the next page of results (RFC 5988).
Example:
`<https://panel.sendcloud.sc/api/v3/integrations/{id}/logs?cursor=2023-03-01T02:02:00&page_size=25>;
rel="next"`
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/integration-log'
examples:
RetrieveIntegrationLogs:
summary: Retrieve a list of integration logs
value:
data:
- id: 123
base_url: https://example.com
full_url: https://example.com/order-note.json
method: POST
response_code: 495
response:
headers:
Cache-Control: max-age=3600
Content-Type: text/html; charset=utf-8
Connection: keep-alive
body: |
<!doctype html>
<html>
<head>
<title>SSL Certificate Error</title>
</head>
</html>
request:
headers:
Cache-Control: max-age=3600
Content-Type: text/html; charset=utf-8
Connection: keep-alive
payload:
order_note:
note: Success
created_at: '2023-03-01T02:02:00+01:00'
exception_type: requests.exceptions.SSLError
exception: An SSL error occurred
protected: false
additional_data: ''
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
examples:
IntegrationDoesNotExist:
summary: Integration does not exist
value:
errors:
- status: 404
code: not_found
title: Not Found
detail: >-
The Integration could not be found with the search
criteria given
post:
summary: Create integration exception logs
operationId: sc-public-v3-integrations-post-create_integration_logs
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
x-mint:
href: /api/v3/integrations/create-integration-exception-logs
description: >-
Create integration exception logs, which will appear in the connection
issue log screen of the user's integration.
tags:
- Exception logs
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/integration-log-create'
examples:
CreateIntegrationLog:
summary: Create an integration log
value:
base_url: https://example.com
full_url: https://example.com/order-note.json
method: POST
response_code: 495
response:
headers:
Cache-Control: max-age=3600
Content-Type: text/html; charset=utf-8
Connection: keep-alive
body: |
<!doctype html>
<html>
<head>
<title>SSL Certificate Error</title>
</head>
</html>
request:
headers:
Cache-Control: max-age=3600
Content-Type: text/html; charset=utf-8
Connection: keep-alive
payload:
order_note:
note: Success
created_at: '2023-03-01T02:02:00+01:00'
exception_type: requests.exceptions.SSLError
exception: An SSL error occurred
responses:
'201':
description: Created
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/integration-log'
examples:
CreateIntegrationLog:
summary: Create an integration log
value:
data:
id: 123
integration_id: 123
base_url: https://example.com
full_url: https://example.com/order-note.json
method: POST
response_code: 495
response:
headers:
Cache-Control: max-age=3600
Content-Type: text/html; charset=utf-8
Connection: keep-alive
body: |
<!doctype html>
<html>
<head>
<title>SSL Certificate Error</title>
</head>
</html>
request:
headers:
Cache-Control: max-age=3600
Content-Type: text/html; charset=utf-8
Connection: keep-alive
payload:
order_note:
note: Success
created_at: '2023-03-01T02:02:00+01:00'
exception_type: requests.exceptions.SSLError
exception: An SSL error occurred
protected: false
additional_data: ''
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
examples:
ExtraFieldsNotPermitted:
summary: Extra fields are not permitted
value:
errors:
- status: 400
code: extra_forbidden
title: Extra Forbidden
detail: Extra inputs are not permitted
source:
pointer: body/unknown_field
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
examples:
IntegrationDoesNotExist:
summary: Integration does not exist
value:
errors:
- status: 404
code: not_found
title: Not Found
detail: >-
The Integration could not be found with the search
criteria given
/shop-order-statuses:
get:
summary: Retrieve shop order statuses for an integration
description: >-
Fetch all available shop order statuses for the Prestashop v2
integration, in the default or selected language.
x-mint:
href: /api/v3/integrations/retrieve-shop-order-statuses-for-an-integration
content: >-
<Warning>
Only the Prestashop V2 integration is supported.
</Warning>
Note that:
- If the user hasn't picked a language, they will receive the status
in the default language, `en-gb`.
- If `en-gb` is not present, the user receives the status in the first
language of the alphabetically ordered list.
parameters:
- $ref: '#/components/parameters/required_integration_id'
- $ref: '#/components/parameters/language'
- $ref: '#/components/parameters/show_deleted'
responses:
'200':
description: >-
All available shop order statuses for a given integration, in
default or selected language.
content:
application/json:
schema:
$ref: '#/components/schemas/get-shop-order-statuses'
examples:
Response:
value:
data:
- external_id: 17-B
status: Delivered
deleted_at: null
translations:
- status: Delivered
language: en-gb
- status: Verzonden
language: nl-nl
- status: Geliefert
language: de-de
- external_id: 14-A
status: Cancelled
deleted_at: '2023-11-04T14:15:22Z'
translations:
- status: Cancelled
language: en-gb
- status: Geannuleerd
language: nl-nl
- status: Abgesagt
language: de-de
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
examples:
InvalidRequest:
value:
errors:
- status: '400'
code: non_field_errors
title: integration ID
detail: Integration ID is a required GET parameter
operationId: sc-public-v3-integrations-get-shop_order_statuses
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
tags:
- Integrations
post:
summary: Create or overwrite shop order statuses
description: Insert shop-specific custom statuses into the Sendcloud system.
x-mint:
href: /api/v3/integrations/create-or-overwrite-shop-order-statuses
content: >-
<Warning>
Only the Prestashop V2 integration is supported.
</Warning>
Note that:
- Integrations can have their own custom shop statuses.
- To get your order updates in time, Sendcloud needs to know what
statuses are available.
- This endpoint updates all existing statuses. That includes creating
new statuses, changing existing ones, and deleting ones that no longer
exist.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/post-shop-order-statuses'
examples:
PostOrderShopStatuses:
summary: Upserting available shop order statuses
description: >-
Setting all available shop order statuses with their available
translations.
value:
integration_id: 23452345
statuses:
- external_id: Send-4
translations:
- status: Sent
language: en-gb
- status: Verzonden
language: nl-nl
- external_id: '15'
translations:
- status: Delivered
language: en-gb
- status: Bezorgt
language: nl-nl
responses:
'200':
description: OK.
content:
application/json:
schema:
type: 'null'
examples:
Response:
value: null
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
examples:
WrongPayloadFormatRequested:
value:
errors:
- status: '400'
code: non_field_errors
title: Wrong format
detail: Wrong request format, expected object
operationId: sc-public-v3-integrations-post-shop_order_statuses
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
tags:
- Integrations
/shop-order-statuses/mapping:
get:
summary: Retrieve custom status mapping for an integration
description: >
Fetch a map of available shop order statuses and Sendcloud's internal
status category for the integration.
x-mint:
href: /api/v3/integrations/retrieve-custom-status-mapping-for-an-integration
content: |-
<Warning>
Only the Prestashop V2 integration is supported.
</Warning>
parameters:
- $ref: '#/components/parameters/required_integration_id'
responses:
'200':
description: Custom status mapping for an integration.
content:
application/json:
schema:
type: object
$ref: '#/components/schemas/get-custom-status-mapping'
examples:
Response:
value:
data:
integration_id: 23452345
mapping:
- status_category: READY_TO_SEND
external_id: '11'
is_valid: true
- status_category: IN_TRANSIT
external_id: '11'
is_valid: true
- status_category: DELIVERED
external_id: null
is_valid: true
- status_category: CANCEL
external_id: '1'
is_valid: false
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
examples:
InvalidRequest:
value:
errors:
- status: '400'
code: non_field_errors
title: integration ID
detail: Integration ID is a required GET parameter
operationId: sc-public-v3-integrations-get-shop_order_statuses_mapping
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
tags:
- Integrations
post:
summary: Create or update custom status mapping for an integration
description: >-
Upsert a map of available shop order statuses and Sendcloud's internal
status category for an integration
x-mint:
href: >-
/api/v3/integrations/create-or-update-custom-status-mapping-for-an-integration
content: |-
<Warning>
Only the Prestashop V2 integration is supported.
</Warning>
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/create-custom-status-mapping'
# --- truncated at 32 KB (57 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sendcloud/refs/heads/main/openapi/sendcloud-v3-integrations-openapi.yml