curl --request POST \
--url https://api.smartsend.io/beta/teams/{teamUuid}/booking-batches \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"identifier": "batch-db-42",
"reference": "MORNING-2026-09-16",
"callback": {
"url": "https://merchant.example.com/smartsend/batches",
"events": [
"shipment.booked",
"shipment.failed",
"shipment.cancelled",
"shipment.voided",
"batch.updated",
"batch.completed",
"batch.stopped"
],
"signing_secret": "whsec_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="
}
}
'{
"data": {
"uuid": "55555555-5555-4555-8555-555555555555",
"state": "open",
"identifier": "batch-db-42",
"reference": "MORNING-2026-09-16",
"total_count": 0,
"pending_count": 0,
"processing_count": 0,
"booked_count": 0,
"failed_count": 0,
"cancelled_count": 0,
"completed_count": 0,
"progress": 0,
"created_at": "2026-09-16T10:00:00Z",
"updated_at": "2026-09-16T10:00:00Z",
"started_at": null,
"finished_at": null
}
}{
"message": "Unauthenticated."
}{
"message": "This action is unauthorized."
}{
"message": "A request with this Idempotency-Key is still being processed."
}{
"message": "The given data was invalid.",
"errors": {
"field_name": [
"This field is required."
]
}
}{
"message": "Too Many Attempts."
}{
"message": "Server Error"
}{
"message": "Service Unavailable"
}Create a booking batch
Creates an empty booking batch with an optional callback for progress updates.
curl --request POST \
--url https://api.smartsend.io/beta/teams/{teamUuid}/booking-batches \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"identifier": "batch-db-42",
"reference": "MORNING-2026-09-16",
"callback": {
"url": "https://merchant.example.com/smartsend/batches",
"events": [
"shipment.booked",
"shipment.failed",
"shipment.cancelled",
"shipment.voided",
"batch.updated",
"batch.completed",
"batch.stopped"
],
"signing_secret": "whsec_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="
}
}
'{
"data": {
"uuid": "55555555-5555-4555-8555-555555555555",
"state": "open",
"identifier": "batch-db-42",
"reference": "MORNING-2026-09-16",
"total_count": 0,
"pending_count": 0,
"processing_count": 0,
"booked_count": 0,
"failed_count": 0,
"cancelled_count": 0,
"completed_count": 0,
"progress": 0,
"created_at": "2026-09-16T10:00:00Z",
"updated_at": "2026-09-16T10:00:00Z",
"started_at": null,
"finished_at": null
}
}{
"message": "Unauthenticated."
}{
"message": "This action is unauthorized."
}{
"message": "A request with this Idempotency-Key is still being processed."
}{
"message": "The given data was invalid.",
"errors": {
"field_name": [
"This field is required."
]
}
}{
"message": "Too Many Attempts."
}{
"message": "Server Error"
}{
"message": "Service Unavailable"
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
Preferred language(s) for translatable content using BCP 47 language tags. Supports quality values (q-factors) for priority ordering. The API negotiates the best available language based on this header, the team's configured language, and available translations. If omitted, the team's default language is used.
"da-DK, da;q=0.9, en;q=0.8"
Optional client-supplied request identifier. When provided and matching the validation pattern, the value is echoed back in the Request-ID response header. Otherwise the server generates one. Use this to correlate requests between client and server when reporting issues.
1 - 64^[A-Za-z0-9._-]{1,64}$Optional, case-sensitive key for one intended action. Scope: team, HTTP method and canonical path. Completed actions are remembered in cache for 24 hours; cache loss, eviction or expiry may allow the action to execute again. Same key and payload reuses the stored outcome without repeating side effects; the resource representation is current. Changed payload: 422 with an Idempotency-Key entry in errors. Concurrent duplicate: 409 with Retry-After and Location when known. Without a key there is no deduplication. Use GET at Location after 202.
16 - 128^[A-Za-z0-9]{16,128}$Path Parameters
Team uuid. All resources are scoped to this team.
Body
Create an empty open batch. Team document/print defaults apply to each shipment at its acceptance.
Private integration reference.
Public batch reference.
Register a callback at batch creation. Omitted events defaults to shipment.booked, shipment.failed, shipment.cancelled, shipment.voided, batch.completed and batch.stopped. Callback configuration is immutable after creation.
Show child attributes
Show child attributes
Callbacks
POST{$request.body#/callback/url}updates
Body
- Option 1
- Option 2
Thin event envelope: stable id, event type, occurred_at, team_uuid and resource identifiers in data. Full payloads are not offered in this version. A future full-payload option must be explicitly selected; existing thin subscriptions retain their documented meaning.
Stable event UUID, also sent in webhook-id. Duplicate deliveries keep the same id.
Resource UUID.
When the business event occurred; distinct from the delivery-attempt timestamp.
shipment.booked, shipment.failed, shipment.cancelled, shipment.voided Show child attributes
Show child attributes
Response
Event durably accepted. Acknowledge with any 2xx within 10 seconds; a non-2xx response or timeout triggers retries with backoff for up to 24 hours.
Response
Open batch created.
Batch progress for one-at-a-time booking. total_count = pending_count + processing_count + completed_count. Post-booking cancellation/printing/tracking do not rewrite booking outcomes. Late booking corrections may adjust outcome counts without reopening a terminal batch.
Show child attributes
Show child attributes
Was this page helpful?