Sales Order Shipment API¶
Introduction¶
The Sales Order Shipment API allows you to manage shipments in your OpenMage store. You can retrieve shipment information, create new shipments, add comments, and manage tracking information.
Available Methods¶
list¶
Retrieve list of shipments with basic info.
Method Name: sales_order_shipment.list
Parameters:
filters
(object|array, optional) - Filters to apply to the list:shipment_id
(int|array) - Filter by shipment ID(s)order_id
(int|array) - Filter by order ID(s)increment_id
(string|array) - Filter by increment ID(s)created_at
(string|array) - Filter by creation dateorder_increment_id
(string|array) - Filter by order increment ID(s)- Other attributes can also be used as filters
Return:
- (array) - Array of shipments with the following structure:
increment_id
(string) - Shipment increment IDshipment_id
(int) - Shipment IDorder_id
(int) - Order IDorder_increment_id
(string) - Order increment IDcreated_at
(string) - Creation datetotal_qty
(float) - Total quantitystore_id
(int) - Store ID
Example Request:
{
"jsonrpc": "2.0",
"method": "call",
"params": [
"session_id",
"sales_order_shipment.list",
[{"order_increment_id": "100000001"}]
],
"id": 1
}
Example Response:
{
"jsonrpc": "2.0",
"result": [
{
"increment_id": "100000001",
"shipment_id": 1,
"order_id": 1,
"order_increment_id": "100000001",
"created_at": "2023-01-16 10:30:45",
"total_qty": 2.0000,
"store_id": 1
}
],
"id": 1
}
Possible Errors:
filters_invalid
- Invalid filters provided
info¶
Retrieve detailed shipment information.
Method Name: sales_order_shipment.info
Parameters:
shipmentIncrementId
(string, required) - Shipment increment ID
Return:
- (object) - Shipment information with the following structure:
increment_id
(string) - Shipment increment IDshipment_id
(int) - Shipment IDorder_id
(int) - Order IDorder_increment_id
(string) - Order increment IDcreated_at
(string) - Creation datetotal_qty
(float) - Total quantitystore_id
(int) - Store IDshipping_address
(object) - Shipping address informationbilling_address
(object) - Billing address informationitems
(array) - Array of shipped itemstracks
(array) - Array of tracking informationcomments
(array) - Array of shipment comments
Example Request:
{
"jsonrpc": "2.0",
"method": "call",
"params": [
"session_id",
"sales_order_shipment.info",
"100000001"
],
"id": 1
}
Example Response:
{
"jsonrpc": "2.0",
"result": {
"increment_id": "100000001",
"shipment_id": 1,
"order_id": 1,
"order_increment_id": "100000001",
"created_at": "2023-01-16 10:30:45",
"total_qty": 2.0000,
"store_id": 1,
"shipping_address": {
"firstname": "John",
"lastname": "Doe",
"street": "123 Main St",
"city": "Anytown",
"region": "California",
"postcode": "12345",
"country_id": "US",
"telephone": "555-123-4567"
},
"billing_address": {
"firstname": "John",
"lastname": "Doe",
"street": "123 Main St",
"city": "Anytown",
"region": "California",
"postcode": "12345",
"country_id": "US",
"telephone": "555-123-4567"
},
"items": [
{
"item_id": 1,
"parent_id": 1,
"sku": "product123",
"name": "Test Product",
"qty": 2.0000,
"price": 70.00,
"weight": 1.00,
"order_item_id": 1
}
],
"tracks": [
{
"track_id": 1,
"parent_id": 1,
"track_number": "1Z12345E0291980793",
"title": "UPS",
"carrier_code": "ups",
"created_at": "2023-01-16 10:35:12"
}
],
"comments": [
{
"comment_id": 1,
"parent_id": 1,
"created_at": "2023-01-16 10:30:45",
"comment": "Shipment created"
}
]
},
"id": 1
}
Possible Errors:
shipment_not_exists
- Shipment does not exist
create¶
Create a new shipment for an order.
Method Name: sales_order_shipment.create
Parameters:
orderIncrementId
(string, required) - Order increment IDitemsQty
(array, optional) - Array of items to ship with quantities:order_item_id
(int) - Order item IDqty
(float) - Quantity to shipcomment
(string, optional) - Shipment commentemail
(boolean, optional) - Whether to send email notification (default: false)includeComment
(boolean, optional) - Whether to include comment in email (default: false)
Return:
- (string) - Shipment increment ID
Example Request:
{
"jsonrpc": "2.0",
"method": "call",
"params": [
"session_id",
"sales_order_shipment.create",
[
"100000001",
{"1": 2},
"Shipment created",
true,
true
]
],
"id": 1
}
Example Response:
Possible Errors:
order_not_exists
- Order does not existorder_not_shippable
- Order cannot be shippeddata_invalid
- Invalid data provided
addComment
¶
Add a comment to a shipment.
Method Name: sales_order_shipment.addComment
Parameters:
shipmentIncrementId
(string, required) - Shipment increment IDcomment
(string, required) - Comment textemail
(boolean, optional) - Whether to send email notification (default: false)includeInEmail
(boolean, optional) - Whether to include comment in email (default: false)
Return:
- (boolean) - True on success
Example Request:
{
"jsonrpc": "2.0",
"method": "call",
"params": [
"session_id",
"sales_order_shipment.addComment",
["100000001", "Package has been shipped", true, true]
],
"id": 1
}
Example Response:
Possible Errors:
shipment_not_exists
- Shipment does not exist
addTrack
¶
Add tracking information to a shipment.
Method Name: sales_order_shipment.addTrack
Parameters:
shipmentIncrementId
(string, required) - Shipment increment IDcarrier
(string, required) - Carrier codetitle
(string, required) - Carrier titletrackNumber
(string, required) - Tracking number
Return:
- (int) - Tracking ID
Example Request:
{
"jsonrpc": "2.0",
"method": "call",
"params": [
"session_id",
"sales_order_shipment.addTrack",
["100000001", "ups", "UPS", "1Z12345E0291980793"]
],
"id": 1
}
Example Response:
Possible Errors:
shipment_not_exists
- Shipment does not existdata_invalid
- Invalid data provided
removeTrack
¶
Remove tracking information from a shipment.
Method Name: sales_order_shipment.removeTrack
Parameters:
shipmentIncrementId
(string, required) - Shipment increment IDtrackId
(int, required) - Tracking ID
Return:
- (boolean) - True on success
Example Request:
{
"jsonrpc": "2.0",
"method": "call",
"params": [
"session_id",
"sales_order_shipment.removeTrack",
["100000001", 1]
],
"id": 1
}
Example Response:
Possible Errors:
shipment_not_exists
- Shipment does not existtrack_not_exists
- Tracking information does not exist
sendInfo
¶
Send shipment information to the customer.
Method Name: sales_order_shipment.sendInfo
Parameters:
shipmentIncrementId
(string, required) - Shipment increment IDcomment
(string, optional) - Comment to include in the email
Return:
- (boolean) - True on success
Example Request:
{
"jsonrpc": "2.0",
"method": "call",
"params": [
"session_id",
"sales_order_shipment.sendInfo",
["100000001", "Your order has been shipped"]
],
"id": 1
}
Example Response:
Possible Errors:
shipment_not_exists
- Shipment does not exist
getCarriers
¶
Get list of available shipping carriers.
Method Name: sales_order_shipment.getCarriers
Parameters:
orderIncrementId
(string, required) - Order increment ID
Return:
- (object) - Object with carrier codes as keys and carrier titles as values
Example Request:
{
"jsonrpc": "2.0",
"method": "call",
"params": [
"session_id",
"sales_order_shipment.getCarriers",
"100000001"
],
"id": 1
}
Example Response:
{
"jsonrpc": "2.0",
"result": {
"ups": "United Parcel Service",
"usps": "United States Postal Service",
"fedex": "Federal Express",
"dhl": "DHL"
},
"id": 1
}
Possible Errors:
order_not_exists
- Order does not exist