Sale Prices using Price Schedules

Suggest an edit
Rob Lloyd

Updated by Rob Lloyd

March 24th, 2022

Sale Pricing is new additional functionality added on top of the existing PriceSchedule and PriceBreak. These changes allow for sale prices to be applied, optionally using a set start and end date.

Updated Resource: PriceSchedule

"PriceSchedule" : {
	"OwnerID": "marketplaceownerID",
	"ID": "priceschedule1",
	"Name": "Price Schedule One",
	"ApplyTax": false,
	"ApplyShipping": false,
	"MinQuantity": 1,
	"MaxQuantity": null,
	"UseCumulativeQuantity": false,
	"RestrictedQuantity": false,
	"SaleStart": "2022-03-02T00:00:00.00+00:00", // NEW - optional
	"SaleEnd": "2022-03-02T00:00:00.00+00:00", // NEW - optional
	"IsOnSale": true, // NEW - readonly - determined from current date/time falling within SaleStart/SaleEnd date AND existence of PriceBreak.SalePrice
	"PriceBreaks": [
		{
			"Quantity": 1,
			"Price": 20,
			"SalePrice": 15 // NEW - optional
		}
	],
	"Currency": null,
	"xp": {}
}

If sale pricing is active, that sale price is used to determine the line item unit price.

New Properties

PriceSchedule.SaleStart

  • Used to define the start date to be used for a PriceBreak.SalePrice to be active.
  • Optional.
  • Stored date/time will be converted to UTC.

PriceSchedule.SaleEnd

  • Used to define the end date to be used for a PriceBreak.SalePrice to be active.
  • Optional.
  • Stored date/time will be converted to UTC.

PriceSchedule.IsOnSale

  • Readonly boolean that will be set to true if the PriceSchedule has active Sale Pricing.
  • This value is calculated based on if the current date/time is within the PriceSchedule.SaleStart and PriceSchedule.SaleEnd date/time range and whether a PriceBreak.SalePrice exists.

PriceBreak.SalePrice

  • Sale Price that will override the PriceBreak.Price if the current date/time is within the PriceSchedule.SaleStart and PriceSchedule.SaleEnd date/time range.

Current Limitations

At this time, the PriceSchedule.IsOnSale property is not searchable or filterable as it is a calculated value.

Tutorial

Although there are multiple ways to provide sale prices to your products with price schedules, in this scenario we want to provide a time based sale price to the "ProductID": "usb-product-id" product.

After reviewing the considerations below, lets go through the steps of achieving this!

Considerations

  1. In our example, we will be modifying price schedules that were created in the Same Product, Multiple Price Schedules example. If you follow those steps the required products, categories and catalogs have been created successfully, with proper assignments.

Modify the Price Schedules

From the previous example, we should have two price schedules for the "USB Cord" product, so let's check to ensure the PriceSchedules exist.

Our calls to the OrderCloud API should look like this (If successful, our call should return a 200 response and the PriceSchedule):

Verify that the enterprise PriceSchedules exists
GET https://sandboxapi.ordercloud.io/v1/priceschedules/enterprise-priceschedule-id HTTP/1.1
Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
Content-Type: application/json; charset=UTF-8;
Verify that the startup PriceSchedules exists
GET https://sandboxapi.ordercloud.io/v1/priceschedules/startup-priceschedule-id HTTP/1.1
Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
Content-Type: application/json; charset=UTF-8;

Add Sale Pricing for each PriceSchedule

Now that we have determined that both the PriceSchedules exist, let's add some sale pricing with some date and time restrictions. For this next step, we will assign a SalePrice, SaleStart and SaleEnd values for enterprise-priceschedule-id. Assuming we are currently in the month of March, let's assign a SalePrice of 2.99 for the duration of the month, which would see the sale price be immediately available.

Note: Modify the SaleStart and SaleEnd dates to be valid for your scenario.

Note: As SaleStart is optional, by not setting a value for SaleStart the SalePrice would be valid immediately (As long as the SaleEnd date is in the future).

PATCH https://sandboxapi.ordercloud.io/v1/priceschedules/enterprise-priceschedule-id HTTP/1.1
Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
Content-Type: application/json; charset=UTF-8

{
  "SaleStart": "2022-03-01T00:00:00.00+00:00",
  "SaleEnd": "2022-04-01T00:00:00.00+00:00",
  "PriceBreaks": [
    {
      "Quantity": 1,
      "Price": 3.99,
      "SalePrice": 2.99
    }
  ]
}

In similar fashion, let's assign a SalePrice and SaleStart and SaleEnd values for startup-priceschedule-id. Still assuming we are in month of March, we will assign a SalePrice of 4.99 for the duration of April, which would see the sale price not be available until next month.

Note: Modify the SaleStart and SaleEnd dates to be valid for your scenario.

PATCH https://sandboxapi.ordercloud.io/v1/priceschedules/startup-priceschedule-id HTTP/1.1
Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
Content-Type: application/json; charset=UTF-8

{
  "SaleStart": "2022-04-01T00:00:00.00+00:00",
  "SaleEnd": "2022-05-01T00:00:00.00+00:00",
  "PriceBreaks": [
    {
      "Quantity": 1,
      "Price": 5.99,
      "SalePrice": 4.99
    }
  ]
}

Verify Valid Pricing

Now let's verify that we have successfully created two different price schedules with SalePrices and our product: USB Cord. The next steps require that you authenticate as specific users. To check the contents of your authentication token, visit JWT.io.

Let's verify the sale price is active. In the context of Jane Doe from CloudTech, call GET https://sandboxapi.ordercloud.io/v1/me/products/usb-product-id. You should see the USB Cord product returned with "IsOnSale": true, indicating that "SalePrice": 2.99 will be resolved over the standard "Price": 3.99 for the UnitPrice calculation of order line items.

Let's verify that the product is not on sale. In the context of John Deer from ComputerDudes, call GET https://sandboxapi.ordercloud.io/v1/me/products/usb-product-id. You should see the same product returned with "IsOnSale": false, so even though there is the "SalePrice": 4.99, as it's not currently 'on sale', the standard "Price": 5.99 will be resolved for the UnitPrice calculation of order line items.

Conclusion

Congratulations! You now have the knowledge and background to make informed decisions about how to structure your Product -- multiple Price Schedule -- Sale Pricing, and how to make those assignments via the OrderCloud API.