Skip to content
/
Create an order (with opt...

Create an order (with optional new customer)

Request

Creates an order with its lines, optionally creating the customer in the same call (newVendor* fields). Used by the Orderwerks mobile sales app; also available to integrators with an API key.

Before anything is written the request is validated: the customer must be active and accessible, and every line's item must be active with enough inventory. Failures come back as 400 with a ReconcileErrors body.

Idempotent on order.api_guid: a retry with the same key returns the existing order (and the customer / address / contact references) instead of creating a duplicate.

Security
(ApiKey and ApiSecret) or (UserGuid and UserToken and SupplierGuid)
Headers
vendorGuidstring, (uuid)

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.

userGuidstring, (uuid)

With API key authentication only: run the request as this user instead of the supplier's master user (the order is attributed to them). Ignored when user session headers are used, where it is part of the credentials.

Bodyapplication/jsonrequired
catalogGuidstring, (uuid)required
priceGroupGuidstring, (uuid)required
orderobject(OrderInput)required

Order header fields accepted on create.

orderItemsArray of objects, non-empty(OrderItemInput)required
orderDetailsobject

Supplier-specific extra order fields.

shipToobject(AddressInput)

Address fields accepted when creating or updating an address.

sourcestring or integer
One of:

Order source, as a name (OTHER, APP, ...) or its numeric id.

string
workflowGuidstring, (uuid)

Workflow to run the order through, for suppliers with multiple workflows. Defaults to the supplier's default workflow.

newVendorobject(VendorInput)

Customer fields accepted on create.

newVendorBillToobject(AddressInput)

Address fields accepted when creating or updating an address.

newVendorShipToobject(AddressInput)

Address fields accepted when creating or updating an address.

newVendorContactobject(VendorContactInput)
newVendorNotestring
remainInPreliminaryboolean

When true the order stays in PRELIMINARY. When omitted, the supplier setting "remain in preliminary" decides; when false the order is submitted.

utmobject

UTM attribution captured by the client, stamped onto the order.

curl -i -X POST \
  https://docs.orderwerks.com/_mock/openapi/v1/orderWithItems \
  -H 'Content-Type: application/json' \
  -H 'userGuid: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \
  -H 'vendorGuid: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \
  -H 'x-apiKey: YOUR_API_KEY_HERE' \
  -H 'x-apiSecret: YOUR_API_KEY_HERE' \
  -d '{
    "catalogGuid": "0f5a4b1e-1c9c-4d1a-9b8e-6f4a2a3c1d10",
    "priceGroupGuid": "9c8b7a6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "order": {
      "api_guid": "4c0d3e2a-8f7b-4c1e-9a6d-0b1c2d3e4f5a",
      "po_no": "PO-77812"
    },
    "orderItems": [
      {
        "catalog_item_id": 10432,
        "qty": 6
      }
    ],
    "newVendor": {
      "name": "New Retailer LLC",
      "email": "buyer@newretailer.example"
    },
    "newVendorShipTo": {
      "name": "Receiving",
      "address_line_one": "1 Main St",
      "city": "Anytown",
      "state": "CA",
      "postal_code": "12345",
      "country": "US"
    }
  }'

Responses

The created (or matched) order.

Bodyapplication/json
orderobject(Order)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.

vendorobject(Vendor)

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.

billToobject(EntityRef)

Minimal reference to a created record, so a client can back-fill its local rows.

shipToobject(EntityRef)

Minimal reference to a created record, so a client can back-fill its local rows.

contactobject(EntityRef)

Minimal reference to a created record, so a client can back-fill its local rows.

noteobject(EntityRef)

Minimal reference to a created record, so a client can back-fill its local rows.

Response
{
  "order": {
    "id": 0,
    "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
    "name": "string",
    "api_guid": "string",
    "supplier_id": 0,
    "vendor_id": 0,
    "user_id": 0,
    "catalog_id": 0,
    "price_group_id": 0,
    "category_id": 0,
    "parent_order_id": 0,
    "client_id": 0,
    "project_id": 0,
    "sales_rep_id": 0,
    "ship_to_id": 0,
    "order_state_id": 0,
    "order_source_id": 0,
    "po_no": "string",
    "invoice_no": "string",
    "description": "string",
    "note": "string",
    "internal_note": "string",
    "shipping_instructions": "string",
    "is_quote": true,
    "is_sample": true,
    "is_local_pickup": true,
    "is_local_delivery": true,
    "is_shipped": true,
    "partially_shipped": true,
    "is_on_hold": true,
    "is_cancelled": true,
    "sub_total": 0,
    "tax": 0,
    "shipping": 0,
    "labor": 0,
    "discount": 0,
    "discount_total": 0,
    "other": 0,
    "grand_total": 0,
    "delivery_date": "string",
    "ship_date": "string",
    "do_not_ship_before_date": "string",
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z",
    "Order_Items": [
      { … }
    ],
    "Ship_To": {
      "id": 0,
      "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
      "vendor_id": 0,
      "order_id": 0,
      "name": "string",
      "company_name": "string",
      "address_line_one": "string",
      "address_line_two": "string",
      "address_line_three": "string",
      "city": "string",
      "state": "string",
      "postal_code": "string",
      "country": "string",
      "phone": "string",
      "fax": "string",
      "email": "string",
      "note": "string",
      "address_internal_id": "string",
      "is_vendor_main_ship_to": true,
      "verified": true,
      "lat": 0,
      "lng": 0,
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z"
    },
    "Vendor": {
      "id": 0,
      "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
      "supplier_id": 0,
      "parent_vendor_id": 0,
      "customer_internal_id": "string",
      "name": "string",
      "email": "string",
      "shipping_email": "string",
      "phone": "string",
      "cell": "string",
      "fax": "string",
      "address_line_one": "string",
      "address_line_two": "string",
      "city": "string",
      "state": "string",
      "postal_code": "string",
      "country": "string",
      "active": true,
      "tax_exempt": true,
      "resale_tax_id": "string",
      "lock_catalog_id": 0,
      "price_group_id": 0,
      "payment_type_id": 0,
      "payment_term_id": 0,
      "require_payment": true,
      "credit_limit": 0,
      "open_balance": 0,
      "is_ecomm_user": true,
      "net_term_ecomm_user": true,
      "require_po": true,
      "standing_po": "string",
      "hide_pricing": true,
      "currency_id": 0,
      "notes": "string",
      "default_order_category_id": 0,
      "route_id": 0,
      "timezone": "string",
      "bill_to_id": 0,
      "ship_to_id": 0,
      "Bill_To": { … },
      "Ship_To": { … },
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "deleted_at": "2019-08-24T14:15:22Z"
    },
    "Catalog": {
      "id": 0,
      "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
      "supplier_id": 0,
      "name": "Main Catalog",
      "email": "string",
      "version": "string",
      "active": true,
      "order_item_type_id": 0,
      "currency_id": 0,
      "order_prefix_override": "string",
      "last_inventory_update": "2019-08-24T14:15:22Z",
      "Price_Groups": [ … ],
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z"
    },
    "Price_Group": {
      "id": 0,
      "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
      "catalog_id": 0,
      "value": "Wholesale",
      "is_main": true,
      "percentage": 0,
      "price_upcharge_type_id": 0,
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "deleted_at": "2019-08-24T14:15:22Z"
    },
    "Category": {
      "id": 0,
      "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
      "catalog_id": 0,
      "parent_category_id": 0,
      "name": "string",
      "sequence": 0,
      "hide_category": true,
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z"
    },
    "Order_State": {
      "id": 0,
      "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
      "name": "string"
    },
    "User": {
      "id": 0,
      "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
      "name": "string",
      "email": "string"
    },
    "Supplier": {
      "id": 0,
      "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
      "name": "string",
      "email": "string"
    },
    "Client": {
      "id": 0,
      "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
      "name": "string"
    },
    "Parent_Order": {
      "id": 0,
      "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
      "name": "string"
    },
    "Order_Detail": {},
    "Order_State_Logs": [
      { … }
    ],
    "Assigned_Users": [
      { … }
    ]
  },
  "vendor": {
    "id": 0,
    "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
    "supplier_id": 0,
    "parent_vendor_id": 0,
    "customer_internal_id": "string",
    "name": "string",
    "email": "string",
    "shipping_email": "string",
    "phone": "string",
    "cell": "string",
    "fax": "string",
    "address_line_one": "string",
    "address_line_two": "string",
    "city": "string",
    "state": "string",
    "postal_code": "string",
    "country": "string",
    "active": true,
    "tax_exempt": true,
    "resale_tax_id": "string",
    "lock_catalog_id": 0,
    "price_group_id": 0,
    "payment_type_id": 0,
    "payment_term_id": 0,
    "require_payment": true,
    "credit_limit": 0,
    "open_balance": 0,
    "is_ecomm_user": true,
    "net_term_ecomm_user": true,
    "require_po": true,
    "standing_po": "string",
    "hide_pricing": true,
    "currency_id": 0,
    "notes": "string",
    "default_order_category_id": 0,
    "route_id": 0,
    "timezone": "string",
    "bill_to_id": 0,
    "ship_to_id": 0,
    "Bill_To": {
      "id": 0,
      "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
      "vendor_id": 0,
      "order_id": 0,
      "name": "string",
      "company_name": "string",
      "address_line_one": "string",
      "address_line_two": "string",
      "address_line_three": "string",
      "city": "string",
      "state": "string",
      "postal_code": "string",
      "country": "string",
      "phone": "string",
      "fax": "string",
      "email": "string",
      "note": "string",
      "address_internal_id": "string",
      "is_vendor_main_ship_to": true,
      "verified": true,
      "lat": 0,
      "lng": 0,
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z"
    },
    "Ship_To": {
      "id": 0,
      "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc",
      "vendor_id": 0,
      "order_id": 0,
      "name": "string",
      "company_name": "string",
      "address_line_one": "string",
      "address_line_two": "string",
      "address_line_three": "string",
      "city": "string",
      "state": "string",
      "postal_code": "string",
      "country": "string",
      "phone": "string",
      "fax": "string",
      "email": "string",
      "note": "string",
      "address_internal_id": "string",
      "is_vendor_main_ship_to": true,
      "verified": true,
      "lat": 0,
      "lng": 0,
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z"
    },
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z",
    "deleted_at": "2019-08-24T14:15:22Z"
  },
  "billTo": {
    "id": 4821,
    "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc"
  },
  "shipTo": {
    "id": 4821,
    "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc"
  },
  "contact": {
    "id": 4821,
    "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc"
  },
  "note": {
    "id": 4821,
    "guid": "ee6a7af7-650d-499b-8e32-58a52ffdb7bc"
  }
}