Create Return
This endpoint creates a locker return order. Locker Return supports four usage modes — make sure you have aligned with your Implementation Manager on which to use and what parcel sizes apply:
- Standalone return, labelless — Recommended. The consumer drops off without attaching a label, providing a smoother experience.
- Standalone return, with label — The consumer attaches a label to the parcel before dropping off.
- Associated return, labelless — Linked to an outbound parcel via
associatedParcelId. The return cannot be activated until the outbound parcel has been delivered. - Associated return, with label — Same as above, but with a label.
Use isLabelless: true for the labelless variants. For associated returns, include the associatedParcelId of the original outbound parcel. Parcel dimensions are required for all return orders.
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:
- Minimum: Basic confirmation with essential parcel details
- Maximum: Complete order details with final dimensions and product information
Request Body
| Parameter | Type | Required | Description | Constraints | Comment |
|---|---|---|---|---|---|
| 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 | LOCKER_RETURN |
| availabilityToken | string | optional | Availability token from availability response | Can be optional if agreed with your Implementation Manager | |
| parcelId | string | optional | Unique identifier/barcode for parcel | Auto-generated if omitted | |
| merchantBrandId | string | optional | Merchant brand identifier | This is a feature to use multiple brands without using multiple credentials. Needs to be configured if used. Talk to your Implementation Manager | |
| communicationName | string | optional | Communication name override | Note! This will only change the name in Instabee communication such as notifications, SMS or email. Will not change partner name in our partner portal nor change any specs on invoices | |
| sender | object | required | Sender (consumer) information object | ||
| recipient | object | optional | Recipient (merchant) information object. Will default to configuration | ||
| deliveryOption | object | required* | The selected locker from for drop off. | ||
| dispatch | object | optional | Return warehouse information | ||
| cart | object | required* | Parcel and/or product details. Size of parcel is required for returns |
sender
| Parameter | Type | Required | Description | Constraints | Comment |
|---|---|---|---|---|---|
| name | string | required | Recipient name | ||
| string | required | Recipient email address | Valid email format | Used for delivery notifications | |
| phone | string | required | Recipient 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 | Recipient street address | ||
| street2 | string | optional | Additional address information | Floor, apartment, etc. | |
| postalCode | string | required | Recipient postal code | ||
| city | string | required | Recipient city | ||
| countryCode | string | required | Recipient country code | ISO 3166 alpha 2 | e.g., "SE", "DK", "NO" |
| coordinates | object | optional | GPS coordinates | For precise location |
recipient
| Parameter | Type | Required | Description | Constraints | Comment |
|---|---|---|---|---|---|
| name | string | required | Recipient name | ||
| string | required | Recipient email address | Valid email format | Used for delivery notifications | |
| phone | string | required | Recipient 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 | Recipient street address | ||
| street2 | string | optional | Additional address information | Floor, apartment, etc. | |
| postalCode | string | required | Recipient postal code | ||
| city | string | required | Recipient city | ||
| countryCode | string | required | Recipient country code | ISO 3166 alpha 2 | e.g., "SE", "DK", "NO" |
| coordinates | object | optional | GPS coordinates | For precise location |
deliveryOption
| Parameter | Type | Required | Description | Comment |
|---|---|---|---|---|
| sort_code | string | required | Sort code for the dropoff locker | Identifies specific locker or specific home delivery time |
dispatch
| Parameter | Type | Required | Description | Comment |
|---|---|---|---|---|
| returnPointId | string | optional | Not yet implemented. Return address point ID | For failed deliveries |
cart
| Parameter | Type | Required | Description | Comment |
|---|---|---|---|---|
| checkoutId | string | optional | Checkout session ID | Used as a link in Instabee system |
| orderNumber | string | required* | Your order number | Used as a link in Instabee system |
| totalValueInCents | number | optional | Total order value in cents | This helps us with claims process |
| totalWeightGram | number | optional | Total weight in grams | This helps us with claims process |
| parcel | object | optional | Parcel dimensions and contents | Detailed parcel information |
cart.parcel
| Parameter | Type | Required | Description | Constraints | Comment |
|---|---|---|---|---|---|
| heightMm | number | required | Parcel height in mm | ||
| widthMm | number | required | Parcel width in mm | ||
| lengthMm | number | required | Parcel length in mm | ||
| volumeDm3 | number | optional | Parcel volume in dm³ | If you do not have this data, do not send anything | |
| estimatedSize | string | optional | Estimated size category | "small", "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 8. Temperature in Celsius |
| max | number | optional | Maximum 15. Temperature in Celsius |
cart.parcel.products[]
| Parameter | Type | Required | Description |
|---|---|---|---|
| packages | array | optional | Physical package information |
cart.parcel.products[].packages[]
| Parameter | Type | Required | Description | Comment |
|---|---|---|---|---|
| widthMm | number | optional | Package width in mm | If you do not have this data, do not send anything |
| heightMm | number | optional | Package height in mm | If you do not have this data, do not send anything |
| lengthMm | number | optional | Package length in mm | If you do not have this data, do not send anything |
| weightMm | number | optional | Package weight | If you do not have this data, do not send anything |
| volumeDm3 | number | optional | Package volume in mm³ | If you do not have this data, do not send anything |
| barcodes | array | optional | Barcode information | If you do not have this data, do not send anything |
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 | And 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 Confirmation: Confirm packing as soon as possible after physical packing
- Error Handling: Implement proper error handling for failed confirmations
- Label Management: Download and store shipping labels 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) |
|---|---|---|---|---|
| Locker - Small | 39 | 39 | 59 | 20 |
Exceeding these limitations may result in additional charges or delivery refusal.
Quick Links
- Post Purchase API - Initial prebooking before packing
- Availability API - Check delivery options and get tokens