Sale Prices using Price Schedules

Published by Rob Lloyd on March 3, 2022

Last updated on March 24, 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

1"PriceSchedule" : {
2	"OwnerID": "marketplaceownerID",
3	"ID": "priceschedule1",
4	"Name": "Price Schedule One",
5	"ApplyTax": false,
6	"ApplyShipping": false,
7	"MinQuantity": 1,
8	"MaxQuantity": null,
9	"UseCumulativeQuantity": false,
10	"RestrictedQuantity": false,
11	"SaleStart": "2022-03-02T00:00:00.00+00:00", // NEW - optional
12	"SaleEnd": "2022-03-02T00:00:00.00+00:00", // NEW - optional
13	"IsOnSale": true, // NEW - readonly - determined from current date/time falling within SaleStart/SaleEnd date AND existence of PriceBreak.SalePrice
14	"PriceBreaks": [
15		{
16			"Quantity": 1,
17			"Price": 20,
18			"SalePrice": 15 // NEW - optional
19		}
20	],
21	"Currency": null,
22	"xp": {}
23}

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.
If an item is being purchased as part of a bundle the BundlePrice will always apply when it is defined. If it is not defined, then the following pricing precedence applies:
- SubscriptionPrice
  - if the item is part of a subscription order
- SalePrice

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

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

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

Verify that the startup PriceSchedules exists

1GET https://sandboxapi.ordercloud.io/v1/priceschedules/startup-priceschedule-id HTTP/1.1
2Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
3Content-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).

1PATCH https://sandboxapi.ordercloud.io/v1/priceschedules/enterprise-priceschedule-id HTTP/1.1
2Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
3Content-Type: application/json; charset=UTF-8
4
5{
6  "SaleStart": "2022-03-01T00:00:00.00+00:00",
7  "SaleEnd": "2022-04-01T00:00:00.00+00:00",
8  "PriceBreaks": [
9    {
10      "Quantity": 1,
11      "Price": 3.99,
12      "SalePrice": 2.99
13    }
14  ]
15}

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.

1PATCH https://sandboxapi.ordercloud.io/v1/priceschedules/startup-priceschedule-id HTTP/1.1
2Authorization: Bearer INSERT_ACCESS_TOKEN_HERE
3Content-Type: application/json; charset=UTF-8
4
5{
6  "SaleStart": "2022-04-01T00:00:00.00+00:00",
7  "SaleEnd": "2022-05-01T00:00:00.00+00:00",
8  "PriceBreaks": [
9    {
10      "Quantity": 1,
11      "Price": 5.99,
12      "SalePrice": 4.99
13    }
14  ]
15}

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.

Still have questions?
Ask in our Community Channel