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 in different steps depending on their workflow:
- Bare Minimum: If everything was sent previously, just confirm packing
- Minimum: Basic confirmation with essential parcel 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
- Pickup: Consumer keeps parcel ready for scheduled pickup
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
- Availability API - Check delivery options and get tokens
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
- The parcel is ready for collection from the consumer's address
- You have the consumer's full address details
Merchants can send information in different steps - some may provide all details upfront, others may provide minimal information initially.
Request Body
| Parameter | Type | Required | Description | Constraints | Comment |
|---|---|---|---|---|---|
| parcelPackingConfrimed | boolean | optional* | 1. Set to true if only the create return call is made. 2. If you want to make more edits then actively set to false. 3. The call will automatically set this param to true if nothing is sent. | true or false | |
| 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 country code. Can be sent in query param | ISO 3166 alpha 2 | |
| parcelPackingConfirmed | boolean | conditional* | Confirm parcel is packed and ready for pickup | See docs | |
| 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 | |
| merchantBrandId | string | optional | Brand identifier | ||
| communicationName | string | optional | Communication name override | ||
| 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 | Comment |
|---|---|---|---|---|---|
| name | string | required | Consumer name | ||
| string | required | Consumer email address | Valid email format | Used for pickup notifications | |
| phone | string | required | Consumer phone number | Min: 6 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 | Consumer country code | ISO 3166 alpha 2 | e.g., "SE", "DK", "NO" |
| coordinates | object | optional | GPS coordinates | For precise location |
sender.coordinates
| Parameter | Type | Required | Description |
|---|---|---|---|
| lat | number | optional | Latitude |
| lon | number | optional | Longitude |
recipient
| Parameter | Type | Required | Description | Constraints |
|---|---|---|---|---|
| name | string | optional | Merchant/recipient name | |
| string | optional | Recipient email address | Valid email format | |
| phone | string | optional | Recipient phone number | |
| 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 country code | ISO 3166 alpha 2 |
| coordinates | object | optional | Recipient GPS coordinates |
recipient.coordinates
| Parameter | Type | Required | Description |
|---|---|---|---|
| lat | number | optional | Latitude |
| lon | number | optional | Longitude |
deliveryOption
| Parameter | Type | Required | Description | Comment |
|---|---|---|---|---|
| sort_code | string | required | Sort code for home return pickup | Identifies specific pickup time |
| etaInterval | object | optional | Preferred pickup time window |
deliveryOption.etaInterval
| Parameter | Type | Required | Description | Constraints | Comment |
|---|---|---|---|---|---|
| from | string | optional | Start of pickup window | ISO-8601 datetime | |
| to | string | optional | End of pickup window | ISO-8601 datetime | Will default to best available if doesn't match |
dispatch
| Parameter | Type | Required | Description | Constraints | 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 | Comment |
|---|---|---|---|---|---|
| languageCode | string | optional | Language for customer communications | ISO 639-1 | e.g., "EN", "SE", "NO" |
| 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 | Constraints | 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 | Comment |
|---|---|---|---|---|---|
| identification | object | optional | Identity verification requirements | ||
| leaveByDoor | string | optional | Allow leaving parcel by door | "allow", "disallow", "force" | |
| leaveWithNeighbour | string | optional | Allow leaving with neighbor | "allow", "disallow", "force" | |
| numberOfMissRetries | number | optional | Number of pickup retry attempts | Minimum: 1 | null = default |
additionalServices.identification
| Parameter | Type | Required | Description | Constraints | Comment |
|---|---|---|---|---|---|
| type | string | optional | Type of verification | "age_limit", "age_limit_at_handover", "specific_person", "any_person" | |
| ageLimit | number | optional | Minimum age required | 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 | |
| totalWeightGram | 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 | Constraints | 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 category | "small", "medium", "large" | |
| weightGram | number | optional | Parcel weight in grams | ||
| type | string | optional | Parcel type | "box", "envelope", "bag" | |
| products | array | optional | Array of products in parcel | Detailed product information |
cart.parcel.products[]
| Parameter | Type | Required | Description |
|---|---|---|---|
| name | string | optional | Product name |
| quantity | number | optional | Quantity of this product |
| productId | string | optional | Your product identifier |
| details | object | optional | Detailed product information |
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 | |
| temperature | object | optional | Temperature requirements |
cart.parcel.products[].details.price
| Parameter | Type | Required | Description | Constraints | Comment |
|---|---|---|---|---|---|
| priceInCents | number | optional | Price in cents | ||
| taxRateInCents | 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[].details.temperature
| Parameter | Type | Required | Description |
|---|---|---|---|
| min | number | optional | Minimum temperature in Celsius |
| max | number | optional | Maximum temperature in Celsius |
cart.parcel.products[]
| Parameter | Type | Required | Description |
|---|---|---|---|
| packages | array | optional | Physical package information |
cart.parcel.products[].packages[]
| Parameter | Type | Required | Description |
|---|---|---|---|
| widthMm | number | optional | Package width in mm |
| heightMm | number | optional | Package height in mm |
| lengthMm | number | optional | Package length in mm |
| weightMm | number | optional | Package weight |
| volumeDm3 | number | optional | Package volume in mm³ |
| barcodes | array | optional | Barcode information |
cart.parcel.products[].packages[].barcodes[]
| Parameter | Type | Required | Description | Constraints |
|---|---|---|---|---|
| code | string | optional | Barcode value | |
| type | string | optional | Barcode type | "ean13", etc. |
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 |
| base64 | boolean | false | true, false | 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.