# Order/Warehouse Events ## Create Event You can create a new event in the parcelLab system using the `v4/track/events` endpoint. ## POST /v4/track/events/ > Create Event ```json {"openapi":"3.1.0","info":{"title":"parcelLab API","version":"v4"},"security":[{"OAuth2 Authentication":[]},{"HeaderToken":[]}],"components":{"securitySchemes":{"OAuth2 Authentication":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"HeaderToken":{"type":"http","scheme":"bearer","bearerFormat":"Parcellab-API-Token base64(account_id:token)","description":"Send `Authorization: Parcellab-API-Token `.\n\n`` = `base64(account_id:token)` as provided in the portal."}},"schemas":{"EventSchemaRootModelRequest":{"$ref":"#/components/schemas/EventSchema","title":"EventSchemaRootModel"},"EventSchema":{"anyOf":[{"$ref":"#/components/schemas/EventSchemaTracking"},{"$ref":"#/components/schemas/EventSchemaReference"},{"$ref":"#/components/schemas/EventSchemaOrder"}]},"EventSchemaTracking":{"properties":{"event_timestamp":{"description":"Timestamp of the event","format":"date-time","title":"Event Timestamp","type":"string"},"location":{"description":"Location of the event","title":"Location","type":"string"},"event_status":{"$ref":"#/components/schemas/EventTypes","description":"Status code of the event","title":"Event Status"},"event_details":{"description":"Message of the event","title":"Event Details Message","type":"string"},"placeholder_value":{"description":"Placeholder value for events with specifics, such as 'ScheduledDelivery ###'","title":"Placeholder Value","type":"string"},"courier":{"description":"Key of the courier, if available (required, unless reference number is provided)","title":"Courier","type":"string"},"tracking_number":{"description":"Tracking number of the shipment, if available. If no tracking number is available, reference number must be used.","title":"Tracking Number","type":"string"}},"required":["event_status","courier","tracking_number"],"title":"EventSchemaTracking","type":"object"},"EventTypes":{"enum":["WarehousePending","WarehousePrepared","WarehouseDelay","Loaded","InboundScan","InTransit","ExportHub","ImportHub","CustomsIn","CustomsReleased","Exception-AddressIssue","Exception-CustomerRefusal","Exception-Customs","Exception-Damaged","Exception-DeliveryPayment","Exception-IdentFailed","Exception-ItemMissing","Exception-Notified","Exception-Strike","ScheduledDelivery ###","ScheduledTomorrow","DestinationDeliveryCenter","OutForDelivery","FailedAttempt-NewAttemptNextDay","FailedAttempt-NewAttemptToday","FailedAttempt-PickUpReady","FailedAttempt-Scheduled ###","PickupReady","PickupReady, collect at ###","Delivered","Delivered-Doorstep","Delivered-HomeDeposit","Delivered-Neighbor","Delivered-Notified","Delivered-ParcelLocker","Delivered-ParcelShop","Delivered-Postbox","ReturnToSender-Damaged","ReturnToSender-DeliveryPayment","ReturnToSender-NotCollected","ReturnToSender-Recall","ReturnDroppedOff","ReturnInProcess","ReturnDelivered","ReturnRefunded","RMAProcessed"],"type":"string"},"EventSchemaReference":{"properties":{"event_timestamp":{"description":"Timestamp of the event","format":"date-time","title":"Event Timestamp","type":"string"},"location":{"description":"Location of the event","title":"Location","type":"string"},"event_status":{"$ref":"#/components/schemas/EventTypes","description":"Status code of the event","title":"Event Status"},"event_details":{"description":"Message of the event","title":"Event Details Message","type":"string"},"placeholder_value":{"description":"Placeholder value for events with specifics, such as 'ScheduledDelivery ###'","title":"Placeholder Value","type":"string"},"account":{"description":"ID of the account","title":"Account ID","type":"integer"},"reference_number":{"description":"Reference number of the shipment, if no tracking number is available","title":"Reference Number","type":"string"}},"required":["event_status","account","reference_number"],"title":"EventSchemaReference","type":"object"},"EventSchemaOrder":{"properties":{"event_timestamp":{"description":"Timestamp of the event","format":"date-time","title":"Event Timestamp","type":"string"},"location":{"description":"Location of the event","title":"Location","type":"string"},"event_status":{"$ref":"#/components/schemas/EventTypes","description":"Status code of the event","title":"Event Status"},"event_details":{"description":"Message of the event","title":"Event Details Message","type":"string"},"placeholder_value":{"description":"Placeholder value for events with specifics, such as 'ScheduledDelivery ###'","title":"Placeholder Value","type":"string"},"account":{"description":"ID of the account","title":"Account ID","type":"integer"},"order_number":{"description":"Order number of the shipment","title":"Order Number","type":"string"}},"required":["event_status","account","order_number"],"title":"EventSchemaOrder","type":"object"},"Error400Response":{"type":"object","properties":{"type":{"type":"string"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/GenericErrorItem"}}},"required":["errors","type"]},"GenericErrorItem":{"type":"object","properties":{"code":{"type":"string"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["code","detail"]},"ErrorResponse403":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ClientErrorEnum"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error403"}}},"required":["errors","type"]},"ClientErrorEnum":{"enum":["client_error"],"type":"string","description":"* `client_error` - Client Error"},"Error403":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode403Enum"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["attr","code","detail"]},"ErrorCode403Enum":{"enum":["permission_denied"],"type":"string","description":"* `permission_denied` - Permission Denied"}}},"paths":{"/v4/track/events/":{"post":{"operationId":"track_events_create","summary":"Create Event","tags":["Events"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventSchemaRootModelRequest"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/EventSchemaRootModelRequest"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/EventSchemaRootModelRequest"}}}},"responses":{"204":{"description":"No response body"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}},"description":""},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse403"}}},"description":""}}}}}} ``` ### Allowed API Payload Structures This API accepts request bodies (payloads) to update via multiple reference numbers. The provided payload always must contain: * The `event_yimestamp` of the event in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format `YYYY-MM-DD[T]HH:mm:ss.SSSZ`. * The `event_status` can be any internal code describing a status that will be mapped by the parcelLab team. * Optional `location` of the event as any clear text string. #### Via Courier and Tracking Number To update a specific tracking via providing the original courier code and tracking number, your payload must include the following: * The `courier` in the parcelLab format. * The `tracking_number` as listed in the parcelLab system.
Courier and Tracking Number Example In this example, you would send a request similar to the below. ``` { "event_timestamp": "2025-04-09T16:12:00.000Z", "location": "Munich, Germany", "event_status": "WarehousePending" "courier": "dhl-germany", "tracking_number": "00340001612264742802", } ```
#### Via Account and Reference Number If no tracking number is available, the reference number must be used. The payload can be changed to include the following: * The `account` ID as listed in the parcelLab system. * The `reference_number` of the shipment.
Account and Referemce Number Example In this example, you would send a request similar to the below. ``` { "event_timestamp": "2025-04-09T16:12:00.000Z", "location": "Munich, Germany", "event_status": "WarehousePending" "account": "1612197", "reference_number": "12DE442983451", } ```
#### Via Account and Order Number Events can also be attached to any order. For this, the identification key is `order_number`. The payload can be changed to include the following: * The `account` ID as listed in the parcelLab system. * The `order_number` as listed in the parcelLab system.
Account and Order Number Example In this example, you would send a request similar to the below. ``` { "event_timestamp": "2025-04-09T16:12:00.000Z", "location": "Munich, Germany", "event_status": "WarehousePending" "account": "1612197", "order_number": "PK1004", } ```
--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.parcellab.com/docs/developers/status-updates/send-shop-events.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.