Create Return

Create a home return order once the postal code has been validated. The consumer's address is the sender in this flow — Instabee will pick up from their home and return the parcel to the merchant. After the order is created, the consumer will receive communication from Instabee and can book a pickup time that suits them.

API Endpoint

Endpoint	Method	Content-Type
`api.integration.instabee.com/orders` (production) · `sandbox-api.integration.instabee.com/orders` (sandbox)	PUT	application/json

Integration Levels

Merchants can send information at different levels depending on their workflow:

Minimum: Basic confirmation with essential sender details
Maximum: Complete order details with dimensions and product information

Key Benefits

Pickup Scheduling: Triggers pickup scheduling and route optimization
Label Generation: Provides shipping labels for the return parcels
Consumer Convenience: Enables home pickup for hassle-free returns
Status Updates: Updates tracking status for consumers and merchants

Integration Workflow

Validate Postal Code: Check if home return is available for the consumer's postal code
Create Return: Register the return order with this API
Label Download: Download shipping labels from the response
Consumer Books Pickup: The consumer receives communication from Instabee and selects a pickup time via the Instabee app

Next Steps

Initial Setup: Check the Authentication section for API setup
Validate Coverage: Use the Validate Postal Code endpoint first

Quick Links

Validate Postal Code - Check return availability for a postal code

Create Order API (Create Return)

The Create Return API is used to register a home return parcel. The consumer's address is provided as the sender, and the parcel will be picked up from there.

This endpoint should be called when:

A consumer has requested a home return pickup
You have the consumer's full address details

Request Body

Parameter	Type	Required	Description	Constraints	Enum	Comment
parcelPackingConfirmed	boolean	required	Confirm parcel is packed and ready for pickup	must be `true`		Order is created and confirmed in a single call
brand	string	optional	Define brand of the delivery options			`instabox` or `budbee`
product	string	required	Define the product of the delivery options	Must be one		`HOME_RETURN`
countryCode	string	required*	Sender (consumer) country code. Can be sent in query param	ISO 3166 alpha 2	DK, FI, NO, SE
availabilityToken	string	optional	Availability token from availability response
orderId	string	optional	Unique order reference for subsequent calls
parcelId	string	optional	Unique identifier/barcode for parcel	Auto-generated if omitted
sender	object	required	Consumer/sender information object — the pickup address
recipient	object	optional	Merchant/recipient information object
dispatch	object	optional	Dispatch readiness and warehouse
options	object	optional	Response options / language
deliveryInstructions	object	optional	Delivery instruction details
additionalServices	object	optional	Additional services
cart	object	optional	Parcel and/or product details

sender

Parameter	Type	Required	Description	Constraints	Enum	Comment
name	string	required	Consumer name
email	string	required	Consumer email address	Valid email format		Used for pickup notifications
phone	string	required	Consumer phone number	Box: Min 6 digits, Home delivery: Min 10 digits, Max 15 digits		Can be made optional with setting
ssn	string	optional	Social security number			For age verification services
street	string	required	Consumer street address
street2	string	optional	Additional address information			Floor, apartment, etc.
postalCode	string	required	Consumer postal code
city	string	required	Consumer city
countryCode	string	required	Sender (consumer) country code	ISO 3166 alpha 2	DK, FI, NO, SE
coordinates	object	optional	GPS coordinates			For precise location

sender.coordinates

Parameter	Type	Required	Description	Enum
lat	number	optional	Latitude
lon	number	optional	Longitude

recipient

Parameter	Type	Required	Description	Constraints	Enum	Comment
name	string	optional	Merchant/recipient name
email	string	optional	Recipient email address	Valid email format
phone	string	optional	Recipient phone number	Box: Min 6 digits, Home delivery: Min 10 digits, Max 15 digits
street	string	optional	Recipient street address
street2	string	optional	Additional recipient address info
postalCode	string	optional	Recipient postal code
city	string	optional	Recipient city
countryCode	string	optional	Recipient (merchant) country code	ISO 3166 alpha 2	BE, DE, DK, FI, NL, NO, PL, SE	DE and PL are merchant address countries only, not delivery markets
coordinates	object	optional	Recipient GPS coordinates

recipient.coordinates

Parameter	Type	Required	Description	Enum
lat	number	optional	Latitude
lon	number	optional	Longitude

dispatch

Parameter	Type	Required	Description	Constraints	Enum	Comment
readyToShip	string	optional	When parcel is ready for pickup	ISO-8601 datetime		Only one of readyToShip/readyToPack/outOfStock
readyToPack	string	optional	When packing process will start	ISO-8601 datetime		Instabee adds packing time to this
outOfStock	boolean	optional	Product is out of stock		`true`/`false`	Removes ETA from delivery options
packingTime	number	optional	Required packing time in minutes
collectionPointId	string	optional	Specific warehouse/pickup point			Configured by Instabee
returnPointId	string	optional	Return address point ID			For failed deliveries

options

Parameter	Type	Required	Description	Constraints	Enum	Comment
languageCode	string	optional	Language for customer communications	ISO 639-1	da, en, fi, nl, no, sv	Defaults to the main language of the countryCode
localEtas	boolean	optional	Return local delivery terms		`true`/`false`	Different local terms for delivery promise
estimatedParcelType	boolean	optional	Return estimated parcel size		`true`/`false`	Calculated based on cart contents

deliveryInstructions

Parameter	Type	Required	Description	Enum	Comment
notifyBy	string	optional	How to notify consumer	ring_doorbell, knock_on_door
doorCode	string	optional	Door or building access code
message	string	optional	Special pickup instructions		Free text message
intercom	boolean	optional	Use intercom if available	`true`/`false`

additionalServices

Parameter	Type	Required	Description	Constraints	Enum	Comment
identification	object	optional	Identity verification requirements
leaveOutsideDoor	boolean	optional	Allow leaving the parcel outside the door		`true`/`false`	Default is true
leaveWithNeighbour	boolean	optional	Allow leaving the parcel with a neighbour		`true`/`false`	Default is false
numberOfMissRetries	number	optional	Number of pickup retry attempts	Min: 1, Max: 5		null = default. Extra cost applies

additionalServices.identification

Parameter	Type	Required	Description	Constraints	Enum	Comment
type	string	required*	Type of verification		AGE_LIMIT, AGE_LIMIT_AT_HANDOVER, AGE_LIMIT_BY_MERCHANT_AT_HANDOVER, ALREADY_IDENTIFIED, ANY_PERSON, FRAUD_DETECTION, SPECIFIC_PERSON, SPECIFIC_PERSON_AT_HANDOVER	Required when the identification object is sent
ageLimit	number	optional	Minimum age required	Min: 0, Max: 20		Used with AGE_LIMIT types
ssn	string	optional	Required SSN for verification
name	string	optional	Required name for verification

cart

Parameter	Type	Required	Description	Constraints	Comment
checkoutId	string	optional	Checkout session ID	OneOf this, orderNumber, or availabilityToken
orderNumber	string	required*	Your order number	OneOf this, checkoutId, or availabilityToken	Used to link with your system
totalValueInCents	number	optional	Total order value in cents		Used for insurance purposes
totalWeightInGrams	number	optional	Total weight in grams		For logistics planning
parcel	object	optional	Parcel dimensions and contents		Detailed parcel information

cart.parcel

Parameter	Type	Required	Description	Enum	Comment
heightMm	number	optional	Parcel height in mm
widthMm	number	optional	Parcel width in mm
lengthMm	number	optional	Parcel length in mm
volumeDm3	number	optional	Parcel volume in dm³
estimatedSize	string	optional	Estimated size of the parcel. The sizes will be configured together with Instabee	SMALL, LARGE, TOOLARGE
weightGram	number	optional	Parcel weight in grams
type	string	optional	Parcel type	BOX, BAG
products	array	optional	Array of products in parcel		Detailed product information

cart.parcel.products[]

Parameter	Type	Required	Description	Comment
name	string	optional	Product name
quantity	string	optional	Quantity of this product	Sent as a string, not a number
productId	string	optional	Your product identifier
details	object	optional	Detailed product information
temperature	object	optional	Temperature requirements for the product
packages	array	optional	Physical packages the product is shipped in

cart.parcel.products[].details

Parameter	Type	Required	Description	Constraints
productType	string	optional	Type of product	e.g., "Prescription"
imgUrl	string	optional	Product image URL
category	string	optional	Product category
brand	string	optional	Product brand
description	string	optional	Product description
price	object	optional	Price information

cart.parcel.products[].details.price

Parameter	Type	Required	Description	Constraints	Comment
priceInCents	number	optional	Price in cents
taxValueInCents	number	optional	Tax amount in cents
discountRateInCents	number	optional	Discount amount in cents
currency	string	optional	Currency code	ISO 4217	e.g., "SEK"

cart.parcel.products[].temperature

Parameter	Type	Required	Description	Enum
min	number	optional	Minimum temperature in Celsius
max	number	optional	Maximum temperature in Celsius

cart.parcel.products[].packages[]

Parameter	Type	Required	Description	Comment
widthMm	string	optional	Package width in mm
heightMm	string	optional	Package height in mm
lengthMm	string	optional	Package length in mm
weightGram	string	optional	Package weight in grams
volumeDm3	string	optional	Package volume in dm³ (liters)
barcodes	object	optional	Barcode object for the package	Single object, not an array

cart.parcel.products[].packages[].barcodes

Parameter	Type	Required	Description	Enum
code	string	optional	Barcode value
type	string	optional	The barcode type	EAN13

Response

The API returns an updated parcel object with:

Field	Type	Description
parcelId	string	The Instabee parcel ID
status	string	Updated status (e.g., "PENDING_PACKING" or "FINALIZED")
links	object	An object with tracking and label links

links (object)

Field	Type	Description
label	string	URL to download the shipping label
tracking	string	URL to track the parcel

label URL parameters

The label URL supports optional query parameters to customize the output:

Param	Type	Default	Options	Description
fileFormat	string	`pdf`	`png`, `zpl`, `pdf`	Output file format
encoding	string		`base64`	Return label as base64-encoded string
template	string	`a6`	`a6`, `a7`	Label paper size
dpi	integer	`96`		Resolution in dots per inch
debug	boolean	`false`	`true`, `false`	Enable debug mode

Best Practices

Accurate Measurements: Always provide accurate dimensions and weight
Prompt Registration: Create the return order as soon as the consumer requests it
Error Handling: Implement proper error handling for failed requests
Label Management: Download and provide shipping labels to the consumer immediately
Status Tracking: Monitor the parcel status via the Instabee API or dashboard

Size Limitations

Each delivery method has maximum size and weight limitations:

Delivery Type	Max Length (cm)	Max Width (cm)	Max Height (cm)	Max Weight (kg)
Home Return	120	X	X (max total 300cm girth)	20

Exceeding these limitations may result in additional charges or pickup refusal.