Skip to main content

Shipments

The Shipment entity represents a delivery of products from an order. It is created when an order is shipped to the customer.

Shipment States​

Shipments have two states:

  • Draft: shipment is pending fulfillment by the warehouse and is awaiting the first scan from the carrier that will deliver it.
  • Fulfilled: the shipment had a first scan, has a valid tracking number and will receive event updates.

The important distinction is between draft and fulfilled states:

Draft State​

  • Created when: Order is placed
  • Purpose: Show customers expected packages (you can set this in advance via API)
  • Has tracking number: No
  • Generates events: Only pre-in-transit events
  • Customer sees: "Your order will ship in X packages"

Fulfilled State​

  • Created when: A tracking number is added
  • Purpose: Real-time package tracking
  • Has tracking number: Yes
  • Generates events: All carrier tracking events
  • Customer sees: "Your package is in transit" with tracking details

Tracking​

FulfilledShipments are also called trackings. They represent a shipment with a valid tracking code. Such shipments will receive updates from the carriers.

Shipment vs Tracking Terminology​

In Karla's API, Shipment and Tracking refer to the same entity, with a few differences:

  • Shipment - This model has extensive data that is used beyond a tracking page.
  • Tracking - A subset of the Shipment data. It is nested inside an Order response, with a data model specific to show statuses in a tracking page.

Both represent the same package delivery entity and can be in either draft or fulfilled state.

Shipment phases​

A shipment changes its phase frequently during its journey.

All Shipment Phases
  • collect
  • delivery_failed
  • delivered
  • in_delivery
  • in_transit
  • order_created
  • order_processed
  • return_created
  • return_failed
  • return_received
  • return_transit
  • returned

Shipment events​

Every shipment event has an event_name that differentiates them uniquely. For complete documentation of all events, including their ref patterns for webhook filtering and event groups, see Events**

Event Names by Phase​

info

The tables below show event names only. For complete ref patterns, webhook filtering, and event groups, see the Events Reference.

Order Created (order_created) - 2 events
  • ORDER_CREATED
  • ORDER_IN_PROCESSING
Order Processed (order_processed) - 23 events
  • CARRIER_UNKNOWN
  • DISPATCHED_FROM_FORWARDING_DEPOT
  • ERROR_IN_PARCEL_DATA_SUBMISSION
  • ORDER_PROCESSED
  • PARCEL_COLLECTED_FROM_DROP_OFF_LOCATION
  • PARCEL_DATA_SUBMISSION_DELAYED
  • PARCEL_DATA_SUBMITTED_TO_CARRIER
  • PARCEL_DISPATCHED
  • PARCEL_DROPPED_OFF_AT_PARCEL_LOCKER
  • PARCEL_DROPPED_OFF_AT_POST_OFFICE
  • PARCEL_DROPPED_OFF_IN_PARCEL_SHOP
  • PARCEL_DROPPED_OFF_OVER_THE_COUNTER
  • PARCEL_DROPPED_OFF_WITH_CARRIER
  • PARCEL_READY_FOR_PICKUP
  • PICKUP_ATTEMPTED
  • PICKUP_DELAYED
  • PICKUP_FAILED
  • PICKUP_SUCCESSFUL
  • PROCEEDING_TO_CARRIER_FACILITY
  • RECEIPT_AT_FORWARDING_DEPOT
  • SHIPMENT_INFO_SENT_TO_LAST_MILE_SERVICE_PROVIDER
  • SHIPMENT_NEVER_ARRIVED
In Transit (in_transit) - 50+ events
  • ACCEPTED_BY_DESTINATION_OFFICE
  • ACCEPTED_BY_ORIGIN_OFFICE
  • ARRIVAL_AT_FINAL_DELIVERY_CENTER
  • ARRIVAL_AT_TRANSPORT_HUB
  • ARRIVAL_IN_DESTINATION_COUNTRY
  • ARRIVED_AT_SORTING_CENTER
  • ASSIGNED_TO_TRANSPORT
  • AT_SORTING_CENTER
  • AT_TRANSPORT_HUB
  • COMPLETION_OF_CUSTOMS_PROCESSING
  • COMPLETION_OF_EXPORT_PROCESSING
  • CUSTOMS_PROCESSING
  • DELAY_EXPECTED
  • DELAY_IN_TRANSPORT_MISROUTED_SHIPMENT
  • DELAY_IN_TRANSPORT_OFFLOADED_SHIPMENT
  • DELAY_IN_TRANSPORT
  • DEPARTURE_FROM_TRANSPORT_HUB
  • DISPATCHED_FROM_DELIVERY_CENTER
  • DISPATCHED_FROM_SORTING_CENTER
  • DISPATCHING_STARTED_AT_PROCESSING_CENTER
  • ENCODING_COMPLETED_AT_PROCESSING_CENTER
  • ENCODING_ERROR_IN_PROCESSING_AT_SORTING_CENTER
  • ENCODING_STARTED_AT_PROCESSING_CENTER
  • ERROR_IN_PROCESSING_AT_SORTING_CENTER
  • EXPORT_PROCESSING
  • FAILED_TO_HAND_OVER_TO_DELIVERY_PARTNER
  • HANDED_OVER_TO_DELIVERY_PARTNER
  • HELD_AT_CUSTOMS_FOR_ADDITIONAL_PAYMENT
  • HELD_AT_CUSTOMS_FOR_CLARIFICATIONS
  • HELD_AT_CUSTOMS
  • HELD_AT_EXPORT_PROCESSING
  • INBOUND_FLIGHT_ARRIVED
  • INBOUND_TRUCK_ARRIVED
  • ISSUES_IN_PROCESSING_BY_CUSTOMS_AUTHORITIES
  • MORE_INFO_ON_CARRIER_WEBSITE
  • OUTBOUND_FLIGHT_DEPARTED
  • OUTBOUND_TRUCK_DEPARTED
  • PROCESSED_AT_DELIVERY_CENTER
  • PROCESSING_AT_TRANSPORT_HUB
  • SCANNED_AT_PROCESSING_CENTER
  • SHIPMENT_AT_FINAL_DELIVERY_CENTER
  • SHIPMENT_DAMAGED
  • SHIPMENT_DELAYED_DUE_TO_CUSTOMER_REQUEST
  • SHIPMENT_EN_ROUTE
  • SHIPMENT_MISROUTED
  • SORTING_COMPLETED_AT_PROCESSING_CENTER
  • SORTING_ERROR_IN_PROCESSING_AT_SORTING_CENTER
  • SORTING_STARTED_AT_PROCESSING_CENTER
  • START_OF_CUSTOMS_PROCESSING
  • START_OF_EXPORT_PROCESSING
  • TRANSPORT_ARRIVED
  • TRANSPORT_DEPARTED
In Delivery (in_delivery) - 19 events
  • ATTEMPTED_DELIVERY_UNDELIVERABLE
  • DELIVERY_ATTEMPTED_ADDRESS_COULD_NOT_BE_FOUND
  • DELIVERY_ATTEMPTED_ADDRESSEE_MOVED
  • DELIVERY_ATTEMPTED_ADDRESSEE_NOT_KNOWN_AT_ADDRESS
  • DELIVERY_ATTEMPTED_CASH_ON_DELIVERY_AMOUNT_NOT_READY
  • DELIVERY_ATTEMPTED_FAILED_WILL_TRY_AGAIN
  • DELIVERY_ATTEMPTED_FORWARDING_TO_PICKUP_LOCATION
  • DELIVERY_ATTEMPTED_LAST_ATTEMPT
  • DELIVERY_ATTEMPTED_RECIPIENT_NOT_AT_HOME
  • DELIVERY_ATTEMPTED
  • DELIVERY_LAPSED
  • DELIVERY_OPTION_REQUESTED_BY_RECEIVER
  • DELIVERY_SCHEDULED_IN_THE_FINAL_DELIVERY_DEPOT
  • IN_DELIVERY
  • NO_DELIVERY_ATTEMPT_ON_ROUTE
  • OUT_FOR_DELIVERY
  • PATCHED
  • SHIPMENT_ON_HOLD_IN_DELIVERY_CENTER
  • SHIPMENT_ON_ITS_WAY_TO_PICKUP_LOCATION
Collect (collect) - 6 events
  • ARRIVED_AT_PARCEL_LOCKER
  • ARRIVED_AT_PARCEL_SHOP
  • ARRIVED_AT_POST_OFFICE
  • SUCCESSFULLY_DELIVERED_TO_NEIGHBOR
  • SUCCESSFULLY_DELIVERED_AND_LEFT_AT_LETTER_BOX
  • DELIVERY_ATTEMPTED_RECIPIENT_NOT_AT_HOME_CARD_LEFT
Delivered (delivered) - 10 events
  • PARCEL_TRANSFERRED_TO_THIRD_PARTY
  • SUCCESSFULLY_COLLECTED_AT_PARCEL_LOCKER
  • SUCCESSFULLY_COLLECTED_AT_PARCEL_SHOP
  • SUCCESSFULLY_COLLECTED_AT_POST_OFFICE
  • SUCCESSFULLY_COLLECTED
  • SUCCESSFULLY_DELIVERED_AND_CASH_ON_DELIVERY_COLLECTED
  • SUCCESSFULLY_DELIVERED_AND_LEFT_AT_DOOR
  • SUCCESSFULLY_DELIVERED_AND_PROOF_OF_DELIVERY_COLLECTED
  • SUCCESSFULLY_DELIVERED
  • USER_SUCCESSFULLY_DELIVERED
Delivery failed (delivery_failed) - 6 events
  • DELIVERY_ATTEMPTED_REJECTED_BY_ADDRESSEE
  • SHIPMENT_NOT_PICKED_UP_FROM_PARCEL_LOCKER_RETURNED_TO_BASE
  • SHIPMENT_NOT_PICKED_UP_FROM_PARCEL_LOCKER_RETURNED_TO_ORIGIN_COUNTRY
  • SHIPMENT_NOT_PICKED_UP_FROM_PARCEL_SHOP_RETURNED_TO_BASE
  • SHIPMENT_NOT_PICKED_UP_FROM_POST_OFFICE_RETURNED_TO_BASE
  • SHIPMENT_NOT_PICKED_UP_RETURNED_TO_ORIGIN_COUNTRY
Returned (returned) - 7 events
  • RETURN_IN_PROGRESS
  • RETURN_TO_SENDER_COMPLETED
  • RETURN_TO_SENDER_FAILED
  • SHIPMENT_REJECTED_RETURNING_TO_SENDER
  • SHIPMENT_RETURNED_TO_SENDER
  • SHIPMENT_RETURNING_TO_SENDER
  • SHIPMENT_SUCCESSFULLY_RETURNED_TO_SENDER
Return failed (return_failed) - 1 event
  • DELIVERY_FAILED_SHIPMENT_DESTROYED

API Reference​

  • Shipment - Detailed shipment and tracking information
  • Order - Detailed order and tracking information