# Submit an order / advance its state

Moves an order to the next step of its workflow (or to `order_state_id` when given), reserving inventory and
sending the step's notifications. Orders created through `POST /v2/order` are submitted automatically; use this
for orders created with `remainInPreliminary: true` or by `POST /v1/order`.
Accepts user session headers only.

Endpoint: POST /v1/order/submit
Version: 1.19
Security: UserGuid, UserToken, SupplierGuid

## Security:

  - `UserGuid` (unknown)
    apiKey in header userGuid

  - `UserToken` (unknown)
    apiKey in header userToken

  - `SupplierGuid` (unknown)
    apiKey in header supplierGuid

## Header parameters:

  - `vendorGuid` (string)
    GUID of the customer (vendor) to act for. With API key authentication this selects the customer context; with user session headers it is the vendor the user is acting on behalf of.

## Request fields (application/json):

  - `orderGuid` (string, required)

  - `order_state_id` (integer)
    Target workflow state. Defaults to the next step in the order's workflow.

  - `stateChangeNote` (string)
    Note shown to the customer with the state change.

  - `stateChangeInternalNote` (string)

  - `skipInventoryCheck` (boolean)

  - `allowPartialFulfillment` (boolean)
    When true, reserve what is available and auto-create a backorder for the rest. When false, backorder the whole order if anything is short. When omitted, allocate what is available without creating a backorder.

  - `useHeldInventory` (boolean)
    Draw from inventory held for backorders before on-hand stock.

  - `skipPendingItemsCheck` (boolean)

  - `pendingItemsAction` (string)
    What to do with pending backorder lines when moving into a release state.
    Enum: "backorder", "remove", "zero_out"

  - `customMessage` (string)
    Custom text merged into the outbound email for steps that allow it.

  - `override_min_order_total` (boolean)
    Submit even when the order is below the supplier's minimum order total. Honored only for supplier admins (and API keys, which act as the supplier's master user); ignored for other staff and customer users.

## Response 200:

  - `200` (unknown)
    The order after the transition.

## Response 200 fields (application/json):

  - `order` (object, required)
    A sales order. `GET /v1/orders` returns a reduced projection (the header fields plus id/guid/name of each related record); the single-order and create endpoints return the full model with all relations.

  - `order.id` (integer)

  - `order.guid` (string)

  - `order.name` (string)
    Order number as displayed, e.g. `ABC-10000`.

  - `order.api_guid` (string)
    Client-supplied idempotency key, when the order was created through the API.

  - `order.supplier_id` (integer)

  - `order.vendor_id` (integer)

  - `order.user_id` (integer)

  - `order.catalog_id` (integer)

  - `order.price_group_id` (integer)

  - `order.category_id` (integer)

  - `order.parent_order_id` (integer)

  - `order.client_id` (integer)

  - `order.project_id` (integer)

  - `order.sales_rep_id` (integer)

  - `order.ship_to_id` (integer)

  - `order.order_state_id` (integer)
    Current workflow state id (1 = PRELIMINARY, 2 = SUBMITTED, 8 = SHIPPED, 9 = COMPLETED, 23 = CANCELLED, ...).

  - `order.order_source_id` (integer)
    Origin of the order (1 = ORDERWERKS, 20 = OTHER, 21 = APP, ...).

  - `order.po_no` (string)

  - `order.invoice_no` (string)

  - `order.description` (string)

  - `order.note` (string)

  - `order.internal_note` (string)

  - `order.shipping_instructions` (string)

  - `order.is_quote` (boolean)

  - `order.is_sample` (boolean)

  - `order.is_local_pickup` (boolean)

  - `order.is_local_delivery` (boolean)

  - `order.is_shipped` (boolean)

  - `order.partially_shipped` (boolean)

  - `order.is_on_hold` (boolean)

  - `order.is_cancelled` (boolean)

  - `order.sub_total` (number)

  - `order.tax` (number)

  - `order.shipping` (number)

  - `order.labor` (number)

  - `order.discount` (number)

  - `order.discount_total` (number)

  - `order.other` (number)

  - `order.grand_total` (number)

  - `order.delivery_date` (string)

  - `order.ship_date` (string)

  - `order.do_not_ship_before_date` (string)

  - `order.created_at` (string)

  - `order.updated_at` (string)

  - `order.Order_Items` (array)

  - `order.Order_Items.id` (integer)

  - `order.Order_Items.guid` (string)

  - `order.Order_Items.order_id` (integer)

  - `order.Order_Items.catalog_item_id` (integer)

  - `order.Order_Items.catalog_item_guid` (string)

  - `order.Order_Items.parent_order_item_id` (integer)

  - `order.Order_Items.item_no` (integer)
    Line number within the order.

  - `order.Order_Items.sku` (string)

  - `order.Order_Items.name` (string)

  - `order.Order_Items.description` (string)

  - `order.Order_Items.qty` (number)
    Quantity ordered. Never reduced by shipments.

  - `order.Order_Items.qty_shipped` (number)

  - `order.Order_Items.qty_backordered` (number)

  - `order.Order_Items.qty_pending` (number)

  - `order.Order_Items.qty_reserved` (number)

  - `order.Order_Items.is_manual_price` (boolean)

  - `order.Order_Items.list_price_frozen` (number)
    Unit price captured when the line was created.

  - `order.Order_Items.net_price` (number)

  - `order.Order_Items.discount` (number)

  - `order.Order_Items.discount_total` (number)

  - `order.Order_Items.tax` (number)

  - `order.Order_Items.total` (number)

  - `order.Order_Items.is_credit` (boolean)

  - `order.Order_Items.is_backordered` (boolean)

  - `order.Order_Items.note` (string)

  - `order.Order_Items.width` (number)

  - `order.Order_Items.height` (number)

  - `order.Order_Items.depth` (number)

  - `order.Order_Items.selected_options` (array)

  - `order.Order_Items.Catalog_Item` (object)
    A product. With API key authentication the paged list endpoint returns exactly the fields below; other endpoints (and user session calls) return the full model, which has many more optional fields.

  - `order.Order_Items.Catalog_Item.id` (integer)

  - `order.Order_Items.Catalog_Item.guid` (string)

  - `order.Order_Items.Catalog_Item.catalog_id` (integer)

  - `order.Order_Items.Catalog_Item.category_id` (integer)

  - `order.Order_Items.Catalog_Item.sku` (string)

  - `order.Order_Items.Catalog_Item.upc` (string)

  - `order.Order_Items.Catalog_Item.name` (string)

  - `order.Order_Items.Catalog_Item.description` (string)

  - `order.Order_Items.Catalog_Item.manufacturer` (string)

  - `order.Order_Items.Catalog_Item.color` (string)

  - `order.Order_Items.Catalog_Item.style` (string)

  - `order.Order_Items.Catalog_Item.active` (boolean)

  - `order.Order_Items.Catalog_Item.is_taxable` (boolean)

  - `order.Order_Items.Catalog_Item.msrp` (number)

  - `order.Order_Items.Catalog_Item.cost_per_uom` (number)
    Supplier cost. Omitted for customer (vendor) users.

  - `order.Order_Items.Catalog_Item.pricing` (object)
    Price per price group, keyed by price group name. `"N/A"` means not offered to that group.
    Example: {"Retail":99.99,"Wholesale":79.99,"Distributor":"N/A"}

  - `order.Order_Items.Catalog_Item.has_inventory` (boolean)
    Whether stock is tracked for this item.

  - `order.Order_Items.Catalog_Item.qty_on_hand` (number)

  - `order.Order_Items.Catalog_Item.qty_incoming` (number)

  - `order.Order_Items.Catalog_Item.reserved_qty_on_hand` (number)

  - `order.Order_Items.Catalog_Item.qty_backordered` (number)

  - `order.Order_Items.Catalog_Item.qty_held_for_backorders` (number)

  - `order.Order_Items.Catalog_Item.min_qty_on_hand` (number)

  - `order.Order_Items.Catalog_Item.max_qty_on_hand` (number)

  - `order.Order_Items.Catalog_Item.min_order_qty` (number)

  - `order.Order_Items.Catalog_Item.allow_backorder` (boolean)

  - `order.Order_Items.Catalog_Item.qty_break` (number)
    Quantity at which `qty_break_price` applies.

  - `order.Order_Items.Catalog_Item.qty_break_price` (number)

  - `order.Order_Items.Catalog_Item.has_serials` (boolean)

  - `order.Order_Items.Catalog_Item.has_lots` (boolean)

  - `order.Order_Items.Catalog_Item.has_exp_date` (boolean)

  - `order.Order_Items.Catalog_Item.width` (number)

  - `order.Order_Items.Catalog_Item.height` (number)

  - `order.Order_Items.Catalog_Item.depth` (number)

  - `order.Order_Items.Catalog_Item.item_weight` (number)

  - `order.Order_Items.Catalog_Item.shipping_weight` (number)

  - `order.Order_Items.Catalog_Item.is_product_group` (boolean)

  - `order.Order_Items.Catalog_Item.product_group_type` (string)
    Enum: "flat", "multi", "null"

  - `order.Order_Items.Catalog_Item.product_group_display_style` (string)

  - `order.Order_Items.Catalog_Item.group_parent_catalog_item_id` (integer)

  - `order.Order_Items.Catalog_Item.group_sequence` (integer)

  - `order.Order_Items.Catalog_Item.group_title` (string)

  - `order.Order_Items.Catalog_Item.subsection_id` (integer)

  - `order.Order_Items.Catalog_Item.third_party_sku` (string)

  - `order.Order_Items.Catalog_Item.third_party_pricing` (string)

  - `order.Order_Items.Catalog_Item.third_party_size` (string)

  - `order.Order_Items.Catalog_Item.Category` (object)

  - `order.Order_Items.Catalog_Item.Category.id` (integer)

  - `order.Order_Items.Catalog_Item.Category.guid` (string)

  - `order.Order_Items.Catalog_Item.Category.catalog_id` (integer)

  - `order.Order_Items.Catalog_Item.Category.parent_category_id` (integer)

  - `order.Order_Items.Catalog_Item.Category.name` (string)

  - `order.Order_Items.Catalog_Item.Category.sequence` (integer)

  - `order.Order_Items.Catalog_Item.Category.hide_category` (boolean)

  - `order.Order_Items.Catalog_Item.Category.created_at` (string)

  - `order.Order_Items.Catalog_Item.Category.updated_at` (string)

  - `order.Order_Items.Catalog_Item.CategoryHierarchy` (array)
    Root-to-leaf category path, when category retrieval is not skipped.

  - `order.Order_Items.Catalog_Item.created_at` (string)

  - `order.Order_Items.Catalog_Item.updated_at` (string)

  - `order.Order_Items.Catalog_Item.deleted_at` (string)
    Present only in delta-sync responses for soft-deleted items.

  - `order.Order_Items.created_at` (string)

  - `order.Order_Items.updated_at` (string)

  - `order.Ship_To` (object)
    A billing or shipping address. Additional internal fields may be present.

  - `order.Ship_To.id` (integer)

  - `order.Ship_To.guid` (string)

  - `order.Ship_To.vendor_id` (integer)

  - `order.Ship_To.order_id` (integer)

  - `order.Ship_To.name` (string)
    Contact name at this address.

  - `order.Ship_To.company_name` (string)

  - `order.Ship_To.address_line_one` (string)

  - `order.Ship_To.address_line_two` (string)

  - `order.Ship_To.address_line_three` (string)

  - `order.Ship_To.city` (string)

  - `order.Ship_To.state` (string)

  - `order.Ship_To.postal_code` (string)

  - `order.Ship_To.country` (string)

  - `order.Ship_To.phone` (string)

  - `order.Ship_To.fax` (string)

  - `order.Ship_To.email` (string)

  - `order.Ship_To.note` (string)

  - `order.Ship_To.address_internal_id` (string)
    Your own identifier for this address, if one was supplied.

  - `order.Ship_To.is_vendor_main_ship_to` (boolean)

  - `order.Ship_To.verified` (boolean)
    True when the address was verified against a postal database.

  - `order.Ship_To.lat` (number)

  - `order.Ship_To.lng` (number)

  - `order.Ship_To.created_at` (string)

  - `order.Ship_To.updated_at` (string)

  - `order.Vendor` (object)
    A customer of the supplier. The full model includes many integration-specific fields (QuickBooks, Stripe, FastBound, routing); only the commonly used ones are listed here.

  - `order.Vendor.id` (integer)

  - `order.Vendor.guid` (string)

  - `order.Vendor.supplier_id` (integer)

  - `order.Vendor.parent_vendor_id` (integer)

  - `order.Vendor.customer_internal_id` (string)
    Your own identifier for this customer.

  - `order.Vendor.name` (string)

  - `order.Vendor.email` (string)

  - `order.Vendor.shipping_email` (string)

  - `order.Vendor.phone` (string)

  - `order.Vendor.cell` (string)

  - `order.Vendor.fax` (string)

  - `order.Vendor.address_line_one` (string)

  - `order.Vendor.address_line_two` (string)

  - `order.Vendor.city` (string)

  - `order.Vendor.state` (string)

  - `order.Vendor.postal_code` (string)

  - `order.Vendor.country` (string)

  - `order.Vendor.active` (boolean)

  - `order.Vendor.tax_exempt` (boolean)

  - `order.Vendor.resale_tax_id` (string)

  - `order.Vendor.lock_catalog_id` (integer)
    When set, the customer can only order from this catalog.

  - `order.Vendor.price_group_id` (integer)
    Price group used for this customer's pricing.

  - `order.Vendor.payment_type_id` (integer)

  - `order.Vendor.payment_term_id` (integer)

  - `order.Vendor.require_payment` (boolean)

  - `order.Vendor.credit_limit` (number)

  - `order.Vendor.open_balance` (number)

  - `order.Vendor.is_ecomm_user` (boolean)
    True for Orderwerks Online (e-commerce) customers.

  - `order.Vendor.net_term_ecomm_user` (boolean)

  - `order.Vendor.require_po` (boolean)

  - `order.Vendor.standing_po` (string)

  - `order.Vendor.hide_pricing` (boolean)

  - `order.Vendor.currency_id` (integer)

  - `order.Vendor.notes` (string)

  - `order.Vendor.default_order_category_id` (integer)

  - `order.Vendor.route_id` (integer)

  - `order.Vendor.route_stop_order` (integer)
    Standing stop order of the customer on its route; null = unordered (sorts last, by name).

  - `order.Vendor.timezone` (string)

  - `order.Vendor.bill_to_id` (integer)

  - `order.Vendor.ship_to_id` (integer)

  - `order.Vendor.created_at` (string)

  - `order.Vendor.updated_at` (string)

  - `order.Vendor.deleted_at` (string)
    Present only in delta-sync responses for soft-deleted customers.

  - `order.Catalog` (object)

  - `order.Catalog.id` (integer)

  - `order.Catalog.guid` (string)

  - `order.Catalog.supplier_id` (integer)

  - `order.Catalog.name` (string)
    Example: Main Catalog

  - `order.Catalog.email` (string)

  - `order.Catalog.version` (string)

  - `order.Catalog.active` (boolean)

  - `order.Catalog.order_item_type_id` (integer)

  - `order.Catalog.currency_id` (integer)

  - `order.Catalog.order_prefix_override` (string)
    Prefix used for order numbers created from this catalog, if overridden.

  - `order.Catalog.last_inventory_update` (string)

  - `order.Catalog.Price_Groups` (array)

  - `order.Catalog.Price_Groups.id` (integer)

  - `order.Catalog.Price_Groups.guid` (string)

  - `order.Catalog.Price_Groups.catalog_id` (integer)

  - `order.Catalog.Price_Groups.value` (string)
    Price group name. This is the key used in a catalog item's `pricing` object.
    Example: Wholesale

  - `order.Catalog.Price_Groups.is_main` (boolean)

  - `order.Catalog.Price_Groups.percentage` (number)

  - `order.Catalog.Price_Groups.price_upcharge_type_id` (integer)

  - `order.Catalog.Price_Groups.created_at` (string)

  - `order.Catalog.Price_Groups.updated_at` (string)

  - `order.Catalog.Price_Groups.deleted_at` (string)

  - `order.Catalog.created_at` (string)

  - `order.Catalog.updated_at` (string)

  - `order.Order_State` (object)

  - `order.Order_State.id` (integer)

  - `order.Order_State.guid` (string)

  - `order.Order_State.name` (string)

  - `order.User` (object)
    User who created the order.

  - `order.User.id` (integer)

  - `order.User.guid` (string)

  - `order.User.name` (string)

  - `order.User.email` (string)

  - `order.Supplier` (object)

  - `order.Supplier.id` (integer)

  - `order.Supplier.guid` (string)

  - `order.Supplier.name` (string)

  - `order.Supplier.email` (string)

  - `order.Client` (object)
    End client on behalf of whom the customer placed the order, if any.

  - `order.Client.id` (integer)

  - `order.Client.guid` (string)

  - `order.Client.name` (string)

  - `order.Parent_Order` (object)

  - `order.Parent_Order.id` (integer)

  - `order.Parent_Order.guid` (string)

  - `order.Parent_Order.name` (string)

  - `order.Order_Detail` (object)
    Supplier-specific extra fields.

  - `order.Order_State_Logs` (array)
    State transition history.

  - `order.Order_State_Logs.created_at` (string)

  - `order.Order_State_Logs.User` (object)

  - `order.Order_State_Logs.User.name` (string)

  - `order.Order_State_Logs.User.email` (string)

  - `order.Order_State_Logs.Order_State` (object)

  - `order.Order_State_Logs.Order_State.name` (string)

  - `order.Assigned_Users` (array)

  - `order.Assigned_Users.id` (integer)

  - `order.Assigned_Users.guid` (string)

  - `order.Assigned_Users.name` (string)

  - `order.Assigned_Users.email` (string)

  - `autoFulfilledItems` (array)
    Pending backorder lines that were fulfilled from stock during a release transition.

  - `autoFulfilledItems.orderItemId` (integer)

  - `autoFulfilledItems.catalogItemName` (string)

  - `autoFulfilledItems.catalogItemSku` (string)

  - `autoFulfilledItems.qtyFulfilled` (number)

  - `autoFulfilledItems.qtyFromHeld` (number)

  - `autoFulfilledItems.qtyFromOnHand` (number)

## Response 400:

  - `400` (unknown)
    Missing credentials or `orderGuid` (plain-text body `Invalid API Payload`).

## Response 422:

  - `422` (unknown)
    The transition is blocked (insufficient inventory, backorder limit, pending items on release, serials not assigned, or the order is below the supplier's minimum order total).

## Response 422 fields (application/json):

  - `success` (boolean, required)
    Example: false

  - `errorType` (string)
    Present for `PendingItemsOnRelease` and `SerialsNotAssigned`.
    Enum: "PendingItemsOnRelease", "SerialsNotAssigned"

  - `message` (string, required)

  - `items` (array)
    The lines that blocked the transition.

  - `errorType` (string, required)
    Enum: "MinOrderTotalNotMet"

  - `errorCode` (string, required)
    Enum: "MIN_ORDER_TOTAL_NOT_MET"

  - `basis` (string)
    Which subtotal was compared. `after_discounts` subtracts the order discount and the promo code discount; `before_discounts` does not. Tax and shipping never count.
    Enum: "before_discounts", "after_discounts"

  - `minimum` (number, required)
    Example: 500

  - `subtotal` (number, required)
    The subtotal that was compared.
    Example: 420

  - `shortfall` (number, required)
    Example: 80

  - `currency` (string, required)
    Example: USD

  - `vendorCurrency` (string)
    Example: CAD

  - `convertedMinimum` (number)

  - `convertedSubtotal` (number)

  - `convertedShortfall` (number)

## Response 500:

  - `500` (unknown)
    Unexpected server error. Some legacy endpoints return the message as `text/plain` instead of JSON.

## Response 500 fields (application/json):

  - `message` (string, required)
    Human-readable error message.
    Example: Invalid Catalog GUID

  - `error` (string)
    Underlying error detail, when available.

  - `code` (string)
    Machine-readable code for specific failures (for example `INVALID_DELTA_CURSOR`).