This documentation is in beta, and might contain errors. Contact us at integration@instabee.com with any questions.

Instabee API

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:

  1. Capacity management (even for Home Delivery!)
  2. Information for our operation to plan pickups and routes better
  3. 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

EndpointMethodContent-Type
api.integration.instabee.com/orders (production) · sandbox-api.integration.instabee.com/orders (sandbox)PUTapplication/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

  1. Capacity Reservation: Ensures delivery slots are reserved for your customers
  2. Flexible Integration: Send as much or as little information as you have available
  3. Early Tracking: Customers get tracking information immediately after purchase
  4. 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

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

EndpointMethodContent-Type
api.integration.instabee.com/orders (production) · sandbox-api.integration.instabee.com/orders (sandbox)PUTapplication/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

ParameterTypeRequiredDescriptionConstraintsComment
brandstringoptionalDefine brand of the delivery optionsinstabox or budbee
productstringrequiredDefine the product of the delivery optionsMust be oneLOCKER_EXPRESS, LOCKER_RETURN, HOME_DELIVERY, LOCKER_CAPACITY_SURPLUS, LOCKER_ALLOCATION, LOCKER_AREA
countryCodestringrequired*Recipient country code. Can be sent in query paramISO 3166 alpha 2
parcelPackingConfirmedbooleanconditional*Confirm parcel is packed and ready for pickupSee docs
availabilityTokenstringoptionalAvailability token from availability response
orderIdstringoptionalUnique order reference for subsequent calls
parcelIdstringoptionalUnique identifier/barcode for parcelAuto-generated if omitted
merchantBrandIdstringoptionalBrand identifier
communicationNamestringoptionalCommunication name override
senderobjectoptionalSender information objectMainly for C2C
recipientobjectrequiredRecipient information object
dispatchobjectoptionalDispatch readiness and warehouse
optionsobjectoptionalResponse options / language
deliveryInstructionsobjectoptionalDelivery instruction details
additionalServicesobjectoptionalAdditional services
cartobjectoptionalParcel and/or product details

recipient

ParameterTypeRequiredDescriptionConstraintsComment
namestringrequiredRecipient name
emailstringrequiredRecipient email addressValid email formatUsed for delivery notifications
phonestringrequiredRecipient phone numberMin: 6 digits, Max 15 digitsCan be made optional with setting
ssnstringoptionalSocial security numberFor age verification services
streetstringrequiredRecipient street address
street2stringoptionalAdditional address informationFloor, apartment, etc.
postalCodestringrequiredRecipient postal code
citystringrequiredRecipient city
countryCodestringrequiredRecipient country codeISO 3166 alpha 2e.g., "SE", "DK", "NO"
coordinatesobjectoptionalGPS coordinatesFor precise location

recipient.coordinates

ParameterTypeRequiredDescription
latnumberoptionalLatitude
lonnumberoptionalLongitude

sender

ParameterTypeRequiredDescriptionConstraints
namestringoptionalSender/merchant name
emailstringoptionalSender email addressValid email format
phonestringoptionalSender phone number
streetstringoptionalSender street address
street2stringoptionalAdditional sender address info
postalCodestringoptionalSender postal code
citystringoptionalSender city
countryCodestringoptionalSender country codeISO 3166 alpha 2
coordinatesobjectoptionalSender GPS coordinates

sender.coordinates

ParameterTypeRequiredDescription
latnumberoptionalLatitude
lonnumberoptionalLongitude

deliveryOption

ParameterTypeRequiredDescriptionComment
sortCodestringrequiredSort code for the lockerIdentifies specific locker or specific home delivery option
etaIntervalobjectoptionalPreferred delivery time window

deliveryOption.etaInterval

ParameterTypeRequiredDescriptionConstraintsComment
fromstringoptionalStart of delivery windowISO-8601 datetime
tostringoptionalEnd of delivery windowISO-8601 datetimeWill default to best available if doesn't match

dispatch

ParameterTypeRequiredDescriptionConstraintsComment
readyToShipstringoptionalWhen parcel is ready for pickupISO-8601 datetimeOnly one of readyToShip/readyToPack/outOfStock
readyToPackstringoptionalWhen packing process will startISO-8601 datetimeInstabee adds packing time to this
outOfStockbooleanoptionalProduct is out of stocktrue/falseRemoves ETA from delivery options
packingTimenumberoptionalRequired packing time in minutes
collectionPointIdstringoptionalSpecific warehouse/pickup pointConfigured by Instabee
returnPointIdstringoptionalReturn address point IDFor failed deliveries

options

ParameterTypeRequiredDescriptionConstraintsComment
languageCodestringoptionalLanguage for customer communicationsISO 639-1e.g., "EN", "SE", "NO"
localEtasbooleanoptionalReturn local delivery termstrue/falseDifferent local terms for delivery promise
estimatedParcelTypebooleanoptionalReturn estimated parcel sizetrue/falseCalculated based on cart contents

deliveryInstructions

ParameterTypeRequiredDescriptionConstraintsComment
notifyBystringoptionalHow to notify recipient"ring_doorbell", "knock_on_door"
doorCodestringoptionalDoor or building access code
messagestringoptionalSpecial delivery instructionsFree text message
intercombooleanoptionalUse intercom if availabletrue/false

additionalServices

ParameterTypeRequiredDescriptionConstraintsComment
identificationobjectoptionalIdentity verification requirements
leaveByDoorstringoptionalAllow leaving parcel by door"allow", "disallow", "force"
leaveWithNeighbourstringoptionalAllow leaving with neighbor"allow", "disallow", "force"
numberOfMissRetriesnumberoptionalNumber of delivery retry attemptsMinimum: 1null = default

additionalServices.identification

ParameterTypeRequiredDescriptionConstraintsComment
typestringoptionalType of verification"age_limit", "age_limit_at_handover", "specific_person", "any_person"
ageLimitnumberoptionalMinimum age requiredUsed with age_limit types
ssnstringoptionalRequired SSN for verification
namestringoptionalRequired name for verification

cart

ParameterTypeRequiredDescriptionConstraintsComment
checkoutIdstringoptionalCheckout session IDOneOf this, orderNumber, or availabilityToken
orderNumberstringrequired*Your order numberOneOf this, checkoutId, or availabilityTokenUsed to link with your system
totalValueInCentsnumberoptionalTotal order value in centsUsed for insurance purposes
totalWeightGramnumberoptionalTotal weight in gramsFor logistics planning
parcelobjectoptionalParcel dimensions and contentsDetailed parcel information

cart.parcel

ParameterTypeRequiredDescriptionConstraintsComment
heightMmnumberoptionalParcel height in mm
widthMmnumberoptionalParcel width in mm
lengthMmnumberoptionalParcel length in mm
volumeDm3numberoptionalParcel volume in dm³
estimatedSizestringoptionalEstimated size category"small", "medium", "large"
weightGramnumberoptionalParcel weight in grams
typestringoptionalParcel type"box", "envelope", "bag"
productsarrayoptionalArray of products in parcelDetailed product information

cart.parcel.products[]

ParameterTypeRequiredDescription
namestringoptionalProduct name
quantitynumberoptionalQuantity of this product
productIdstringoptionalYour product identifier
detailsobjectoptionalDetailed product information

cart.parcel.products[].details

ParameterTypeRequiredDescriptionConstraints
productTypestringoptionalType of producte.g., "Prescription"
imgUrlstringoptionalProduct image URL
categorystringoptionalProduct category
brandstringoptionalProduct brand
descriptionstringoptionalProduct description
priceobjectoptionalPrice information
temperatureobjectoptionalTemperature requirements

cart.parcel.products[].details.price

ParameterTypeRequiredDescriptionConstraintsComment
priceInCentsnumberoptionalPrice in cents
taxRateInCentsnumberoptionalTax amount in cents
discountRateInCentsnumberoptionalDiscount amount in cents
currencystringoptionalCurrency codeISO 4217e.g., "SEK"

cart.parcel.products[].details.temperature

ParameterTypeRequiredDescription
minnumberoptionalMinimum temperature in Celsius
maxnumberoptionalMaximum temperature in Celsius

cart.parcel.products[]

ParameterTypeRequiredDescription
packagesarrayoptionalPhysical package information

cart.parcel.products[].packages[]

ParameterTypeRequiredDescriptionComment
widthMmnumberoptionalPackage width in mmNote: Different from Post Packing (widthMm)
heightMmnumberoptionalPackage height in mmNote: Different from Post Packing (heightMm)
lengthMmnumberoptionalPackage length in mmNote: Different from Post Packing (lengthMm)
weightMmnumberoptionalPackage weightNote: Different unit from Post Packing
volumeDm3numberoptionalPackage volume in mm³Note: Different from Post Packing (volumeDm3)
barcodesarrayoptionalBarcode information

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

ParameterTypeRequiredDescriptionConstraintsComment
codestringoptionalBarcode value
typestringoptionalBarcode type"ean13", etc.Lowercase in Post Purchase

Command Palette

Search for a command to run...