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:
- write:event-subscription
x-mint:
href: /api/v3/event-subscriptions/create-a-connection
content: |-
OAuth2 scopes required: `write:event-subscription`. See [Scopes for OAuth apps](/api/v3/scopes).
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:
- read:event-subscription
x-mint:
href: /api/v3/event-subscriptions/list-connections
content: |-
OAuth2 scopes required: `read:event-subscription`. See [Scopes for OAuth apps](/api/v3/scopes).
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:
- read:event-subscription
x-mint:
href: /api/v3/event-subscriptions/get-a-connection
content: |-
OAuth2 scopes required: `read:event-subscription`. See [Scopes for OAuth apps](/api/v3/scopes).
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:
- write:event-subscription
x-mint:
href: /api/v3/event-subscriptions/update-a-connection
content: |-
OAuth2 scopes required: `write:event-subscription`. See [Scopes for OAuth apps](/api/v3/scopes).
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:
type: webhook
configuration:
url: https://example.com/webhooks/sendcloud-v2
UpdateAuth:
summary: Update authentication settings
value:
type: webhook
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:
- write:event-subscription
x-mint:
href: /api/v3/event-subscriptions/delete-a-connection
content: |-
OAuth2 scopes required: `write:event-subscription`. See [Scopes for OAuth apps](/api/v3/scopes).
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:
- write:event-subscription
x-mint:
href: /api/v3/event-subscriptions/start-oauth2-authorization
content: |-
OAuth2 scopes required: `write:event-subscription`. See [Scopes for OAuth apps](/api/v3/scopes).
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:
- write:event-subscription
x-mint:
href: /api/v3/event-subscriptions/create-a-subscription
content: |-
OAuth2 scopes required: `write:event-subscription`. See [Scopes for OAuth apps](/api/v3/scopes).
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:
- read:event-subscription
x-mint:
href: /api/v3/event-subscriptions/list-subscriptions
content: |-
OAuth2 scopes required: `read:event-subscription`. See [Scopes for OAuth apps](/api/v3/scopes).
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:
- read:event-subscription
x-mint:
href: /api/v3/event-subscriptions/get-a-subscription
content: |-
OAuth2 scopes required: `read:event-subscription`. See [Scopes for OAuth apps](/api/v3/scopes).
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:
- write:event-subscription
x-mint:
href: /api/v3/event-subscriptions/update-a-subscription
content: |-
OAuth2 scopes required: `write:event-subscription`. See [Scopes for OAuth apps](/api/v3/scopes).
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:
- write:event-subscription
x-mint:
href: /api/v3/event-subscriptions/delete-a-subscription
content: |-
OAuth2 scopes required: `write:event-subscription`. See [Scopes for OAuth apps](/api/v3/scopes).
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:
- write:event-subscription
x-mint:
href: /api/v3/event-subscriptions/test-event-delivery
content: |-
OAuth2 scopes required: `write:event-subscription`. See [Scopes for OAuth apps](/api/v3/scopes).
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: Parcels 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
content: |-
A single subscription to `parcels.event.created` delivers two unrelated response shapes, selected by `data.event.event_type`:
| `event.event_type` | Response shape | What it represents |
| --- | --- | --- |
| `carrier`, `calculated`, `internal` | `Tracking Event` | A parcel tracking update: `phase`/`exception`/`status_type`/`sub_status` plus location and carrier metadata. |
| `claim` | `Claim Event` | A Support Automation ticket update: its own `phase`/`sub_status` values, ticket/category identifiers, and refund/resolution fields. |
The two shapes do not share fields beyond `event_type` and `timestamp` — in particular, `phase` and `sub_status` are *different enums* on each shape. Always check `event.event_type` first and parse the rest of `event` according to that value; do not assume a tracking field (e.g. `exception`) is present on a claim event, or vice versa.
### Parsing the payload
Whatever language you use, the approach is the same:
1. Read `data.event.event_type`.
2. Pick the model: `carrier`, `calculated` or `internal` → `Tracking Event`; `claim` → `Claim Event`.
3. Parse `data.event` with that model. Treat `phase`, `sub_status`, `category`, `resolution` and `origin` as plain strings, because new values can be added at any time.
```python Python (Pydantic v2)
from typing import Annotated, Literal, Union
from pydantic import BaseModel, Field
class TrackingEvent(BaseModel):
event_type: Literal["carrier", "calculated", "internal"]
timestamp: str
phase: str
sub_status: str
# ...other tracking fields
class ClaimEvent(BaseModel):
event_type: Literal["claim"]
timestamp: str
phase: str
sub_status: str
ticket_id: int
claim_event_id: int
# ...other claim fields
class EventData(BaseModel):
event: Annotated[Union[TrackingEvent, ClaimEvent], Field(discriminator="event_type")]
```
```typescript TypeScript (Zod)
import { z } from "zod";
const TrackingEvent = z.object({
event_type: z.enum(["carrier", "calculated", "internal"]),
timestamp: z.string(),
phase: z.string(),
sub_status: z.string(),
// ...other tracking fields
});
const ClaimEvent = z.object({
event_type: z.literal("claim"),
timestamp: z.string(),
phase: z.string(),
sub_status: z.string(),
ticket_id: z.number().int(),
claim_event_id: z.number().int(),
// ...other claim fields
});
const EventData = z.object({
event: z.discriminatedUnion("event_type", [
TrackingEvent.extend({ event_type: z.literal("carrier") }),
TrackingEvent.extend({ event_type: z.literal("calculated") }),
TrackingEvent.extend({ event_type: z.literal("internal") }),
ClaimEvent,
]),
});
```
```php PHP
### Identifying the parcel
- `data.parcel.parcel_id`: the Sendcloud tracking parcel ID. It is not the Shipping API parcel ID.
- `data.parcel.source_id`: the parcel ID in the source system. The value depends on `data.parcel.source`:
- `shipping`: the Shipping API parcel ID.
- `external_parcel`: the ID you sent when you registered the parcel with the Parcel Tracking API.
- `source_id` is unique for `shipping` parcels.
- For `external_parcel` parcels, `source_id` is your own reference. Do not use it as a unique key: if you use the same reference with a different carrier, two parcels have the same `source_id`.
### Internal events
- Events with `event_type` `internal` come from Sendcloud, not from the carrier.
- Examples: announcing, announced, ready to send, cancelled.
- An internal event can arrive before the `parcel.created` event for the same parcel.
### Events sent again
Sendcloud can send the same carrier event more than one time.
- `event.id` stays the same for each copy. For internal and calculated events, `event.id` is `null`.
- The data can change between copies. When you get an `event.id` that you already have, replace the earlier copy.
- Example: a carrier sends a status code that Sendcloud does not know yet. Sendcloud sends the event with an unknown status. When Sendcloud maps the status code, it sends the event again with the correct status. Sendcloud does this only for carrier events from the last 7 days.
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
source: shipping
source_id: '412345678'
event:
id: 734512001
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
source: shipping
source_id: '412345678'
event:
id: 734512088
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
ClaimTicketCreated:
summary: 'Claim: Support Automation ticket created for a parcel'
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
source: shipping
source_id: '412345678'
event:
event_type: claim
timestamp: '2026-01-17T09:00:00Z'
phase: open
sub_status: none
category: lost
ticket_id: 987654
claim_event_id: 555111
refund_price: null
refund_price_eur: null
request_id: null
attachment_type: null
title: null
message: null
resolution: null
origin: public
ClaimActionRequired:
summary: 'Claim: Support Automation ticket requires customer action'
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
source: shipping
source_id: '412345678'
event:
event_type: claim
timestamp: '2026-01-18T11:15:00Z'
phase: action_required
sub_status: customer_documents_requested
category: lost
ticket_id: 987654
claim_event_id: 555112
refund_price:
value: '54.90'
currency: USD
refund_price_eur:
value: '50.12'
currency: EUR
request_id: 4321
attachment_type: photo
title: We need a photo of the damaged item
message: Please upload a photo showing the damage to proceed with your claim.
resolution: null
origin: public
ClaimResolved:
summary: 'Claim: Support Automation ticket resolved'
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
source: shipping
source_id: '412345678'
event:
event_type: claim
timestamp: '2026-01-20T16:45:00Z'
phase: manually_solved_stage
sub_status: solved
category: lost
ticket_id: 987654
claim_event_id: 555113
refund_price:
value: '54.90'
currency: USD
refund_price_eur:
value: '50.12'
currency: EUR
request_id: null
attachment_type: null
title: null
message: null
resolution: claim_approved
origin: public
responses:
'200':
description: Return a 2xx status to acknowledge receipt of the event.
ParcelCreated:
post:
operationId: sc-public-v3-event-subscriptions-parcel_created
summary: Parcel created
description: |-
Delivered to your connection endpoint when a parcel is created in Sendcloud, including its addresses, shipping option and items.
Subscribe to this event type using `parcel.created` when creating a subscription.
x-mint:
href: /api/v3/event-subscriptions/parcel-created
tags:
- Events
security: []
requestBody:
description: Event data delivered to your endpoint
content:
application/json:
schema:
$ref: '#/components/schemas/ParcelCreatedPayload'
examples:
OutboundParcel:
summary: Outbound parcel with order and items
value:
event_type: parcel.created
data:
id: 12345678
source: shipping
source_id: '412345678'
created_at: '2026-01-15T09:58:12.482913Z'
updated_at: '2026-01-15T09:58:12.482913Z'
announced_at: '2026-01-15T10:00:00Z'
organization_id: 87654
ship_with:
type: shipping_option_code
properties:
shipping_option_code: dpd:standard
contract_id: 517
tracking_numbers:
- carrier_code: dpd
tracking_number: 3SYZXG132912330
tracking_identifier: 3SYZXG132912330
tracking_url: https://tracking.sendcloud.sc/forward?carrier=dpd&code=3SYZXG132912330
details:
is_return: false
brand_id: 1234
integration_id: 5678
external_reference: WMS-2026-000123
dimensions:
length: '30.00'
width: '20.00'
height: '10.00'
unit: cm
weight:
value: '1.250'
unit: kg
order:
order_number: ORDER-12345
ordered_at: '2026-01-14T16:42:03Z'
total_price:
value: '54.90'
currency: EUR
from_address:
name: Marie Doe
company_name: Sendcloud
address_line_1: Stadhuisplein 10
house_number: '10'
address_line_2: 2e verdieping
postal_code: 5611 EM
city: Eindhoven
state_province_code: null
country_code: NL
email: marie.doe@sendcloud.com
phone_number: '+31612345678'
po_box: null
to_address:
name: John Doe
company_name: null
address_line_1: Insulindelaan 115
house_number: '115'
address_line_2: null
postal_code: 5642 CV
city: Eindhoven
state_province_code: null
country_code: NL
email: john.doe@sendcloud.com
phone_number: '+31612345679'
po_box: null
parcel_items:
- item_id: '5552'
name: null
description: T-Shirt XL
product_id: '19284'
variant_id: 19284-XL
image_url: null
measurement:
dimension: null
weight:
value: '0.300'
unit: kg
volume: null
quantity: 2
sku: TS1234
hs_code: '620520'
ean: null
properties: null
country_of_origin: NL
total_price: null
unit_price:
value: '12.65'
currency: EUR
delivery_dates: null
mid_code: null
material_content: null
intended_use: null
manufacturer_product_id: null
manufacturer_product_id_std: null
dangerous_goods: null
ReturnParcel:
summary: Return parcel without order or item data
value:
event_type: parcel.created
data:
id: 12345679
source: shipping
source_id: '412345679'
created_at: '2026-01-18T08:12:44.019233Z'
updated_at: '2026-01-18T08:12:44.019233Z'
announced_at: null
organization_id: 87654
ship_with:
type: shipping_option_code
properties:
shipping_option_code: dpd:return
contract_id: null
tracking_numbers:
- carrier_code: dpd
tracking_number: null
tracking_identifier: null
tracking_url: null
details:
is_return: true
brand_id: null
integration_id: null
external_reference: null
dimensions:
length: null
width: null
height: null
unit: null
weight:
value: '0.500'
unit: kg
order: null
from_address:
name: John Doe
company_name: null
address_line_1: Insulindelaan 115
house_number: '115'
address_line_2: null
postal_code: 5642 CV
city: Eindhoven
state_province_code: null
country_code: NL
email: john.doe@sendcloud.com
phone_number: '+31612345679'
po_box: null
to_address:
name: Marie Doe
company_name: Sendcloud
address_line_1: Stadhuisplein 10
house_number: '10'
address_line_2: 2e verdieping
postal_code: 5611 EM
city: Eindhoven
state_province_code: null
country_code: NL
email: marie.doe@sendcloud.com
phone_number: '+31612345678'
po_box: null
parcel_items: []
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:
type: object
description: 'The event that triggered this delivery. Its shape depends on `event.event_type`: `carrier`/`calculated`/`internal` resolve to `Tracking Event`, `claim` resolves to `Claim Event`. The two share no fields beyond `event_type` and `timestamp` — always branch on `event.event_type` before reading any other field.'
oneOf:
- $ref: '#/components/schemas/WebhookTrackingEventData'
- $ref: '#/components/schemas/WebhookClaimEventData'
discriminator:
propertyName: event_type
mapping:
carrier: '#/components/schemas/WebhookTrackingEventData'
calculated: '#/components/schemas/WebhookTrackingEventData'
internal: '#/components/schemas/WebhookTrackingEventData'
claim: '#/components/schemas/WebhookClaimEventData'
WebhookParcelData:
type: object
description: Parcel identifiers included in event deliveries.
required:
- parcel_id
- carrier_code
properties:
parcel_id:
type: integer
description: Sendcloud tracking parcel ID, used by event subscriptions. Not the Shipping API parcel ID. For that, use `source_id` when `source` is `shipping`.
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
source:
type:
- string
- 'null'
description: 'How the parcel entered Sendcloud tracking. `shipping`: the parcel was made with the Sendcloud panel, the Shipping API, or an integration. `external_parcel`: the parcel was registered with the Parcel Tracking API (Create an external parcel for tracking) or came from order sync. `support`: the parcel was made by Sendcloud support automation. `null` when the source is not known.'
example: shipping
enum:
- shipping
- external_parcel
- support
- null
source_id:
type:
- string
- 'null'
description: 'Parcel ID in its source system. When `source` is `shipping`, this is the Shipping API parcel ID. When `source` is `external_parcel`, this is the ID you sent (for order sync, an ID generated from the order). Not unique: a carrier can reuse a tracking number for another parcel. `null` when the source is not known.'
example: '412345678'
WebhookTrackingEventData:
type: object
title: Tracking Event
description: Parcel tracking event data for carrier, calculated and internal events. Does not apply to claim events — see `Claim Event` for those.
required:
- event_type
- timestamp
- phase
- exception
- status_type
- sub_status
properties:
id:
type:
- integer
- 'null'
description: Sendcloud ID of the carrier event. It stays the same when Sendcloud sends the event again, and the data can change. Replace the earlier copy. `null` for internal and calculated events.
example: 734512001
event_type:
type: string
description: Always one of the tracking event types for this shape. `internal` events come from Sendcloud, not from the carrier, and can arrive before `parcel.created`.
example: carrier
enum:
- carrier
- calculated
- internal
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
WebhookClaimEventData:
type: object
title: Claim Event
description: Support Automation ticket investigation data for claim events. Does not share fields with `Tracking Event` beyond `event_type` and `timestamp` — `phase` and `sub_status` here are different enums than on a tracking event.
required:
- event_type
- timestamp
- phase
- sub_status
- category
- ticket_id
- claim_event_id
properties:
event_type:
type: string
description: Always `claim` for this shape.
example: claim
enum:
- claim
timestamp:
type: string
format: date-time
description: ISO 8601 timestamp of when the event occurred.
example: '2026-01-17T09:00:00Z'
phase:
$ref: '#/components/schemas/support-investigation-phase'
sub_status:
$ref: '#/components/schemas/support-investigation-sub-status'
category:
$ref: '#/components/schemas/support-investigation-category'
ticket_id:
type: integer
description: Support Automation ticket identifier.
example: 987654
claim_event_id:
type: integer
description: Sendcloud claim event identifier.
example: 555111
refund_price:
oneOf:
- $ref: '#/components/schemas/WebhookParcelPrice'
- type: 'null'
description: Refund amount associated with the ticket, in its original currency, if any.
refund_price_eur:
oneOf:
- $ref: '#/components/schemas/WebhookParcelPrice'
- type: 'null'
description: Refund amount associated with the ticket, converted to euro, if any.
request_id:
type:
- integer
- 'null'
description: The id of the status update. Use this in the Support Public API to upload required files.
example: null
attachment_type:
type:
- string
- 'null'
description: The requested type of attachment for the ticket, if any file is requested.
example: null
title:
type:
- string
- 'null'
description: Human readable title associated with the ticket's update.
example: null
message:
type:
- string
- 'null'
description: Human readable message associated with the ticket's update.
example: null
resolution:
oneOf:
- $ref: '#/components/schemas/support-investigation-resolution'
- type: 'null'
description: Reason the investigation was solved. Only present on solved statuses; `null` otherwise.
origin:
oneOf:
- $ref: '#/components/schemas/support-investigation-origin'
- type: 'null'
description: Who or what created the investigation. Corresponds to the "Created by" field in the Sendcloud panel. `ava` means it was created by automation.
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
ParcelCreatedPayload:
type: object
description: Event payload delivered to your endpoint when a parcel is created.
required:
- event_type
- data
properties:
event_type:
type: string
description: The event type identifier.
example: parcel.created
enum:
- parcel.created
data:
$ref: '#/components/schemas/WebhookParcelCreatedData'
WebhookParcelCreatedData:
type: object
description: |-
The parcel as it was created. All keys below are always present in the delivered payload; keys that are not applicable are delivered as `null`.
Decimal amounts (weights, dimensions and prices) are delivered as strings to avoid rounding differences.
required:
- id
- created_at
- updated_at
- organization_id
- ship_with
- tracking_numbers
- details
- from_address
- to_address
- parcel_items
properties:
id:
type: integer
description: Sendcloud tracking parcel ID, used by event subscriptions. Not the Shipping API parcel ID. For that, use `source_id` when `source` is `shipping`.
example: 12345678
source:
type: string
description: 'How the parcel entered Sendcloud tracking. `shipping`: the parcel was made with the Sendcloud panel, the Shipping API, or an integration. `external_parcel`: the parcel was registered with the Parcel Tracking API (Create an external parcel for tracking) or came from order sync. `support`: the parcel was made by Sendcloud support automation.'
example: shipping
enum:
- shipping
- external_parcel
- support
source_id:
type: string
description: 'Parcel ID in its source system. When `source` is `shipping`, this is the Shipping API parcel ID. When `source` is `external_parcel`, this is the ID you sent (for order sync, an ID generated from the order). Not unique: a carrier can reuse a tracking number for another parcel.'
example: '412345678'
created_at:
type: string
format: date-time
description: ISO 8601 timestamp of when the parcel was created.
example: '2026-01-15T09:58:12.482913Z'
updated_at:
type: string
format: date-time
description: ISO 8601 timestamp of when the parcel was last updated.
example: '2026-01-15T09:58:12.482913Z'
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'
organization_id:
type: integer
description: Identifier of the organization that owns the parcel.
example: 87654
ship_with:
$ref: '#/components/schemas/WebhookParcelShipWith'
tracking_numbers:
type: array
description: Carrier tracking numbers for the parcel. A single entry is delivered; its `tracking_number` is `null` until the carrier issues one.
items:
$ref: '#/components/schemas/WebhookParcelTrackingNumber'
details:
$ref: '#/components/schemas/WebhookParcelCreatedDetails'
order:
oneOf:
- $ref: '#/components/schemas/WebhookParcelOrder'
- type: 'null'
description: Order the parcel was created for, or `null` when the parcel is not linked to an order.
from_address:
$ref: '#/components/schemas/address'
description: Sender address of the parcel.
to_address:
$ref: '#/components/schemas/address'
description: Recipient address of the parcel.
parcel_items:
type: array
description: Items on the parcel. Empty when the parcel was created without item data.
items:
$ref: '#/components/schemas/WebhookParcelCreatedItem'
WebhookParcelShipWith:
type: object
description: Shipping option the parcel was created with.
required:
- type
- properties
properties:
type:
type: string
description: How the shipping option is referenced. Always `shipping_option_code` for this event.
example: shipping_option_code
enum:
- shipping_option_code
properties:
type: object
description: Details of the selected shipping option.
properties:
shipping_option_code:
type:
- string
- 'null'
description: Code of the shipping option the parcel is shipped with.
example: dpd:standard
contract_id:
type:
- integer
- 'null'
description: Identifier of the carrier contract used for the parcel.
example: 517
WebhookParcelTrackingNumber:
type: object
description: Carrier tracking number issued for the parcel.
required:
- carrier_code
properties:
carrier_code:
type: string
description: Short carrier code (e.g. `dpd`, `dhl`, `postnl`).
example: dpd
tracking_number:
type:
- string
- 'null'
description: Carrier-issued tracking number.
example: 3SYZXG132912330
tracking_identifier:
type:
- string
- 'null'
description: Carrier tracking identifier, for carriers that track on a separate reference.
example: 3SYZXG132912330
tracking_url:
type:
- string
- 'null'
description: Tracking page for the parcel.
example: https://tracking.sendcloud.sc/forward?carrier=dpd&code=3SYZXG132912330
WebhookParcelCreatedDetails:
type: object
description: Physical and integration attributes of the parcel.
required:
- is_return
- dimensions
- weight
properties:
is_return:
type: boolean
description: True when the parcel is a return.
example: false
brand_id:
type:
- integer
- 'null'
description: Sendcloud brand identifier.
example: 1234
integration_id:
type:
- integer
- 'null'
description: Identifier of the integration the parcel originates from.
example: 5678
external_reference:
type:
- string
- 'null'
description: External reference supplied for the parcel.
example: WMS-2026-000123
dimensions:
$ref: '#/components/schemas/str-dimensions'
description: Parcel dimensions. The object is always present; its values are `null` when no dimensions were supplied.
weight:
$ref: '#/components/schemas/str-weight'
description: Parcel weight. The object is always present; its values are `null` when no weight was supplied.
WebhookParcelOrder:
type: object
description: Order the parcel was created for.
required:
- total_price
properties:
order_number:
type:
- string
- 'null'
description: Order number from the shop system.
example: ORDER-12345
ordered_at:
type:
- string
- 'null'
format: date-time
description: ISO 8601 timestamp of when the order was placed.
example: '2026-01-14T16:42:03Z'
total_price:
$ref: '#/components/schemas/WebhookParcelPrice'
description: Total order value.
WebhookParcelPrice:
type: object
description: Monetary amount in the specified currency. The amount is delivered as a decimal string.
properties:
value:
type:
- string
- 'null'
description: Amount as a decimal string.
example: '54.90'
currency:
type:
- string
- 'null'
description: ISO 4217 currency code.
example: EUR
WebhookParcelCreatedItem:
type: object
description: |-
A single item on the parcel.
This object follows the shared Sendcloud order item model, so it also carries keys that `parcel.created` never fills. Those are documented below and are always delivered as `null`.
required:
- measurement
properties:
item_id:
type:
- string
- 'null'
description: Item identifier in the shop system.
example: '5552'
name:
type:
- string
- 'null'
description: Product name. Always `null` for this event.
example: null
description:
type:
- string
- 'null'
description: Product description.
example: T-Shirt XL
product_id:
type:
- string
- 'null'
description: Product identifier in the shop system.
example: '19284'
variant_id:
type:
- string
- 'null'
description: Product variant identifier in the shop system.
example: 19284-XL
image_url:
type:
- string
- 'null'
description: Product image URL. Always `null` for this event.
example: null
measurement:
$ref: '#/components/schemas/WebhookParcelItemMeasurement'
quantity:
type:
- integer
- 'null'
description: Number of this item on the parcel.
example: 2
sku:
type:
- string
- 'null'
description: Stock keeping unit of the product.
example: TS1234
hs_code:
type:
- string
- 'null'
description: Harmonized System code used for customs.
example: '620520'
ean:
type:
- string
- 'null'
description: EAN-13 article number. Always `null` for this event.
example: null
properties:
type:
- object
- 'null'
description: Custom product properties. Always `null` for this event.
example: null
country_of_origin:
type:
- string
- 'null'
description: ISO 3166-1 alpha-2 code of the country where the product was produced or assembled.
example: NL
total_price:
type:
- object
- 'null'
description: Total price of the item line. Always `null` for this event; use `unit_price` and `quantity` instead.
example: null
unit_price:
oneOf:
- $ref: '#/components/schemas/WebhookParcelPrice'
- type: 'null'
description: Price of a single unit of this item.
delivery_dates:
type:
- object
- 'null'
description: Requested delivery dates. Always `null` for this event.
example: null
mid_code:
type:
- string
- 'null'
description: Manufacturer identification code used for customs. Always `null` for this event.
example: null
material_content:
type:
- string
- 'null'
description: Material composition of the product. Always `null` for this event.
example: null
intended_use:
type:
- string
- 'null'
description: Intended use of the product, used for customs. Always `null` for this event.
example: null
manufacturer_product_id:
type:
- string
- 'null'
description: Manufacturer product identifier. Always `null` for this event.
example: null
manufacturer_product_id_std:
type:
- string
- 'null'
description: Standardized manufacturer product identifier. Always `null` for this event.
example: null
dangerous_goods:
type:
- object
- 'null'
description: Hazardous materials information. Always `null` for this event.
example: null
WebhookParcelItemMeasurement:
type: object
description: Measurement of a single item on the parcel.
properties:
dimension:
type:
- object
- 'null'
description: Item dimensions. Always `null` for this event.
example: null
weight:
$ref: '#/components/schemas/str-weight'
description: Weight of a single item. Its values are `null` when no item weight was supplied.
volume:
type:
- object
- 'null'
description: Item volume. Always `null` for this event.
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. Send at least one field.
type: object
properties:
type:
type: string
description: The type of connection. Required when you send `configuration`.
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-phase:
type: string
title: Parcel Event Phase
description: Current delivery phase of a carrier, calculated or internal tracking event. Support Automation claim events use a separate set of phase values; see `Support Investigation Phase`.
enum:
- accepted
- announced
- announcing
- attempted
- cancelled
- customs
- delivered
- delivery_forced
- dropped
- in_delivery
- in_transit
- labelled
- no_label
- none
- 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 of a carrier/calculated tracking event. Support Automation claim events use a separate set of sub-status values; see `Support Investigation Sub Status`.
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
- packaging
- parcel_found
- partly
- passed
- payment
- postal_box
- prohibited_item
- pup
- pup_closed
- receiver
- rejected
- requested
- resolved
- safeplace
- sender
- shop
- signature
- traffic
- undeliverable
- unknown
- unknown_receiver
- updated
- weather_conditions
- '1'
- '2'
- '3'
example: none
support-investigation-phase:
type: string
title: Support Investigation Phase
description: Current stage of a Support Automation ticket investigation. This list is not exhaustive and may be extended with new values in the future. Integrations should be able to handle values they do not recognize.
enum:
- open
- in_progress
- action_required
- solved_by_automation_stage
- manually_solved_stage
- unknown
example: open
support-investigation-sub-status:
type: string
title: Support Investigation Sub Status
description: Additional granularity within the current investigation phase. This list is not exhaustive and may be extended with new values in the future. Integrations should be able to handle values they do not recognize.
enum:
- none
- action_required
- customer_documents_requested
- customer_reminder_sent
- delivery_confirmation_requested
- smart_refund_available
- waiting_for_customer
- escalated_ava
- processing
- pending
- carrier_reminder_sent
- communicated_to_carrier
- delayed
- hold
- smart_refund_update
- new_scan_received
- delivered_scan_received
- carrier_update_received
- waiting_for_carrier
- waiting_for_scan
- documents_forwarded_to_carrier
- delivery_confirmation_rejected
- escalated
- customer_escalation_requested
- claim_paid
- solved
- manually_solved
- closed
- solved_by_automation
- unknown
example: customer_documents_requested
support-investigation-category:
type: string
title: Support Investigation Category
description: Category of the underlying investigation ticket. This list is not exhaustive and may be extended with new values in the future. Integrations should be able to handle values they do not recognize.
enum:
- address_change
- damaged
- delayed
- delivered_not_received
- exception_report
- late_delivery
- lost
- other_shipping
- unjust_return
example: lost
support-investigation-resolution:
type: string
title: Support Investigation Resolution
description: Reason the investigation was solved. Only present on solved statuses. This list is not exhaustive and may be extended with new values in the future. Integrations should be able to handle values they do not recognize.
enum:
- claim_closed_in_carrier_portal
- claim_approved
- claim_declined
- delivered
- returned
- solved_merchant
- address_change_confirmed
- address_change_declined
- address_change_requested
- impossible_to_open_claim
- impossible_to_upload_documents
example: claim_approved
support-investigation-origin:
type: string
title: Support Investigation Origin
description: Who or what created the investigation. This corresponds to the "Created by" field in the Sendcloud panel. The value `ava` means the investigation was created by automation. This list is not exhaustive and may be extended with new values in the future. Integrations should be able to handle values they do not recognize.
enum:
- ava
- portal_import
- panel
- public
- csv_import
- external_event
example: public
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
address:
title: Address Object
type: object
description: Sendcloud Address object
properties:
name:
type: string
example: John Doe
description: Name of the person associated with the address
minLength: 1
company_name:
type: string
example: Sendcloud
description: Name of the company associated with the address
address_line_1:
type: string
example: Stadhuisplein
description: First line of the address
house_number:
type: string
example: '50'
description: House number of the address
address_line_2:
type: string
description: Additional address information, e.g. 2nd level
example: Apartment 17B
postal_code:
type: string
example: 1013 AB
description: Zip code of the address
minLength: 1
city:
type: string
example: Eindhoven
description: City of the address
minLength: 1
po_box:
type:
- string
- 'null'
description: Code required in case of PO Box or post locker delivery
state_province_code:
type: string
example: IT-RM
description: The character state code of the customer represented as ISO 3166-2 code. This field is required for certain countries. See [international shipping](/docs/shipments/international-shipping#required-fields-for-international-shipments) for details.
country_code:
type: string
example: NL
description: The country code of the customer represented as ISO 3166-1 alpha-2
minLength: 1
email:
type: string
format: email
example: johndoe@gmail.com
description: Email address of the person associated with the address
phone_number:
type: string
example: '+319881729999'
description: Phone number of the person associated with the address
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:
read:analytics: View your shipping analytics
read:audit-log: View your account's audit log
read:brand: View your brands
write:brand: Manage your brands
write:carrier: Configure carriers and contracts
read:checkout: View your dynamic checkout configurations and templates
read:event-subscription: View your event subscriptions
write:event-subscription: Create and manage your event subscriptions
read:integration: View your integrations
write:integration: Connect and manage integrations
read:invoice: View your invoices
read:notification: View your notifications
write:notification: Manage your notifications
read:operational-settings: View your warehouses, shipping lanes, and other operational settings
write:operational-settings: Manage your warehouses, shipping lanes, and other operational settings
read:order: View your orders
write:order: Import and process your orders
read:organization: View organization settings
write:organization: Change organization settings
read:parcel: View your shipments and their tracking status
write:parcel: Create, announce, and cancel shipments
read:pickup: View carrier pickups and the options available for scheduling them
write:pickup: Schedule and manage carrier pickups
read:price: View shipping prices
write:product: Manage your product catalog
read:return: View your returns
write:return: Create and manage returns
read:return-settings: View your return settings
write:return-settings: Configure your return settings
read:service-point: View carrier service points
read:shipping-method: View shipping methods, products and prices
read:shipping-rule: View your shipping rules
write:shipping-rule: Create and manage shipping rules
read:support-ticket: View your support tickets
write:support-ticket: Manage your support tickets
read:tracking-message: View your tracking notifications
write:tracking-message: Manage your tracking notifications
read:tracking-page: View your tracking page
write:tracking-page: Customize your tracking page
read:user: Read your basic account information