openapi: 3.1.0
info:
title: Event Subscriptions API
version: 3.0.0
description: >-
**BETA** - The Event Subscriptions API allows you to subscribe to parcel
events and have them delivered to external endpoints such as webhooks or
Klaviyo.
This API uses a two-part model:
- **Connections** define _where_ events are delivered (e.g., a webhook URL
or a Klaviyo account).
- **Subscriptions** define _which_ events are routed to a connection.
All resources are scoped to the authenticated user's organization.
contact:
name: Sendcloud API Support
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/v3
description: Sendcloud Production
tags:
- name: Connections
- name: Subscriptions
- name: OAuth2
- name: Broadcast
- name: Events
paths:
/event-subscriptions/connections:
post:
summary: Create a connection
description: >-
Create a new connection to an external endpoint where event
notifications will be delivered.
tags:
- Connections
operationId: sc-public-v3-scp-post-create_connection
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
x-mint:
href: /api/v3/event-subscriptions/create-a-connection
content: >-
Create a new connection that defines an external endpoint for event
delivery.
**Webhook connections** require a `url` and optionally authentication
configuration. Supported authentication types are `none`, `bearer`,
`basic`, and `api_key`.
**Klaviyo connections** require only the `type` field set to `klaviyo`
with an empty `configuration` object. After creating the connection,
use the [Start OAuth2
authorization](/api/v3/event-subscriptions/start-oauth2-authorization)
endpoint to connect your Klaviyo account.
Webhook URLs must be publicly accessible and respond with a `2xx` status code to acknowledge event delivery.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/connection-create-request'
examples:
WebhookConnection:
summary: Create a webhook connection with bearer auth
value:
type: webhook
configuration:
url: https://example.com/webhooks/sendcloud
auth_type: bearer
auth_config:
token: my-secret-token
extra_headers:
X-Custom-Header: my-value
WebhookConnectionNoAuth:
summary: Create a webhook connection without auth
value:
type: webhook
configuration:
url: https://example.com/webhooks/sendcloud
auth_type: none
KlaviyoConnection:
summary: Create a Klaviyo connection
value:
type: klaviyo
configuration: {}
responses:
'201':
description: Created
content:
application/json:
schema:
description: Connection created
type: object
properties:
data:
$ref: '#/components/schemas/connection'
examples:
WebhookCreated:
summary: Webhook connection created
value:
data:
id: 1
type: webhook
configuration:
url: https://example.com/webhooks/sendcloud
auth_type: bearer
extra_headers:
X-Custom-Header: my-value
created_at: '2026-01-15T10:30:00Z'
updated_at: '2026-01-15T10:30:00Z'
KlaviyoCreated:
summary: Klaviyo connection created
value:
data:
id: 2
type: klaviyo
configuration: {}
created_at: '2026-01-15T10:30:00Z'
updated_at: '2026-01-15T10:30:00Z'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
examples:
ValidationError:
summary: Validation error
value:
errors:
- detail: This field is required.
status: '400'
source:
pointer: /data/type
code: required
'429':
description: Throttled
get:
summary: List connections
description: Retrieve all connections for the authenticated user's organization.
tags:
- Connections
operationId: sc-public-v3-scp-get-list_connections
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
x-mint:
href: /api/v3/event-subscriptions/list-connections
parameters:
- schema:
type: string
enum:
- webhook
- klaviyo
in: query
name: connection_type
description: Filter by connection type.
responses:
'200':
description: OK
content:
application/json:
schema:
description: List of connections
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/connection'
required:
- data
examples:
ListConnections:
summary: List of connections
value:
data:
- id: 1
type: webhook
configuration:
url: https://example.com/webhooks/sendcloud
auth_type: bearer
extra_headers:
X-Custom-Header: my-value
created_at: '2026-01-15T10:30:00Z'
updated_at: '2026-01-15T10:30:00Z'
- id: 2
type: klaviyo
configuration: {}
created_at: '2026-01-16T09:00:00Z'
updated_at: '2026-01-16T09:00:00Z'
'429':
description: Throttled
/event-subscriptions/connections/{id}:
parameters:
- schema:
type: integer
in: path
name: id
description: The id of the connection.
required: true
get:
summary: Get a connection
description: Retrieve a specific connection by its id.
tags:
- Connections
operationId: sc-public-v3-scp-get-connection
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
x-mint:
href: /api/v3/event-subscriptions/get-a-connection
responses:
'200':
description: OK
content:
application/json:
schema:
description: Connection details
type: object
properties:
data:
$ref: '#/components/schemas/connection'
examples:
GetConnection:
summary: Get a webhook connection
value:
data:
id: 1
type: webhook
configuration:
url: https://example.com/webhooks/sendcloud
auth_type: bearer
extra_headers:
X-Custom-Header: my-value
created_at: '2026-01-15T10:30:00Z'
updated_at: '2026-01-15T10:30:00Z'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
patch:
summary: Update a connection
description: >-
Update an existing connection by its id. Only the fields provided in the
request body will be updated.
tags:
- Connections
operationId: sc-public-v3-scp-patch-connection
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
x-mint:
href: /api/v3/event-subscriptions/update-a-connection
content: >-
Update the configuration of an existing connection.
Only the fields provided in the request body will be updated. For
example, you can update just the webhook URL or authentication
settings without changing other fields.
Updating a connection's configuration may affect all subscriptions that use this connection.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/connection-update-request'
examples:
UpdateWebhookUrl:
summary: Update the webhook URL
value:
configuration:
url: https://example.com/webhooks/sendcloud-v2
UpdateAuth:
summary: Update authentication settings
value:
configuration:
auth_type: api_key
auth_config:
header_name: X-Api-Key
api_key: my-new-api-key
responses:
'200':
description: OK
content:
application/json:
schema:
description: Updated connection
type: object
properties:
data:
$ref: '#/components/schemas/connection'
examples:
UpdatedConnection:
summary: Updated webhook connection
value:
data:
id: 1
type: webhook
configuration:
url: https://example.com/webhooks/sendcloud-v2
auth_type: api_key
extra_headers:
X-Custom-Header: my-value
created_at: '2026-01-15T10:30:00Z'
updated_at: '2026-01-20T14:00:00Z'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
examples:
ValidationError:
summary: Validation error
value:
errors:
- detail: Enter a valid URL.
status: '400'
source:
pointer: /data/configuration/url
code: invalid
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
delete:
summary: Delete a connection
description: >-
Delete a specific connection by its id. Any subscriptions associated
with this connection will also be deleted.
tags:
- Connections
operationId: sc-public-v3-scp-delete-connection
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
x-mint:
href: /api/v3/event-subscriptions/delete-a-connection
content: |-
Delete a connection and all its associated subscriptions.
This action is irreversible. All subscriptions linked to this connection will be permanently deleted and event delivery will stop immediately.
responses:
'204':
description: No Content
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
/event-subscriptions/connections/{id}/authorization:
parameters:
- schema:
type: integer
in: path
name: id
description: The id of the connection to authorize.
required: true
post:
summary: Start OAuth2 authorization
description: >-
Initiate the OAuth2 authorization flow for a connection that requires it
(e.g., Klaviyo). Returns an authorization URL to redirect the user to.
tags:
- OAuth2
operationId: sc-public-v3-scp-post-start_authorization
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
x-mint:
href: /api/v3/event-subscriptions/start-oauth2-authorization
content: >-
Start the OAuth2 authorization flow for a Klaviyo connection. This
endpoint returns an authorization URL that the user should be
redirected to in their browser.
After the user authorizes access, the OAuth provider will redirect
back to the Sendcloud callback URL, completing the connection setup.
Use the [Create a connection](/api/v3/event-subscriptions/create-a-connection) endpoint with `type: "klaviyo"`.
Call this endpoint to get the authorization URL.
Open the `authorization_url` in the user's browser to complete the OAuth2 flow.
responses:
'200':
description: OK
content:
application/json:
schema:
description: OAuth2 authorization URL
type: object
properties:
data:
$ref: '#/components/schemas/connection-authorization-response'
examples:
AuthorizationUrl:
summary: OAuth2 authorization URL
value:
data:
authorization_url: >-
https://www.klaviyo.com/oauth/authorize?client_id=sendcloud&response_type=code&redirect_uri=https%3A%2F%2Fpanel.sendcloud.sc%2Fapi%2Fv3%2Fevent-subscriptions%2Fconnections%2Fauthorization%2Fcallback&state=abc123
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
/event-subscriptions/subscriptions:
post:
summary: Create a subscription
description: >-
Create a new subscription that routes events of a specific type to a
connection.
tags:
- Subscriptions
operationId: sc-public-v3-scp-post-create_subscription
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
x-mint:
href: /api/v3/event-subscriptions/create-a-subscription
content: >-
Create a subscription that routes a specific event type to a
connection for delivery.
A subscription links an event type (e.g., `parcels.event.created`) to
a connection endpoint. When the event occurs, the event payload is
delivered to the connection's configured endpoint.
Subscriptions are active by default. Set `is_active` to `false` to create a paused subscription.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/subscription-create-request'
examples:
CreateSubscription:
summary: Create a subscription for parcel events
value:
connection_id: 1
event_type: parcels.event.created
is_active: true
responses:
'201':
description: Created
content:
application/json:
schema:
description: Subscription created
type: object
properties:
data:
$ref: '#/components/schemas/subscription'
examples:
SubscriptionCreated:
summary: Subscription created
value:
data:
id: 1
connection_id: 1
event_type: parcels.event.created
is_active: true
created_at: '2026-01-15T11:00:00Z'
updated_at: '2026-01-15T11:00:00Z'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
examples:
ValidationError:
summary: Validation error
value:
errors:
- detail: This field is required.
status: '400'
source:
pointer: /data/connection_id
code: required
'429':
description: Throttled
get:
summary: List subscriptions
description: Retrieve all subscriptions for the authenticated user's organization.
tags:
- Subscriptions
operationId: sc-public-v3-scp-get-list_subscriptions
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
x-mint:
href: /api/v3/event-subscriptions/list-subscriptions
parameters:
- schema:
type: string
in: query
name: event_type
description: Filter by event type.
- schema:
type: boolean
in: query
name: is_active
description: Filter by active status.
responses:
'200':
description: OK
content:
application/json:
schema:
description: List of subscriptions
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/subscription'
required:
- data
examples:
ListSubscriptions:
summary: List of subscriptions
value:
data:
- id: 1
connection_id: 1
event_type: parcels.event.created
is_active: true
created_at: '2026-01-15T11:00:00Z'
updated_at: '2026-01-15T11:00:00Z'
- id: 2
connection_id: 2
event_type: parcels.event.created
is_active: false
created_at: '2026-01-16T09:15:00Z'
updated_at: '2026-01-16T09:15:00Z'
'429':
description: Throttled
/event-subscriptions/subscriptions/{id}:
parameters:
- schema:
type: integer
in: path
name: id
description: The id of the subscription.
required: true
get:
summary: Get a subscription
description: Retrieve a specific subscription by its id.
tags:
- Subscriptions
operationId: sc-public-v3-scp-get-subscription
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
x-mint:
href: /api/v3/event-subscriptions/get-a-subscription
responses:
'200':
description: OK
content:
application/json:
schema:
description: Subscription details
type: object
properties:
data:
$ref: '#/components/schemas/subscription'
examples:
GetSubscription:
summary: Get a subscription
value:
data:
id: 1
connection_id: 1
event_type: parcels.event.created
is_active: true
created_at: '2026-01-15T11:00:00Z'
updated_at: '2026-01-15T11:00:00Z'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
patch:
summary: Update a subscription
description: >-
Update an existing subscription by its id. Only the fields provided in
the request body will be updated.
tags:
- Subscriptions
operationId: sc-public-v3-scp-patch-subscription
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
x-mint:
href: /api/v3/event-subscriptions/update-a-subscription
content: >-
Update an existing subscription. You can change the connection, event
type, or toggle the active state.
Set `is_active` to `false` to pause event delivery without deleting the subscription.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/subscription-update-request'
examples:
PauseSubscription:
summary: Pause a subscription
value:
is_active: false
ChangeConnection:
summary: Route events to a different connection
value:
connection_id: 2
responses:
'200':
description: OK
content:
application/json:
schema:
description: Updated subscription
type: object
properties:
data:
$ref: '#/components/schemas/subscription'
examples:
UpdatedSubscription:
summary: Updated subscription
value:
data:
id: 1
connection_id: 2
event_type: parcels.event.created
is_active: false
created_at: '2026-01-15T11:00:00Z'
updated_at: '2026-01-20T14:30:00Z'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
delete:
summary: Delete a subscription
description: >-
Delete a specific subscription by its id. Event delivery for this
subscription will stop immediately.
tags:
- Subscriptions
operationId: sc-public-v3-scp-delete-subscription
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
x-mint:
href: /api/v3/event-subscriptions/delete-a-subscription
responses:
'204':
description: No Content
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
/event-subscriptions/broadcast/test/{subscription_id}:
parameters:
- schema:
type: integer
in: path
name: subscription_id
description: The id of the subscription to send a test event to.
required: true
post:
summary: Broadcast test event
description: >-
Send a test event to the connection endpoint configured for a specific
subscription. Use this to verify that your connection is set up
correctly before relying on it for production events.
tags:
- Broadcast
operationId: sc-public-v3-scp-post-test_broadcast
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
x-mint:
href: /api/v3/event-subscriptions/test-event-delivery
content: >-
Send a test event to the connection endpoint configured for this
subscription. This is useful for verifying that your webhook URL or
Klaviyo integration is set up correctly.
The test event will contain a sample payload matching the
subscription's event type.
The test broadcast will use the same authentication and headers configured on the connection.
responses:
'200':
description: OK
content:
application/json:
schema:
description: Test broadcast result
type: object
properties:
data:
$ref: '#/components/schemas/broadcast-result'
examples:
SuccessfulBroadcast:
summary: Successful test broadcast
value:
data:
success: true
status_code: 200
response_body: OK
FailedBroadcast:
summary: Failed test broadcast
value:
data:
success: false
status_code: 500
response_body: Internal Server Error
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
webhooks:
ParcelEventCreated:
post:
operationId: sc-public-v3-event-subscriptions-parcel_event_created
summary: Parcel event created
description: >-
Delivered to your connection endpoint when a parcel tracking event
occurs (e.g., a status change such as shipped, delivered, or returned).
Subscribe to this event type using `parcels.event.created` when creating
a subscription.
x-mint:
href: /api/v3/event-subscriptions/parcel-event-created
tags:
- Events
security: []
requestBody:
description: Event data delivered to your endpoint
content:
application/json:
schema:
$ref: '#/components/schemas/ParcelEventCreatedPayload'
examples:
InTransit:
summary: Parcel in transit
value:
event_type: parcels.event.created
data:
parcel:
parcel_id: 12345678
tracking_number: 3SYZXG132912330
carrier_code: dpd
announced_at: '2026-01-15T10:00:00Z'
order_number: ORDER-12345
event:
event_type: carrier
timestamp: '2026-01-15T10:30:00Z'
phase: in_transit
exception: none
status_type: success
sub_status: none
description: Parcel is on its way
end_of_tracking: false
is_offered: false
is_carrier_responsible: null
is_returned: false
location_details:
city: Eindhoven
country: NL
house_number: null
postal_code: null
street: null
service_point_id: null
depot: null
extra_data: null
Delivered:
summary: Parcel delivered
value:
event_type: parcels.event.created
data:
parcel:
parcel_id: 12345678
tracking_number: 3SYZXG132912330
carrier_code: dpd
announced_at: '2026-01-15T10:00:00Z'
order_number: ORDER-12345
event:
event_type: carrier
timestamp: '2026-01-16T14:22:00Z'
phase: delivered
exception: none
status_type: success
sub_status: none
description: Parcel has been delivered
end_of_tracking: true
is_offered: true
is_carrier_responsible: null
is_returned: false
location_details: null
extra_data: null
responses:
'200':
description: Return a 2xx status to acknowledge receipt of the event.
components:
schemas:
ParcelEventCreatedPayload:
type: object
description: >-
Event payload delivered to your endpoint when a parcel tracking event
occurs.
required:
- event_type
- data
properties:
event_type:
type: string
description: The event type identifier.
example: parcels.event.created
enum:
- parcels.event.created
data:
type: object
description: The event payload.
required:
- parcel
- event
properties:
parcel:
$ref: '#/components/schemas/WebhookParcelData'
event:
$ref: '#/components/schemas/WebhookEventData'
WebhookParcelData:
type: object
description: Parcel identifiers included in event deliveries.
required:
- parcel_id
- carrier_code
properties:
parcel_id:
type: integer
description: Sendcloud parcel identifier.
example: 12345678
tracking_number:
type:
- string
- 'null'
description: Carrier-issued tracking number.
example: 3SYZXG132912330
carrier_code:
type: string
description: Short carrier code (e.g. `dpd`, `dhl`, `postnl`).
example: dpd
announced_at:
type:
- string
- 'null'
format: date-time
description: >-
ISO 8601 timestamp of when the carrier was announced for this
parcel.
example: '2026-01-15T10:00:00Z'
order_number:
type:
- string
- 'null'
description: Order number associated with the parcel.
example: ORDER-12345
WebhookEventData:
type: object
description: Parcel tracking event data.
required:
- event_type
- timestamp
- phase
- exception
- status_type
- sub_status
properties:
event_type:
$ref: '#/components/schemas/parcel-event-type'
timestamp:
type: string
format: date-time
description: ISO 8601 timestamp of when the event occurred.
example: '2026-01-15T10:30:00Z'
phase:
$ref: '#/components/schemas/parcel-event-phase'
exception:
$ref: '#/components/schemas/parcel-event-exception'
status_type:
$ref: '#/components/schemas/parcel-event-status-type'
sub_status:
$ref: '#/components/schemas/parcel-event-sub-status'
description:
type:
- string
- 'null'
description: Human-readable carrier description of the event.
example: Parcel is on its way
end_of_tracking:
type:
- boolean
- 'null'
description: True when there will be no further tracking updates.
example: false
is_offered:
type:
- boolean
- 'null'
description: True when the parcel was offered for delivery.
example: false
is_carrier_responsible:
type:
- boolean
- 'null'
description: True when the carrier is responsible for the event.
example: null
is_returned:
type:
- boolean
- 'null'
description: True when this event belongs to a return shipment.
example: false
location_details:
oneOf:
- $ref: '#/components/schemas/WebhookLocationData'
- type: 'null'
description: Location where the event occurred, if available.
extra_data:
type:
- object
- 'null'
description: Additional carrier-specific data. Structure varies per carrier.
example: null
WebhookLocationData:
type: object
description: Location details associated with a carrier event.
properties:
city:
type:
- string
- 'null'
description: City where the event occurred.
example: Eindhoven
country:
type:
- string
- 'null'
description: ISO 3166-1 alpha-2 country code.
example: NL
house_number:
type:
- string
- 'null'
description: Street house number.
example: '10'
postal_code:
type:
- string
- 'null'
description: Postal / zip code.
example: 5611 EM
street:
type:
- string
- 'null'
description: Street name.
example: Stadhuisplein
service_point_id:
type:
- integer
- 'null'
description: Service point identifier, if applicable.
example: null
depot:
type:
- string
- 'null'
description: Carrier depot name, if applicable.
example: null
connection:
title: Connection
description: >-
A connection defines an external endpoint where event notifications are
delivered.
type: object
properties:
id:
type: integer
format: int64
minimum: 1
description: Unique identifier of the connection.
type:
type: string
description: The type of connection.
enum:
- webhook
- klaviyo
configuration:
type: object
description: >-
The configuration for the connection. The shape depends on the
connection type.
created_at:
type: string
format: date-time
description: >-
The date and time when the connection was created, in ISO 8601
format.
updated_at:
type: string
format: date-time
description: >-
The date and time when the connection was last updated, in ISO 8601
format.
connection-create-request:
title: Create Connection request
description: Request body for creating a new connection.
type: object
required:
- type
- configuration
properties:
type:
type: string
description: The type of connection.
enum:
- webhook
- klaviyo
configuration:
type: object
description: >-
The configuration for the connection. The shape depends on the
connection type.
For `webhook` connections, see the webhook configuration fields.
For `klaviyo` connections, configuration can be an empty object as
credentials are managed via OAuth2.
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.
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
connection-update-request:
title: Update Connection request
description: >-
Request body for updating an existing connection. All fields are
optional.
type: object
properties:
type:
type: string
description: The type of connection.
enum:
- webhook
- klaviyo
configuration:
type: object
description: >-
The configuration for the connection. The shape depends on the
connection type.
For `webhook` connections, see the webhook configuration fields.
For `klaviyo` connections, configuration can be an empty object as
credentials are managed via OAuth2.
connection-authorization-response:
title: Authorization Response
description: >-
Response containing the OAuth2 authorization URL for connecting external
services like Klaviyo.
type: object
properties:
authorization_url:
type: string
format: uri
description: >-
The URL to redirect the user to for OAuth2 authorization with the
external service.
subscription:
title: Subscription
description: >-
A subscription routes a specific event type to a connection for
delivery.
type: object
properties:
id:
type: integer
format: int64
minimum: 1
description: Unique identifier of the subscription.
connection_id:
type: integer
format: int64
minimum: 1
description: >-
The identifier of the connection this subscription delivers events
to.
event_type:
type: string
description: The type of event this subscription listens for.
enum:
- parcels.event.created
is_active:
type: boolean
description: Whether the subscription is currently active and delivering events.
created_at:
type: string
format: date-time
description: >-
The date and time when the subscription was created, in ISO 8601
format.
updated_at:
type: string
format: date-time
description: >-
The date and time when the subscription was last updated, in ISO
8601 format.
subscription-create-request:
title: Create Subscription request
description: Request body for creating a new subscription.
type: object
required:
- connection_id
- event_type
properties:
connection_id:
type: integer
format: int64
minimum: 1
description: The identifier of the connection to deliver events to.
event_type:
type: string
description: The type of event to subscribe to.
enum:
- parcels.event.created
is_active:
type: boolean
description: >-
Whether the subscription should be active immediately. Defaults to
`true`.
default: true
subscription-update-request:
title: Update Subscription request
description: >-
Request body for updating an existing subscription. All fields are
optional.
type: object
properties:
connection_id:
type: integer
format: int64
minimum: 1
description: The identifier of the connection to deliver events to.
event_type:
type: string
description: The type of event to subscribe to.
enum:
- parcels.event.created
is_active:
type: boolean
description: Whether the subscription should be active.
broadcast-result:
title: Broadcast Result
description: >-
The result of a test event broadcast to a subscription's connection
endpoint.
type: object
properties:
success:
type: boolean
description: Whether the test event was successfully delivered.
status_code:
type: integer
description: The HTTP status code returned by the connection endpoint.
response_body:
type: string
description: The response body returned by the connection endpoint.
parcel-event-type:
type: string
title: Parcel Event Type
description: Classification of the event source.
enum:
- carrier
- internal
- calculated
- claim
example: carrier
parcel-event-phase:
type: string
title: Parcel Event Phase
description: Current delivery phase.
enum:
- accepted
- announced
- announcing
- attempted
- cancelled
- customs
- delivered
- delivery_forced
- dropped
- in_delivery
- in_transit
- labelled
- none
- no_label
- pup
- ready_to_send
- sorted
- unknown
example: in_transit
parcel-event-exception:
type: string
title: Parcel Event Exception
description: Exception on the current phase, or `none` when on the expected path.
enum:
- address_error
- announcement_failed
- cancellation_failed
- cancelled
- cancelled_upstream
- cancelling
- cancelling_upstream
- changed
- claim
- claimable
- customer_rejected
- customer_support
- customs_issue
- damaged
- delay_unknown
- delivery_delay
- dropoff_expiration
- handover_delay
- hold
- missing
- none
- non_conformity
- off_radar
- pup_expiration
- refused
- relabelled
- returned_sender
- sorting_delay
- unknown
example: none
parcel-event-status-type:
type: string
title: Parcel Event Status Type
description: Severity of the event.
enum:
- error
- success
- warning
example: success
parcel-event-sub-status:
type: string
title: Parcel Event Sub Status
description: Additional granularity within the phase/exception combination.
enum:
- accepted
- additional_information
- carrier
- company_closed
- connection_missed
- content
- cut_off
- damaged
- delay
- delivery_change
- disposed
- documents
- duplicate
- expired
- high_volume
- inaccessible
- incorrect_information
- in_progress
- late
- locker
- mailbox
- max_measure
- max_weight
- mechanical
- misrouted
- missort
- neighbour
- none
- not_home
- not_ordered
- one
- packaging
- parcel_found
- partly
- passed
- payment
- postal_box
- prohibited_item
- pup
- pup_closed
- receiver
- rejected
- requested
- resolved
- safeplace
- sender
- shop
- signature
- three
- traffic
- two
- undeliverable
- unknown
- unknown_receiver
- updated
- weather_conditions
example: none
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.