Orders

Orders

Send us orders, change them, and follow them through to delivery. You only ever see your own orders, and you find each one by your own reference.

The endpoints are also in the OpenAPI document, for generating a client.

References

Every order needs a reference of your own, such as your order number: letters, digits, ., _ and -, up to 64 characters. Use each reference once. Sending a reference again gets 409, so it’s safe to retry creating an order (see Errors).

Changing an order

You can change an order while its status is Received, before we start making it. Send the whole order again to PUT /partner/v1/orders/{reference}: it replaces the purchaser, recipient, delivery, message and items, so include every field, not only the ones that changed. The reference can’t be changed.

Once we’ve started an order you get 409. Contact us if it still needs to change.

Statuses

Status Meaning
Received We have the order and haven’t started it.
InProgress It’s being made.
Packed It’s made and waiting for the courier.
Dispatched It’s with the courier. shipments has the tracking numbers.
Delivered It’s been delivered.
DeliveryFailed The courier couldn’t deliver it, and will usually try again.
Returned It came back to us.
OnHold We’ve paused it, and will be in touch.
Cancelled It’s been cancelled.

We may add statuses later, so treat one you don’t recognise as “in progress” rather than failing.

How an order usually moves between them:

flowchart TD subgraph before [Before dispatch] Received --> InProgress --> Packed end before --> Dispatched Dispatched --> Delivered Dispatched --> DeliveryFailed DeliveryFailed -->|tried again| Dispatched DeliveryFailed --> Returned Dispatched --> Returned before --> OnHold OnHold -->|resumed| before before --> Cancelled OnHold --> Cancelled

An order on hold goes back to where it was when we resume it. You see the status an order has when you look, so it can seem to skip statuses: for example, straight from Received to Dispatched.

Endpoints

GET /partner/v1/orders - List orders

GET /partner/v1/orders

List orders

Your orders, newest first. Pages are cursor-based: pass the previous page’s nextCursor as cursor to get the next page; nextCursor is null on the last page.

Parameters
NameInTypeDescription / Example
deliveryDateFrom query string:date
Description

Only orders for delivery on or after this date.
deliveryDateTo query string:date
Description

Only orders for delivery on or before this date.
cursor query string
Description

The previous page’s nextCursor. Leave it out for the first page.
pageSize query integer:int32
Description

Orders per page, 1 to 100.
Responses
StatusDescription
200

A page of orders.


OrderPage
200 body

application/json

FieldTypeDescription / Example
items array[Order]
Show fields
FieldTypeDescription / Example
reference string | null
Description

Your reference for the order.
status OrderStatus
Description

Where an order has got to. Received: we have the order and haven’t started it. InProgress: it’s being made. Packed: it’s made and waiting for the courier. Dispatched: it’s with the courier. Delivered. DeliveryFailed: the courier couldn’t deliver it, and will usually try again. Returned: it came back to us. OnHold: we’ve paused it, and will be in touch. Cancelled.
receivedAt string:date-time | null
Description

When we received the order (UTC).
purchaser Purchaser
Show fields
FieldTypeDescription / Example
name * string
minLength: 1maxLength: 100
Description

Their full name.

Example
Siobhán Murphy
email * string:email
minLength: 1maxLength: 254
Description

Their email address.

Example
siobhan@example.com
Description

The person who placed the order.
recipient Recipient
Show fields
FieldTypeDescription / Example
name * string
minLength: 1maxLength: 100
Description

Their full name.

Example
Mary Murphy
telephone * string
minLength: 1maxLength: 30
Description

A telephone number the courier can call them on.

Example
+353 87 123 4567
address * Address
Show fields
FieldTypeDescription / Example
line1 * string
minLength: 1maxLength: 100
Description

The first line: house number or name, and street.

Example
12 Main Street
line2 string | null
maxLength: 100
Description

The second line, if there is one.

Example
Rathmines
city string | null
maxLength: 60
Description

The town or city.

Example
Dublin 6
county string | null
maxLength: 60
Description

The county.

Example
Dublin
postcode string | null
maxLength: 20
Description

The postcode (Eircode in Ireland).

Example
D06 A1B2
country * string
minLength: 1maxLength: 60
Description

The country.

Example
Ireland
Description

A postal address.
Description

The person the order is for, and where it’s going.
delivery Delivery
Show fields
FieldTypeDescription / Example
date * string:date
Description

The delivery date: today or later.

Example
2026-11-14
earliestTime string | null
pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
Description

The start of the delivery window, in 24-hour time (Irish time). Leave it out for any time.

Example
09:00
latestTime string | null
pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
Description

The end of the delivery window, in 24-hour time (Irish time). Leave it out for any time.

Example
13:00
Description

When the order is to be delivered.
message string | null
Description

The message for the card.
items array[OrderItem]
Show fields
FieldTypeDescription / Example
sku * string
minLength: 1maxLength: 64
Description

Your product code.

Example
BQT-ROSE-12
name * string
minLength: 1maxLength: 255
Description

The product’s name.

Example
A dozen red roses
quantity integer:int32
minimum: 1maximum: 100
Description

How many: 1 to 100.

Example
1
unitPrice * number:double
minimum: 0maximum: 100000
Description

The price of one, in euro.

Example
49.99
Description

What’s in the order.
shipments array[Shipment]
Show fields
FieldTypeDescription / Example
carrier string | null
Description

The courier, if known, such as DPD.
trackingNumber string | null
Description

The courier’s tracking number.
Description

The order’s parcels with the courier, once it’s dispatched: empty until then.
Description

This page’s orders, newest first.
nextCursor string | null
Description

Pass as cursor to get the next page; null on the last page.
400

A filter isn’t valid, such as delivery dates the wrong way round.


ValidationProblemDetails
400 body

application/json

FieldTypeDescription / Example
type string | null
title string | null
status integer:int32 | null
detail string | null
instance string | null
errors map[string, array[string]]

Additional properties: any

401

The access token is missing, invalid or expired.


ProblemDetails
401 body

application/json

FieldTypeDescription / Example
type string | null
title string | null
status integer:int32 | null
detail string | null
instance string | null

Additional properties: any

403

The token isn’t for a partner application we’ve set up.


ProblemDetails
403 body

application/json

FieldTypeDescription / Example
type string | null
title string | null
status integer:int32 | null
detail string | null
instance string | null

Additional properties: any

POST /partner/v1/orders - Create an order

POST /partner/v1/orders

Create an order

Each order needs a reference of your own that you haven’t used before. If you send a reference again, for example retrying after a timeout, you get 409 and the order isn’t created twice: get the order by its reference to see it.

Request Body

application/json

FieldTypeDescription / Example
purchaser * Purchaser
Show fields
FieldTypeDescription / Example
name * string
minLength: 1maxLength: 100
Description

Their full name.

Example
Siobhán Murphy
email * string:email
minLength: 1maxLength: 254
Description

Their email address.

Example
siobhan@example.com
Description

The person who placed the order.
recipient * Recipient
Show fields
FieldTypeDescription / Example
name * string
minLength: 1maxLength: 100
Description

Their full name.

Example
Mary Murphy
telephone * string
minLength: 1maxLength: 30
Description

A telephone number the courier can call them on.

Example
+353 87 123 4567
address * Address
Show fields
FieldTypeDescription / Example
line1 * string
minLength: 1maxLength: 100
Description

The first line: house number or name, and street.

Example
12 Main Street
line2 string | null
maxLength: 100
Description

The second line, if there is one.

Example
Rathmines
city string | null
maxLength: 60
Description

The town or city.

Example
Dublin 6
county string | null
maxLength: 60
Description

The county.

Example
Dublin
postcode string | null
maxLength: 20
Description

The postcode (Eircode in Ireland).

Example
D06 A1B2
country * string
minLength: 1maxLength: 60
Description

The country.

Example
Ireland
Description

A postal address.
Description

The person the order is for, and where it’s going.
delivery * Delivery
Show fields
FieldTypeDescription / Example
date * string:date
Description

The delivery date: today or later.

Example
2026-11-14
earliestTime string | null
pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
Description

The start of the delivery window, in 24-hour time (Irish time). Leave it out for any time.

Example
09:00
latestTime string | null
pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
Description

The end of the delivery window, in 24-hour time (Irish time). Leave it out for any time.

Example
13:00
Description

When the order is to be delivered.
message string | null
maxLength: 1000
Description

The message for the card. Leave it out for no card message.

Example
Happy birthday Mam! Love, Siobhán
items * array[OrderItem]
minItems: 1maxItems: 50
Show fields
FieldTypeDescription / Example
sku * string
minLength: 1maxLength: 64
Description

Your product code.

Example
BQT-ROSE-12
name * string
minLength: 1maxLength: 255
Description

The product’s name.

Example
A dozen red roses
quantity integer:int32
minimum: 1maximum: 100
Description

How many: 1 to 100.

Example
1
unitPrice * number:double
minimum: 0maximum: 100000
Description

The price of one, in euro.

Example
49.99
Description

What’s in the order: 1 to 50 lines.
reference * string
minLength: 1maxLength: 64pattern: ^[A-Za-z0-9][A-Za-z0-9._-]*$
Description

Your reference for the order, unique among your orders: letters, digits, ., _ and -, up to 64 characters. You use it to look the order up.

Example
WEB-100234
Responses
StatusDescription
201

The order was created. The Location header is its URL.


Order
201 body

application/json

FieldTypeDescription / Example
reference string | null
Description

Your reference for the order.
status OrderStatus
Description

Where an order has got to. Received: we have the order and haven’t started it. InProgress: it’s being made. Packed: it’s made and waiting for the courier. Dispatched: it’s with the courier. Delivered. DeliveryFailed: the courier couldn’t deliver it, and will usually try again. Returned: it came back to us. OnHold: we’ve paused it, and will be in touch. Cancelled.
receivedAt string:date-time | null
Description

When we received the order (UTC).
purchaser Purchaser
Show fields
FieldTypeDescription / Example
name * string
minLength: 1maxLength: 100
Description

Their full name.

Example
Siobhán Murphy
email * string:email
minLength: 1maxLength: 254
Description

Their email address.

Example
siobhan@example.com
Description

The person who placed the order.
recipient Recipient
Show fields
FieldTypeDescription / Example
name * string
minLength: 1maxLength: 100
Description

Their full name.

Example
Mary Murphy
telephone * string
minLength: 1maxLength: 30
Description

A telephone number the courier can call them on.

Example
+353 87 123 4567
address * Address
Show fields
FieldTypeDescription / Example
line1 * string
minLength: 1maxLength: 100
Description

The first line: house number or name, and street.

Example
12 Main Street
line2 string | null
maxLength: 100
Description

The second line, if there is one.

Example
Rathmines
city string | null
maxLength: 60
Description

The town or city.

Example
Dublin 6
county string | null
maxLength: 60
Description

The county.

Example
Dublin
postcode string | null
maxLength: 20
Description

The postcode (Eircode in Ireland).

Example
D06 A1B2
country * string
minLength: 1maxLength: 60
Description

The country.

Example
Ireland
Description

A postal address.
Description

The person the order is for, and where it’s going.
delivery Delivery
Show fields
FieldTypeDescription / Example
date * string:date
Description

The delivery date: today or later.

Example
2026-11-14
earliestTime string | null
pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
Description

The start of the delivery window, in 24-hour time (Irish time). Leave it out for any time.

Example
09:00
latestTime string | null
pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
Description

The end of the delivery window, in 24-hour time (Irish time). Leave it out for any time.

Example
13:00
Description

When the order is to be delivered.
message string | null
Description

The message for the card.
items array[OrderItem]
Show fields
FieldTypeDescription / Example
sku * string
minLength: 1maxLength: 64
Description

Your product code.

Example
BQT-ROSE-12
name * string
minLength: 1maxLength: 255
Description

The product’s name.

Example
A dozen red roses
quantity integer:int32
minimum: 1maximum: 100
Description

How many: 1 to 100.

Example
1
unitPrice * number:double
minimum: 0maximum: 100000
Description

The price of one, in euro.

Example
49.99
Description

What’s in the order.
shipments array[Shipment]
Show fields
FieldTypeDescription / Example
carrier string | null
Description

The courier, if known, such as DPD.
trackingNumber string | null
Description

The courier’s tracking number.
Description

The order’s parcels with the courier, once it’s dispatched: empty until then.
400

The order isn’t valid: each problem is listed under errors.


ValidationProblemDetails
400 body

application/json

FieldTypeDescription / Example
type string | null
title string | null
status integer:int32 | null
detail string | null
instance string | null
errors map[string, array[string]]

Additional properties: any

401

The access token is missing, invalid or expired.


ProblemDetails
401 body

application/json

FieldTypeDescription / Example
type string | null
title string | null
status integer:int32 | null
detail string | null
instance string | null

Additional properties: any

403

The token isn’t for a partner application we’ve set up.


ProblemDetails
403 body

application/json

FieldTypeDescription / Example
type string | null
title string | null
status integer:int32 | null
detail string | null
instance string | null

Additional properties: any

409

You’ve already sent an order with this reference.


ProblemDetails
409 body

application/json

FieldTypeDescription / Example
type string | null
title string | null
status integer:int32 | null
detail string | null
instance string | null

Additional properties: any

GET /partner/v1/orders/{reference} - Get an order

GET /partner/v1/orders/{reference}

Get an order

Parameters
NameInTypeDescription / Example
reference * path string
Description

Your reference for the order.
Responses
StatusDescription
200

The order and where it’s got to.


Order
200 body

application/json

FieldTypeDescription / Example
reference string | null
Description

Your reference for the order.
status OrderStatus
Description

Where an order has got to. Received: we have the order and haven’t started it. InProgress: it’s being made. Packed: it’s made and waiting for the courier. Dispatched: it’s with the courier. Delivered. DeliveryFailed: the courier couldn’t deliver it, and will usually try again. Returned: it came back to us. OnHold: we’ve paused it, and will be in touch. Cancelled.
receivedAt string:date-time | null
Description

When we received the order (UTC).
purchaser Purchaser
Show fields
FieldTypeDescription / Example
name * string
minLength: 1maxLength: 100
Description

Their full name.

Example
Siobhán Murphy
email * string:email
minLength: 1maxLength: 254
Description

Their email address.

Example
siobhan@example.com
Description

The person who placed the order.
recipient Recipient
Show fields
FieldTypeDescription / Example
name * string
minLength: 1maxLength: 100
Description

Their full name.

Example
Mary Murphy
telephone * string
minLength: 1maxLength: 30
Description

A telephone number the courier can call them on.

Example
+353 87 123 4567
address * Address
Show fields
FieldTypeDescription / Example
line1 * string
minLength: 1maxLength: 100
Description

The first line: house number or name, and street.

Example
12 Main Street
line2 string | null
maxLength: 100
Description

The second line, if there is one.

Example
Rathmines
city string | null
maxLength: 60
Description

The town or city.

Example
Dublin 6
county string | null
maxLength: 60
Description

The county.

Example
Dublin
postcode string | null
maxLength: 20
Description

The postcode (Eircode in Ireland).

Example
D06 A1B2
country * string
minLength: 1maxLength: 60
Description

The country.

Example
Ireland
Description

A postal address.
Description

The person the order is for, and where it’s going.
delivery Delivery
Show fields
FieldTypeDescription / Example
date * string:date
Description

The delivery date: today or later.

Example
2026-11-14
earliestTime string | null
pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
Description

The start of the delivery window, in 24-hour time (Irish time). Leave it out for any time.

Example
09:00
latestTime string | null
pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
Description

The end of the delivery window, in 24-hour time (Irish time). Leave it out for any time.

Example
13:00
Description

When the order is to be delivered.
message string | null
Description

The message for the card.
items array[OrderItem]
Show fields
FieldTypeDescription / Example
sku * string
minLength: 1maxLength: 64
Description

Your product code.

Example
BQT-ROSE-12
name * string
minLength: 1maxLength: 255
Description

The product’s name.

Example
A dozen red roses
quantity integer:int32
minimum: 1maximum: 100
Description

How many: 1 to 100.

Example
1
unitPrice * number:double
minimum: 0maximum: 100000
Description

The price of one, in euro.

Example
49.99
Description

What’s in the order.
shipments array[Shipment]
Show fields
FieldTypeDescription / Example
carrier string | null
Description

The courier, if known, such as DPD.
trackingNumber string | null
Description

The courier’s tracking number.
Description

The order’s parcels with the courier, once it’s dispatched: empty until then.
401

The access token is missing, invalid or expired.


ProblemDetails
401 body

application/json

FieldTypeDescription / Example
type string | null
title string | null
status integer:int32 | null
detail string | null
instance string | null

Additional properties: any

403

The token isn’t for a partner application we’ve set up.


ProblemDetails
403 body

application/json

FieldTypeDescription / Example
type string | null
title string | null
status integer:int32 | null
detail string | null
instance string | null

Additional properties: any

404

You haven’t sent an order with this reference.


ProblemDetails
404 body

application/json

FieldTypeDescription / Example
type string | null
title string | null
status integer:int32 | null
detail string | null
instance string | null

Additional properties: any

PUT /partner/v1/orders/{reference} - Update an order

PUT /partner/v1/orders/{reference}

Update an order

Replaces the order’s purchaser, recipient, delivery, message and items with the request: send every field, not only the ones that changed. The reference can’t be changed.

You can change an order until we start making it, while its status is Received. After that you get 409: contact us to change it.

Parameters
NameInTypeDescription / Example
reference * path string
Description

Your reference for the order.
Request Body

application/json

FieldTypeDescription / Example
purchaser * Purchaser
Show fields
FieldTypeDescription / Example
name * string
minLength: 1maxLength: 100
Description

Their full name.

Example
Siobhán Murphy
email * string:email
minLength: 1maxLength: 254
Description

Their email address.

Example
siobhan@example.com
Description

The person who placed the order.
recipient * Recipient
Show fields
FieldTypeDescription / Example
name * string
minLength: 1maxLength: 100
Description

Their full name.

Example
Mary Murphy
telephone * string
minLength: 1maxLength: 30
Description

A telephone number the courier can call them on.

Example
+353 87 123 4567
address * Address
Show fields
FieldTypeDescription / Example
line1 * string
minLength: 1maxLength: 100
Description

The first line: house number or name, and street.

Example
12 Main Street
line2 string | null
maxLength: 100
Description

The second line, if there is one.

Example
Rathmines
city string | null
maxLength: 60
Description

The town or city.

Example
Dublin 6
county string | null
maxLength: 60
Description

The county.

Example
Dublin
postcode string | null
maxLength: 20
Description

The postcode (Eircode in Ireland).

Example
D06 A1B2
country * string
minLength: 1maxLength: 60
Description

The country.

Example
Ireland
Description

A postal address.
Description

The person the order is for, and where it’s going.
delivery * Delivery
Show fields
FieldTypeDescription / Example
date * string:date
Description

The delivery date: today or later.

Example
2026-11-14
earliestTime string | null
pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
Description

The start of the delivery window, in 24-hour time (Irish time). Leave it out for any time.

Example
09:00
latestTime string | null
pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
Description

The end of the delivery window, in 24-hour time (Irish time). Leave it out for any time.

Example
13:00
Description

When the order is to be delivered.
message string | null
maxLength: 1000
Description

The message for the card. Leave it out for no card message.

Example
Happy birthday Mam! Love, Siobhán
items * array[OrderItem]
minItems: 1maxItems: 50
Show fields
FieldTypeDescription / Example
sku * string
minLength: 1maxLength: 64
Description

Your product code.

Example
BQT-ROSE-12
name * string
minLength: 1maxLength: 255
Description

The product’s name.

Example
A dozen red roses
quantity integer:int32
minimum: 1maximum: 100
Description

How many: 1 to 100.

Example
1
unitPrice * number:double
minimum: 0maximum: 100000
Description

The price of one, in euro.

Example
49.99
Description

What’s in the order: 1 to 50 lines.
Responses
StatusDescription
200

The order as it is now.


Order
200 body

application/json

FieldTypeDescription / Example
reference string | null
Description

Your reference for the order.
status OrderStatus
Description

Where an order has got to. Received: we have the order and haven’t started it. InProgress: it’s being made. Packed: it’s made and waiting for the courier. Dispatched: it’s with the courier. Delivered. DeliveryFailed: the courier couldn’t deliver it, and will usually try again. Returned: it came back to us. OnHold: we’ve paused it, and will be in touch. Cancelled.
receivedAt string:date-time | null
Description

When we received the order (UTC).
purchaser Purchaser
Show fields
FieldTypeDescription / Example
name * string
minLength: 1maxLength: 100
Description

Their full name.

Example
Siobhán Murphy
email * string:email
minLength: 1maxLength: 254
Description

Their email address.

Example
siobhan@example.com
Description

The person who placed the order.
recipient Recipient
Show fields
FieldTypeDescription / Example
name * string
minLength: 1maxLength: 100
Description

Their full name.

Example
Mary Murphy
telephone * string
minLength: 1maxLength: 30
Description

A telephone number the courier can call them on.

Example
+353 87 123 4567
address * Address
Show fields
FieldTypeDescription / Example
line1 * string
minLength: 1maxLength: 100
Description

The first line: house number or name, and street.

Example
12 Main Street
line2 string | null
maxLength: 100
Description

The second line, if there is one.

Example
Rathmines
city string | null
maxLength: 60
Description

The town or city.

Example
Dublin 6
county string | null
maxLength: 60
Description

The county.

Example
Dublin
postcode string | null
maxLength: 20
Description

The postcode (Eircode in Ireland).

Example
D06 A1B2
country * string
minLength: 1maxLength: 60
Description

The country.

Example
Ireland
Description

A postal address.
Description

The person the order is for, and where it’s going.
delivery Delivery
Show fields
FieldTypeDescription / Example
date * string:date
Description

The delivery date: today or later.

Example
2026-11-14
earliestTime string | null
pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
Description

The start of the delivery window, in 24-hour time (Irish time). Leave it out for any time.

Example
09:00
latestTime string | null
pattern: ^([01][0-9]|2[0-3]):[0-5][0-9]$
Description

The end of the delivery window, in 24-hour time (Irish time). Leave it out for any time.

Example
13:00
Description

When the order is to be delivered.
message string | null
Description

The message for the card.
items array[OrderItem]
Show fields
FieldTypeDescription / Example
sku * string
minLength: 1maxLength: 64
Description

Your product code.

Example
BQT-ROSE-12
name * string
minLength: 1maxLength: 255
Description

The product’s name.

Example
A dozen red roses
quantity integer:int32
minimum: 1maximum: 100
Description

How many: 1 to 100.

Example
1
unitPrice * number:double
minimum: 0maximum: 100000
Description

The price of one, in euro.

Example
49.99
Description

What’s in the order.
shipments array[Shipment]
Show fields
FieldTypeDescription / Example
carrier string | null
Description

The courier, if known, such as DPD.
trackingNumber string | null
Description

The courier’s tracking number.
Description

The order’s parcels with the courier, once it’s dispatched: empty until then.
400

The order isn’t valid: each problem is listed under errors.


ValidationProblemDetails
400 body

application/json

FieldTypeDescription / Example
type string | null
title string | null
status integer:int32 | null
detail string | null
instance string | null
errors map[string, array[string]]

Additional properties: any

401

The access token is missing, invalid or expired.


ProblemDetails
401 body

application/json

FieldTypeDescription / Example
type string | null
title string | null
status integer:int32 | null
detail string | null
instance string | null

Additional properties: any

403

The token isn’t for a partner application we’ve set up.


ProblemDetails
403 body

application/json

FieldTypeDescription / Example
type string | null
title string | null
status integer:int32 | null
detail string | null
instance string | null

Additional properties: any

404

You haven’t sent an order with this reference.


ProblemDetails
404 body

application/json

FieldTypeDescription / Example
type string | null
title string | null
status integer:int32 | null
detail string | null
instance string | null

Additional properties: any

409

We’ve started the order, so it can’t be changed; or it changed while you were updating it.


ProblemDetails
409 body

application/json

FieldTypeDescription / Example
type string | null
title string | null
status integer:int32 | null
detail string | null
instance string | null

Additional properties: any
Previous Webhooks Next Webhooks