Adding line items

Viewing my orders

If you do not remember your order ID, buyer users can view their orders using the My Orders resource. This returns a list of orders where the currently authenticated user is the FromUser.

http

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

Creating a line item

Now that you can browse products available to your buyer user and know the direction and ID of the order you are working with, you can add a line item to the order.

See OrderCloud Line items for more information.

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

{
  "ProductID": "SHIRT",
  "Quantity": 2
}

The response looks like this:

json

{
	"ID": "wvBDPU-WM0CaHpDaIplJcA",
	"ProductID": "SHIRT",
	"Quantity": 2,
	"DateAdded": "2021-03-01T22:00:05.437+00:00",
	"QuantityShipped": 0,
	"UnitPrice": 10,
	"PromotionDiscount": 0,
	"LineTotal": 20,
	"LineSubtotal": 20,
	"CostCenter": null,
	"DateNeeded": null,
	"ShippingAccount": null,
	"ShippingAddressID": null,
	"ShipFromAddressID": null,
	"Product": {
		"ID": "SHIRT",
		"Name": "Cotton T-Shirt",
		"Description": "A plain white, cotton shirt for everyday use.",
		"QuantityMultiplier": 1,
		"ShipWeight": null,
		"ShipHeight": null,
		"ShipWidth": null,
		"ShipLength": null,
		"xp": null
	},
	"Variant": null,
	"ShippingAddress": null,
	"ShipFromAddress": null,
	"SupplierID": null,
	"Specs": [],
	"xp": null
}

Line item response model

Like the buyer product model, the line item includes a sub-object for the Product attached to it. This is not a buyer product with a full price schedule. Pricing information appears at the root of the line item model.

Note: Because a Quantity of two was added, the API automatically calculates UnitPrice, LineTotal, and LineSubtotal.

Use these line item properties to display cost in a shopping cart because the price schedule is only one component in calculating the actual purchase price.

If a product spec for "shirt size" incurs a price markup of $2.00, the new unit price would be $12.00.

If any applicable line item promotions exist, PromotionDiscount and LineSubtotal might be affected. For example, if a BOGO offer is applied to the product, the second unit would be free, bringing the subtotal back down to $10.00.

See Line item-level promotions for more information.

Retrieve the order

After adding a line item, retrieve the order again to see how it has changed. Use the example at the top of this guide. The response now looks like this:

json

{
	"Meta": {
		"Page": 1,
		"PageSize": 20,
		"TotalCount": 1,
		"TotalPages": 1,
		"ItemRange": [
			1,
			1
		]
	},
	"Items": [
		{
			"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": "bClEeDV0f9GjjkGD",
			"FromUserID": "BUYER_USER",
			"BillingAddressID": null,
			"BillingAddress": null,
			"ShippingAddressID": null,
			"Comments": null,
			"LineItemCount": 1,
			"Status": "Unsubmitted",
			"DateCreated": "2021-02-23T20:39:03.173+00:00",
			"DateSubmitted": null,
			"DateApproved": null,
			"DateDeclined": null,
			"DateCanceled": null,
			"DateCompleted": null,
			"Subtotal": 20,
			"ShippingCost": 0,
			"TaxCost": 0,
			"PromotionDiscount": 0,
	                "Currency": null,
			"Total": 20,
			"IsSubmitted": false,
	                "LineItems": null,
			"xp": null
		}
	]
}

The order's LineItemCount, Subtotal, and Total have changed.

If you have suggestions for improving this article, let us know!