Creating your first order

The central concept within OrderCloud is the order. This is the object where buyers, sellers, products, payments, and other elements come together to form a business transaction.

Direction

A key feature of the Order resource is the order "direction". The endpoints used to interact with the order resource are the same endpoints you use regardless of which type of user you are: buyer, seller, supplier. What changes is the order direction. An order generally flows like this:

Buyer ➔ Seller

To create an order for our buyer user, use a direction of Outgoing because we are placing an outgoing order from buyer to seller.

Create an empty order

Now that we know what direction to use, create an empty order using the Orders resource. You may be thinking - wait, we do not have the OrderAdmin role available, so how will we use the Orders resource? The Shopper role allows buyer users to create and modify new orders and line items for their own user.

POST https://sandboxapi.ordercloud.io/v1/orders/Outgoing HTTP/1.1
Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
Content-Type: application/json; charset=UTF-8

{} //empty order object

The response looks like this:

{
  "ID": "PKTiEFNEiEi9mEmC9cZCrw",
  "FromUser": {
    "ID": "BUYER_USER",
    "Username": "buyer01",
    "Password": null,
    "FirstName": "Buyer",
    "LastName": "User",
    "Email": "[email protected]",
    "Phone": null,
    "TermsAccepted": null,
    "Active": true,
    "xp": null,
    "AvailableRoles": null,
    "Locale": null,
    "DateCreated": "2021-02-08T23:09:14.82+00:00",
    "PasswordLastSetDate": "2021-02-08T23:10:00.56+00:00"
  },
  "FromCompanyID": "BUYER_ORGANIZATION",
  "ToCompanyID": "xxxxxxxxxxxxxxxx",
  "FromUserID": "BUYER_USER",
  "BillingAddressID": null,
  "BillingAddress": null,
  "ShippingAddressID": null,
  "Comments": null,
  "LineItemCount": 0,
  "Status": "Unsubmitted",
  "DateCreated": "2021-02-23T20:39:03.173+00:00",
  "DateSubmitted": null,
  "DateApproved": null,
  "DateDeclined": null,
  "DateCanceled": null,
  "DateCompleted": null,
  "LastUpdated": "2021-02-23T20:39:03.173+00:00",
  "Subtotal": 0.0,
  "ShippingCost": 0.0,
  "TaxCost": 0.0,
  "PromotionDiscount": 0.0,
  "Currency": null,
  "Total": 0.0,
  "IsSubmitted": false,
  "LineItems": null,
  "xp": null
}

Note the Order ID returned here; you will need it in subsequent guides.

Review some of the properties that were populated on our behalf:

• FromUser - The user placing the order. In our case this is our buyer user with the username buyer01.
• FromCompanyID - The company of the from user, our buyer organization ID.
• ToCompanyID - The company that the order will be submitted to, in our case this is the seller organization ID.
• OrderStatus - The OrderCloud order status of the order, which begins at Unsubmitted and changes throughout the order's lifecycle.

Status

Throughout a workflow an order undergoes various status changes:

• Unsubmitted: Created but has not yet been submitted
• Open: Submitted but not yet fulfilled
• AwaitingApproval: On hold awaiting approval
• Declined: Submitted but has been declined
• Completed: Submitted and all the line items on the order have been shipped
• Canceled: Order can no longer be submitted

Once an order is canceled, it is effectively dead and no further actions can be taken on it.

See Understanding orders for more information.