Post Purchase Flow
The Post Purchase flow (also known as the Create Order API) is called immediately after the consumer completes their purchase with Home Delivery selected. Instabee uses this to reserve capacity and begin planning the home delivery route.
Overview
What is Post Purchase? This is like a "prebooking" except that we do not actually "book" anything. It's being used for:
- Capacity management (even for Home Delivery!)
- Information for our operation to plan pickups and routes better
- Gives Instabee the possibility to talk to the consumer earlier to help them with any of their needs.
It does also levels up the integration and enables you to send information in the post purchase call that is not possible to send in the post packing call. As Instabee will easily merge the information on our end without introducing any extra complexity.
API Endpoint
| Endpoint | Method | Content-Type |
|---|---|---|
api.integration.instabee.com/orders (production) · sandbox-api.integration.instabee.com/orders (sandbox) | PUT | application/json |
When to Use
Call this endpoint immediately after:
- Customer completes their purchase in your checkout system
Integration Levels
You can integrate at different levels on what's possible:
- Nothing: This call can of course be skipped completely but that just makes it harder for Instabee to achieve a great delivery experience.
- Bare Minimum: Just an availability token/short toke/order reference/cart ID and the selected delivery options. This is the absolute minimum and will enable us to reserve the capacity.
- Regular (or Instabee prefered option): Basic recipient and delivery information.
- Maximum: Complete order details including products, dimensions, and special services. You can create a full order directly and just confirm the packing is done at a later stage.
Key Benefits
- Capacity Reservation: Ensures delivery slots are reserved for your customers
- Flexible Integration: Send as much or as little information as you have available
- Early Tracking: Customers get tracking information immediately after purchase
- Optimized Logistics: Helps Instabee plan pickup and delivery routes
Next Steps
- Complete Parameter Reference: See the Create Order API page for all available parameters
- After Packing: Use the Post Packing API to confirm when parcels are ready for pickup
- Integration Guide: Check the Authentication section for API setup
Quick Links
- Availability API - Check delivery options before creating parcels
- Post Packing API - Confirm parcels after physical packing
Create Order API
The Create Order API (also known as Create Parcel or Order Create API) is used to register a parcel for delivery immediately after a customer completes their purchase. This is the prebooking step that reserves capacity for delivery before the parcel is physically packed.
API Endpoint
| Endpoint | Method | Content-Type |
|---|---|---|
api.integration.instabee.com/orders (production) · sandbox-api.integration.instabee.com/orders (sandbox) | PUT | application/json |
Integration Levels
You can provide information at different levels:
- Bare Minimum: Nothing
- Minimum: Basic order identification and delivery option
- Regular: Basic recipient and delivery information
- Maximum: Complete order details including products, dimensions, and special services
Request Body
| Parameter | Type | Required | Description | Constraints | Enum | 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 | HOME_DELIVERY | |
| countryCode | string | required* | Recipient country code. Can be sent in query param | ISO 3166 alpha 2 | DK, FI, NO, SE | |
| 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 | ||
| sender | object | optional | Sender information object | Not normally needed for Home Delivery | ||
| recipient | object | required | 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 |
recipient
| Parameter | Type | Required | Description | Constraints | Enum | Comment |
|---|---|---|---|---|---|---|
| name | string | required | Recipient name | |||
| string | required | Recipient email address | Valid email format | Used for delivery notifications | ||
| phone | string | required | Recipient 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 | 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 | DK, FI, NO, SE | |
| coordinates | object | optional | GPS coordinates | For precise location |
recipient.coordinates
| Parameter | Type | Required | Description | Enum |
|---|---|---|---|---|
| lat | number | optional | Latitude | |
| lon | number | optional | Longitude |
sender
| Parameter | Type | Required | Description | Constraints | Enum | Comment |
|---|---|---|---|---|---|---|
| name | string | optional | Sender/merchant name | |||
| string | optional | Sender email address | Valid email format | |||
| phone | string | optional | Sender phone number | Box: Min 6 digits, Home delivery: Min 10 digits, Max 15 digits | ||
| street | string | optional | Sender street address | |||
| street2 | string | optional | Additional sender address info | |||
| postalCode | string | optional | Sender postal code | |||
| city | string | optional | Sender city | |||
| countryCode | string | optional | Sender (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 | Sender GPS coordinates |
sender.coordinates
| Parameter | Type | Required | Description | Enum |
|---|---|---|---|---|
| lat | number | optional | Latitude | |
| lon | number | optional | Longitude |
deliveryOption
| Parameter | Type | Required | Description | Enum | Comment |
|---|---|---|---|---|---|
| sortCode | string | required | Sort code for the selected home delivery slot | Identifies the specific home delivery option | |
| etaInterval | object | optional | Preferred delivery time window |
deliveryOption.etaInterval
| Parameter | Type | Required | Description | Constraints | Enum | Comment |
|---|---|---|---|---|---|---|
| from | string | required* | Start of delivery window | ISO-8601 datetime | Required when etaInterval is sent | |
| to | string | required* | End of delivery window | ISO-8601 datetime | Required when etaInterval is sent. Defaults to best available if it doesn't match |
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 recipient | ring_doorbell, knock_on_door | |
| doorCode | string | optional | Door or building access code | ||
| message | string | optional | Special delivery 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 delivery 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 | Enum | 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 | Enum | 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 | Enum |
|---|---|---|---|---|---|
| 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 | Enum | 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 | Enum | 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 the created order/parcel with:
| Field | Type | Description |
|---|---|---|
| orderId | string | The Instabee order ID |
| parcelId | string | The Instabee parcel ID |
| state | string | Parcel state ("PENDING_PACKING" until packing is confirmed) |
| links | object | Object with label and tracking links |
links (object)
| Field | Type | Description |
|---|---|---|
| label | string | URL to download the shipping label |
| tracking | string | Preliminary tracking URL — see the note below |
Preliminary tracking link: links.tracking in this response is preliminary. It is generated before the parcel exists in our tracking system, so it does not resolve yet — opening it gives a broken link. Retrieve the working link with Get Tracking or Fetch Order once the parcel has been registered.
Separate senderTracking and recipientTracking links are not returned here. They only exist for LOCKER_TO_LOCKER (Consumer to Consumer) parcels — see Fetch Tracking Links.