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 | 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 country code. Can be sent in query param | ISO 3166 alpha 2 | |
| 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 | ||
| 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 | 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 | 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 | 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 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 |
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 |
| 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.