Zoey REST API reference ยท Interactive version: apidocs.zoey.com

Orders

Orders: Items

Get

GET https://container-url.zoeysite.com/api/rest/orders/:orderId/items?limit=10&page=1&order=item_id&dir=DESC&filter[0][attribute]=product_id&filter[0][eq]=1

Query parameters:

NameExampleNotes
limit10Limit the amount of results returned. (Optional. Default 10)
page1Paginate the limit. (Optional)
orderitem_idUsed to sort by property. (Optional)
dirDESCUsed to sort by direction. (Optional)
filter[0][attribute]product_idUsed to filter results by property. (Optional)
filter[0][eq]1Used to filter results by action/value. (Optional)

Example response (Get), HTTP 200:

[
    {
        "item_id": "54026",
        "parent_item_id": null,
        "product_id": "68679",
        "product_type": "simple",
        "sku": "dummy-configurable-15",
        "name": "dummy-configurable-15 Large-Red",
        "qty_canceled": "0.0000",
        "qty_invoiced": "0.0000",
        "qty_ordered": "6.0000",
        "qty_refunded": "0.0000",
        "qty_shipped": "0.0000",
        "price": "10.0000",
        "base_price": "10.0000",
        "original_price": "10.0000",
        "base_original_price": "10.0000",
        "tax_percent": "10.0000",
        "tax_amount": "6.0000",
        "base_tax_amount": "6.0000",
        "discount_amount": "0.0000",
        "base_discount_amount": "0.0000",
        "row_total": "60.0000",
        "base_row_total": "60.0000",
        "price_incl_tax": "11.0000",
        "base_price_incl_tax": "11.0000",
        "row_total_incl_tax": "66.0000",
        "base_row_total_incl_tax": "66.0000",
        "qty_to_cancel": 6,
        "qty_to_invoice": 6,
        "qty_to_refund": 0,
        "qty_to_ship": 6,
        "qty_billed": 6,
        "qty_to_bill": 0
    },
    {
        "item_id": "54027",
        "parent_item_id": null,
        "product_id": "68678",
        "product_type": "simple",
        "sku": "dummy-configurable-14",
        "name": "dummy-configurable-14 Large-Yellow",
        "qty_canceled": "0.0000",
        "qty_invoiced": "0.0000",
        "qty_ordered": "6.0000",
        "qty_refunded": "0.0000",
        "qty_shipped": "0.0000",
        "price": "10.0000",
        "base_price": "10.0000",
        "original_price": "10.0000",
        "base_original_price": "10.0000",
        "tax_percent": "10.0000",
        "tax_amount": "6.0000",
        "base_tax_amount": "6.0000",
        "discount_amount": "0.0000",
        "base_discount_amount": "0.0000",
        "row_total": "60.0000",
        "base_row_total": "60.0000",
        "price_incl_tax": "11.0000",
        "base_price_incl_tax": "11.0000",
        "row_total_incl_tax": "66.0000",
        "base_row_total_incl_tax": "66.0000",
        "qty_to_cancel": 6,
        "qty_to_invoice": 6,
        "qty_to_refund": 0,
        "qty_to_ship": 6,
        "qty_billed": 6,
        "qty_to_bill": 0
    },
    {
        "item_id": "54028",
        "parent_item_id": null,
        "product_id": "68677",
        "product_type": "simple",
        "sku": "dummy-configurable-13",
        "name": "dummy-configurable-13 Large-Green",
        "qty_canceled": "0.0000",
       
... (truncated)

Cancel Items

POST https://container-url.zoeysite.com/api/rest/sales2/order/cancelItems

This endpoint allows for Canceling individual Item Quantities on an Order. Note that if canceling all items on an Order that the entire Order will be canceled.

Upon successful completion, a comment will be added to the Order indicating items have been canceled. This comment will not be visible to the customer who placed the Order.

Item Quantities that have already been Invoiced/Shipped cannot be canceled.

Items cannot be Canceled for Orders that are in the complete, closed, or canceled state.

Param Type Notes Required
order_id integer The internal ID of the Order object. Note that this is not the customer facing Order Number. Yes
reason string The reason why the items are being canceled. This will be included in the Order comment indicating items have been canceled. Yes
return_to_stock integer 1/0 flag indicating if the canceled quantity should be returned to stock. No
items Array of Item Yes

Item

Param Type Notes Required
item_id integer The unique ID for this Order Item. This value can be found in the item_id field when retrieving an Order with the API Yes
qty_to_cancel float The quantity to cancel. Note that this cannot be greater than the quantity ordered for the item. Yes
uses_packages integer 1/0 flag indicating if the item uses packaging. No
package_info PackageInfo When uses_packages is 1, provide the package_info column to specify the multiplier. No

PackageInfo

Param Type Notes Required
increment float The qty_to_cancel will be multiplied by this value when canceling an item that uses packaging Yes

Example request body:

[
    {
        "order_id": 27471,
        "reason": "Reason for Cancelling Items",
        "return_to_stock": 1,
        "items": [
            {
                "item_id": 103949,
                "qty_to_cancel": 2,
                "uses_packages": 0
            }
        ]
    }
]

Example response (Cancel Items Success), HTTP 200:

{
    "result": {
        "status": {
            "success": 1,
            "details": [
                {
                    "type": "success",
                    "code": "Items Canceled",
                    "message": "",
                    "detail": ""
                }
            ]
        },
        "data": []
    }
}

Example response (Cancel Items Success - Packages), HTTP 200:

{
    "result": {
        "status": {
            "success": 1,
            "details": [
                {
                    "type": "success",
                    "code": "Items Canceled",
                    "message": "",
                    "detail": ""
                }
            ]
        },
        "data": []
    }
}

Example response (Cancel Items Error - Invalid QTY), HTTP 500:

{
    "messages": {
        "error": [
            {
                "code": 500,
                "message": "SOCI-E-003-03: Invalid Cancel Quantities:\nCannot cancel Quantity 4 for Simple-Alpha (103949). Maximum Cancel Quantity is 2"
            }
        ]
    }
}

Example response (Cancel Items Error - Order Canceled), HTTP 500:

{
    "messages": {
        "error": [
            {
                "code": 500,
                "message": "SOCI-E-001: Cannot cancel Items for Order 120023033 because the Order Status is Canceled (canceled)"
            }
        ]
    }
}

Add Items

POST https://container-url.zoeysite.com/api/rest/orders/:orderid/add-items

Request Fields:

Field Type Required Description
items array Yes Array of items to add
items[].product_id integer Yes Product entity ID
items[].qty number Yes Quantity to add
items[].price number No Custom price per unit (uses catalog price if not provided)
items[].variation_id integer No Variation product ID (for configurable products)
items[].customizations object No Product customizations (option_id => value)
items[].unique_in_quote integer No Controls merge behavior. 0 (default) = merge with existing matching item. Non-zero = force new line item.
items[].use_discount integer No Whether discounts apply to this item (default: 1)
items[].uses_markdown integer No Markdown pricing flag
items[].comment string No Item-level comment
items[].attachments mixed No Item attachments
items[].option_inventory_location mixed No Inventory location data
preview boolean No If true, returns what the order would look like without saving changes (dry-run)

Error Responses:

Code Description Example
400 Bad Request - Validation error "Items array is required."
400 Product not found "Product with SKU 'X' does not exist."
400 Order in finished state "Cannot add items to order in complete state."
400 Negative/zero price "Price must be greater than 0 for item X." (code: ORDEDIT-INPUT-ERROR-CODE-001)
400 Negative quantity "Quantity must be greater than 0 for item X." (code: ORDEDIT-INPUT-ERROR-CODE-002)
400 Extreme quantity "Quantity cannot exceed 10,000 for item X." (code: ORDEDIT-INPUT-ERROR-CODE-002)
400 Configurable without variation "Configurable product X requires a variation_id."
401 Unauthorized "Invalid authentication credentials."
404 Order not found "Order not found."

Example request body:

{
    "items": [
        {
            "product_id": 123,
            "qty": 2,
            "price": 25,
            "variation_id": 790,
            "customizations": {
                "100": "Custom Text",
                "101": "Blue"
            }
        }
    ]
}

Example response (Add Items), HTTP 200:

{
    "success": true,
    "order_id": "12345",
    "increment_id": "200000123",
    "subtotal": "140.0000",
    "tax_amount": "10.0000",
    "shipping_amount": "0.0000",
    "discount_amount": "0.0000",
    "grand_total": "150.0000",
    "total_item_count": "5",
    "history": [
        {
            "id": 123,
            "status": "pending",
            "comment": "API User ID: 1\nThe following items were added to the Order: ...",
            "created_at": "2026-01-30 14:30:00",
            "is_customer_notified": false,
            "is_visible_on_front": false
        }
    ]
}

Edit Items

POST https://container-url.zoeysite.com/api/rest/orders/:orderid/edit-items

Request Fields:

Field Type Required Description
items array Yes Array of items to edit
items[].item_id integer Preferred Order item ID (most explicit - use this if available)
items[].sku string Alternative Product SKU (fallback - matches first item with this SKU)
items[].product_id integer Legacy Product entity ID (legacy support - matches first item)
items[].qty number No New quantity (for sparse update)
items[].price number No New price per unit (for sparse update)
preview boolean No If true, returns what the order would look like without saving changes (dry-run)

When the same product exists multiple times on an order (e.g., with different prices or delivery dates), you must use item_id to specify which item to edit. The sku and product_id options will match the first item only.

Error Responses:

Code Description Example
400 Order has bills "Cannot edit items on Order 200000123 because it has Open and/or Paid bills."
400 Order has shipments "Cannot edit items on Order because it has shipments."
400 Product not on order "Product 'SKU-123' does not exist on order."
400 Multiple items, use item_id "Multiple items with SKU 'ABC-123'. Use item_id instead."
400 No changes detected "No changes detected. All items have the same quantity and price as the current order."
400 Negative/zero price "Price must be greater than 0 for item X." (code: ORDEDIT-INPUT-ERROR-CODE-001)
400 Negative quantity "Quantity must be greater than 0 for item X." (code: ORDEDIT-INPUT-ERROR-CODE-002)
400 Extreme quantity "Quantity cannot exceed 10,000 for item X." (code: ORDEDIT-INPUT-ERROR-CODE-002)
400 Zero quantity "Use remove-items endpoint to remove item from order." (code: ORDEDIT-EDIT-ERROR-CODE-014)
401 Unauthorized "Invalid authentication credentials."
404 Order not found "Order not found."

Example request body:

{
    "items": [
        {
            "item_id": 3196,
            "qty": 5,
            "price": 22.5
        }
    ]
}

Example response (Edit Items), HTTP 200:

{
    "success": true,
    "order_id": "12345",
    "increment_id": "200000123",
    "subtotal": "140.0000",
    "tax_amount": "10.0000",
    "shipping_amount": "0.0000",
    "discount_amount": "0.0000",
    "grand_total": "150.0000",
    "total_item_count": "5",
    "history": [
        {
            "id": 123,
            "status": "pending",
            "comment": "API User ID: 1\nThe following items were added to the Order: ...",
            "created_at": "2026-01-30 14:30:00",
            "is_customer_notified": false,
            "is_visible_on_front": false
        }
    ]
}

Remove Items

POST https://container-url.zoeysite.com/api/rest/orders/:orderid/remove-items

Request Fields:

Field Type Required Description
items array Conditional Array of items to remove. Required unless remove_additional_items is true.
items[].item_id integer Yes Order item ID (sales_flat_order_item.item_id)
items[].qty number No Quantity to remove (if not provided, removes entire item)
preview boolean No If true, returns what the order would look like without saving changes (dry-run)
remove_additional_items boolean No If true, automatically removes all items added via AddItems API (marked with is_additional_order_item flag)

Error Responses:

Code Description Example
400 Cannot remove last item "Cannot remove all items from order. Use cancel order instead."
400 Item partially shipped "Cannot remove item %s because %s units have been shipped."
400 Item partially invoiced "Cannot remove item %s because %s units have been invoiced."
400 No additional items "No additional order items found on this order."
400 Negative quantity "Quantity must be greater than 0 for item X." (code: ORDEDIT-INPUT-ERROR-CODE-002)
400 Extreme quantity "Quantity cannot exceed 10,000 for item X." (code: ORDEDIT-INPUT-ERROR-CODE-002)
401 Unauthorized "Invalid authentication credentials."
404 Order not found "Order not found."

Example request body:

{
    "items": [
        {
            "item_id": 456,
            "qty": 2
        }
    ],
    "preview": false,
    "remove_additional_items": false
}

Example response (Remove Items), HTTP 200:

{
    "success": true,
    "order_id": "12345",
    "increment_id": "200000123",
    "subtotal": "75.0000",
    "tax_amount": "5.0000",
    "shipping_amount": "0.0000",
    "discount_amount": "0.0000",
    "grand_total": "80.0000",
    "total_item_count": "2",
    "history": [...]
}

Example response (Remove Items Preview), HTTP 200:

{
    "success": true,
    "order_id": "12345",
    "increment_id": "200000123",
    "subtotal": "75.0000",
    "tax_amount": "5.0000",
    "shipping_amount": "0.0000",
    "discount_amount": "0.0000",
    "grand_total": "80.0000",
    "total_item_count": "2",
    "preview": true,
    "preview_data": {
        "original_grand_total": "130.00",
        "new_grand_total": "80.00",
        "items_affected": 1
    }
}

Versions

POST https://container-url.zoeysite.com/api/rest/orders/:orderid/versions

Request Fields:

Field Type Required Description
items array Conditional Array of items to remove. Required unless remove_additional_items is true.
items[].item_id integer Yes Order item ID (sales_flat_order_item.item_id)
items[].qty number No Quantity to remove (if not provided, removes entire item)
preview boolean No If true, returns what the order would look like without saving changes (dry-run)
remove_additional_items boolean No If true, automatically removes all items added via AddItems API (marked with is_additional_order_item flag)

Error Responses:

Code Description Example
400 Cannot remove last item "Cannot remove all items from order. Use cancel order instead."
400 Item partially shipped "Cannot remove item %s because %s units have been shipped."
400 Item partially invoiced "Cannot remove item %s because %s units have been invoiced."
400 No additional items "No additional order items found on this order."
400 Negative quantity "Quantity must be greater than 0 for item X." (code: ORDEDIT-INPUT-ERROR-CODE-002)
400 Extreme quantity "Quantity cannot exceed 10,000 for item X." (code: ORDEDIT-INPUT-ERROR-CODE-002)
401 Unauthorized "Invalid authentication credentials."
404 Order not found "Order not found."

Example response (Versions), HTTP 200:

[
    {
        "id": 5,
        "order_id": 12345,
        "version": 3,
        "created_at": "2026-01-30 14:30:00",
        "created_by": 1,
        "source": "api",
        "comment": "Items edited via API",
        "order_snapshot": {
            "grand_total": "150.00",
            "items": [...]
        }
    },
    {
        "id": 4,
        "order_id": 12345,
        "version": 2,
        "created_at": "2026-01-29 10:00:00",
        "created_by": 1,
        "source": "api",
        "comment": "Items added via API",
        "order_snapshot": {
            "grand_total": "100.00",
            "items": [...]
        }
    }
]

Version

POST https://container-url.zoeysite.com/api/rest/orders/:orderid/versions/:version

Error Responses:

Code Description Example
400 Version required "Version is required."
404 Version not found "Version not found for this order."

Example response (Version), HTTP 200:

{
    "id": 5,
    "order_id": 12345,
    "version": 3,
    "created_at": "2026-01-30 14:30:00",
    "created_by": 1,
    "source": "api",
    "comment": "Items edited via API",
    "order_snapshot": {
        "grand_total": "150.00",
        "subtotal": "140.00",
        "tax_amount": "10.00",
        "shipping_amount": "0.00",
        "items": [
            {
                "item_id": 456,
                "product_id": 123,
                "sku": "ABC-123",
                "name": "Product Name",
                "qty": 5,
                "price": 28,
                "row_total": 140
            }
        ]
    }
}

Rollback Version

POST https://container-url.zoeysite.com/api/rest/orders/:orderid/versions/:version/rollback

Rollback Process:

  1. Creates a new snapshot of the current order state (for undo capability)

  2. Compares current items with snapshot items

  3. Removes items not in snapshot

  4. Edits items with changed qty/price

  5. Adds items that were in snapshot but not currently on order

  6. Handles customization changes (removes and re-adds items with different customizations)

Error Responses:

Code Description Example
400 Version required "Version is required."
404 Version not found "Version not found for this order."
423 Order locked "Order is currently locked and cannot be edited."

Example response (Rollback Version), HTTP 200:

{
  "success": true,
  "order_id": "12345",
  "increment_id": "200000123",
  "subtotal": "90.0000",
  "tax_amount": "0.0000",
  "shipping_amount": "0.0000",
  "discount_amount": "0.0000",
  "grand_total": "100.0000",
  "total_item_count": "2",
  "history": [...]
}