Skip to main content
POST
Create order

Authorizations

api-key
string
header
required

Body

application/json
locationId
string
required

Pickup location the order is dispatched from.

Maximum string length: 20
Example:

"ABC123"

orderRef
string
required

Your own reference for the order. Keep it unique.

Maximum string length: 100
Example:

"PADE3JWEA"

deliveryName
string
required
Maximum string length: 100
Example:

"Jane Doe"

deliveryAddress
object
required
name
string
Example:

"iPod"

description
string
Maximum string length: 100
Example:

"ABC"

deliveryCompanyName
string

Company the parcel is delivered to. deliveryName is then printed as the contact person (t.a.v.).

Maximum string length: 100
Example:

"Acme B.V."

deliveryEmail
string<email>
deliveryPhone
string
Maximum string length: 30
Example:

"+31612345678"

deliveryNote
string
Maximum string length: 100
Example:

"Please leave the package at the door when I am not home."

isBusiness
boolean
Example:

false

height
number

Height of the collo (mm).

Required range: x <= 1000
Example:

120.5

length
number

Length of the collo (mm).

Required range: x <= 1000
Example:

200

width
number

Width of the collo (mm).

Required range: x <= 1000
Example:

75.5

weight
number

Weight of the collo (g).

Required range: x <= 20000
Example:

22.5

pudoId
string

Deliver to this pickup point. Use the pudoId of a point returned by GET /pickup-points. The order is created with the carrier that serves that point, and is rejected when no pickup point delivery is available for the address.

Maximum string length: 100
Example:

"9f83c1b0a4"

signature
boolean

Delivery requires a signature.

Example:

false

notAtNeighbour
boolean

Do not deliver to a neighbour.

Example:

false

mailbox
boolean
default:false

Deliver as a mailbox parcel. Optional, defaults to false. The order is rejected when no carrier offers mailbox delivery at the address.

Example:

false

orderBundleId
string

Attach this order to an existing delivery bundle. Omit it on the first order; the create response returns an orderBundle object whose bundleId you pass here on subsequent orders to group them as one multi-parcel shipment.

Maximum string length: 100
Example:

"VNN1UY7TMSY81P8Q4A2C7"

senderRef
string

Your own unique identifier for the brand you ship for. Decides which brand the order belongs to and is never shown to the shopper or carriers. Fulfilment accounts only; on other accounts it has no effect. Always send it with senderName to keep brands apart safely. See Multiple brands.

Maximum string length: 100
Example:

"5179823"

senderName
string

The brand shown to the shopper and carriers as the sender: on the label, the track and trace page, and in tracking emails. With senderRef, the first order for a new ref registers the brand under this name, and after that the registered name is shown. Omit it to use your company name.

Maximum string length: 100
Example:

"Nike"

returnAddress
object

Where returned parcels go, printed as the sender address on Sparqle labels and shown on the track and trace page. Used as sent, without address validation. Omit it to use the address of the pickup location.

Response

Order created

id
integer
Example:

1

orderId
string
Example:

"SPQ-10293"

orderRef
string
Example:

"PADE3JWEA"

status
enum<string>
Available options:
draft,
expected,
in_transit,
out_for_delivery,
awaiting_next_attempt,
at_pickup_point,
completed,
failed,
in_return_transit,
returned,
cancelled,
rejected,
address_not_found,
inactive,
missing,
lost,
error
Example:

"draft"

name
string
Example:

"iPod"

barcode
string
Example:

"3STBXX123456789"

pudoId
string

Pickup point this order is delivered to, when there is one.

Example:

"9f83c1b0a4"

trackingUrl
string
Example:

"https://tracking.sparqle.com/barcode/3STBXX123456789"

deliveryName
string
Example:

"Jane Doe"

deliveryCompanyName
string | null
Example:

"Acme B.V."

deliveryEmail
string
deliveryAddress
string
Example:

"Gustav Mahlerlaan 320, 1082 ME Amsterdam"

deliveryEta
string
Example:

"12:40 - 13:00"

deliveryEtaDate
string<date>
Example:

"2026-08-13"

deliveryDate
string
Example:

"2026-08-13"

locationId
integer
Example:

1

createdAt
string<date-time>
updatedAt
string<date-time>