# Package Commands
Operations for managing package state transitions and commands
## Update or create shipment label for a package
> Executes the \*UpdateShipmentLabelOfThePackageCommand\* to create or update the shipping label for a package.\
> \
> \*\*Prerequisites:\*\*\
> \- Package must be in \`preparing\`, \`waiting\_cargo\_label\`, \`packed\`, or \`shipped\` state\
> \- Package must have an associated shipment\
> \- Valid state transition must exist from source state to destination state\
> \- Either \`transition\` (transition ID) or \`slug\` (transition slug) must be provided in the request body\
> \
> \*\*Request Requirements:\*\*\
> \- If \`transition\` is provided, \`slug\` is not required\
> \- If \`slug\` is provided, \`transition\` is not required\
> \- At least one of \`transition\` or \`slug\` must be present\
> \
> \*\*Process:\*\*\
> 1\. Validates package state and parameters\
> 2\. Checks that package has an associated shipment\
> 3\. Locks the package for processing\
> 4\. Calls ShippingLabelService to create/update shipping label\
> 5\. If package is in \`waiting\_cargo\_label\` state and destination is \`packed\`, transitions package state\
> 6\. Fires PackagePackedStateEvent when transitioning to packed state\
> 7\. Validates that shipping label was successfully created\
> \
> \*\*Side Effects:\*\*\
> \- Shipping label is created or updated for the package\
> \- Package state may be transitioned (waiting\_cargo\_label → packed)\
> \- PackagePackedStateEvent is triggered on state transition\
> \- Label is retrieved from cargo company integration\
> \
> \*\*Response:\*\*\
> \- Returns HTTP 204 No Content on success\
> \- The updated package with shipping label can be retrieved separately if needed
```json
{"openapi":"3.0.3","info":{"title":"UpdateShipmentLabelOfThePackageCommand API","version":"1.0.0"},"tags":[{"name":"Package Commands","description":"Operations for managing package state transitions and commands"}],"servers":[{"url":"https://{domain}/api/v1/oms","variables":{"domain":{"default":"sandbox.akinon.com"}}}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Token","description":"API key for authentication"}},"schemas":{"UpdateShipmentLabelCommandRequest":{"type":"object","description":"Request body for updating shipment label. Either `transition` or `slug` must be provided.\n- If `transition` is provided, `slug` is not required\n- If `slug` is provided, `transition` is not required\n- Providing both is allowed but not necessary\n","required":["input_parameters"],"properties":{"input_parameters":{"type":"object","description":"Command input parameters","required":["package_items"],"properties":{"package_items":{"type":"array","description":"List of package items (can be empty array)","items":{"type":"object"}}}},"transition":{"type":"integer","description":"State transition ID to execute (required if slug is not provided)"},"slug":{"type":"string","description":"State transition slug to execute (required if transition is not provided)"}}},"ValidationErrorResponse":{"type":"object","description":"Validation error response with field-level errors","required":["error","status_code"],"properties":{"error":{"type":"object","description":"Validation errors grouped by field name","additionalProperties":{"type":"array","items":{"type":"string"}}},"status_code":{"type":"integer","description":"HTTP status code"}}},"ErrorResponse":{"type":"object","description":"Generic API error response supporting multiple error formats","properties":{"error":{"type":"object","description":"Error payload","oneOf":[{"type":"object","required":["code","message"],"properties":{"code":{"oneOf":[{"type":"string","enum":["INVALID_COMMAND_PARAMETER","INVALID_PACKAGE_STATE_TRANSITION","PACKAGE_STATE_TRANSITION_POST_ACTION_VALIDATION_ERROR","COMMAND_DEFINITION_NOT_ALLOWED"]},{"type":"integer","enum":[4406]}]},"message":{"type":"string"},"details":{"oneOf":[{"type":"object","properties":{"source_state":{"type":"string"},"destination_state":{"type":"string"},"package_state":{"type":"string"}}},{"type":"object","properties":{"error":{"type":"string"}}},{"type":"array","items":{"type":"string"}}]}}},{"type":"object","required":["detail"],"properties":{"detail":{"type":"string"}}}]},"status_code":{"type":"integer","description":"HTTP status code"}},"required":["error"]}}},"paths":{"/packages/{packageId}/command/":{"post":{"tags":["Package Commands"],"summary":"Update or create shipment label for a package","description":"Executes the *UpdateShipmentLabelOfThePackageCommand* to create or update the shipping label for a package.\n\n**Prerequisites:**\n- Package must be in `preparing`, `waiting_cargo_label`, `packed`, or `shipped` state\n- Package must have an associated shipment\n- Valid state transition must exist from source state to destination state\n- Either `transition` (transition ID) or `slug` (transition slug) must be provided in the request body\n\n**Request Requirements:**\n- If `transition` is provided, `slug` is not required\n- If `slug` is provided, `transition` is not required\n- At least one of `transition` or `slug` must be present\n\n**Process:**\n1. Validates package state and parameters\n2. Checks that package has an associated shipment\n3. Locks the package for processing\n4. Calls ShippingLabelService to create/update shipping label\n5. If package is in `waiting_cargo_label` state and destination is `packed`, transitions package state\n6. Fires PackagePackedStateEvent when transitioning to packed state\n7. Validates that shipping label was successfully created\n\n**Side Effects:**\n- Shipping label is created or updated for the package\n- Package state may be transitioned (waiting_cargo_label → packed)\n- PackagePackedStateEvent is triggered on state transition\n- Label is retrieved from cargo company integration\n\n**Response:**\n- Returns HTTP 204 No Content on success\n- The updated package with shipping label can be retrieved separately if needed\n","operationId":"updateShipmentLabelCommand","parameters":[{"name":"packageId","in":"path","required":true,"description":"The ID of the package to update shipment label for","schema":{"type":"integer","format":"int64"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateShipmentLabelCommandRequest"}}}},"responses":{"204":{"description":"Shipment label update completed successfully (No Content)","content":{}},"400":{"description":"Bad Request - Invalid parameters or validation errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"404":{"description":"Not Found - No Package matches the given query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"406":{"description":"Not Acceptable - Command execution failed or post-validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
---
# 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.akinon.com/technical-guides/oms/commands/shipment/update-shipment-label-of-package-command/package-commands.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.