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.
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.
PriceSchedule.SaleStart
PriceBreak.SalePrice
to be active.PriceSchedule.SaleEnd
PriceBreak.SalePrice
to be active.PriceSchedule.IsOnSale
PriceSchedule.SaleStart
and PriceSchedule.SaleEnd
date/time range and whether a PriceBreak.SalePrice
exists.PriceBreak.SalePrice
PriceBreak.Price
if the current date/time is within the PriceSchedule.SaleStart
and PriceSchedule.SaleEnd
date/time range.At this time, the PriceSchedule.IsOnSale
property is not searchable or filterable as it is a calculated value.
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!
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):
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;
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;
Now that we have determined that both the PriceSchedule
s 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
}
]
}
Now let's verify that we have successfully created two different price schedules with SalePrice
s 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.
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.