1. Product catalogs

Sale prices using price schedules

The PriceSchedule and PriceBreak resources now support sale pricing functionality with optional start and end dates.

Price schedule model

Updated resource definition

json
{
  "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": {}
  }
}

Pricing behavior

Active sale prices override standard pricing in line item unit price calculations.

New properties

SaleStart property

  • Defines sale start date/time
  • Optional field
  • Stored in UTC format
  • Controls price activation

SaleEnd property

  • Defines sale end date/time
  • Optional field
  • Stored in UTC format
  • Controls price deactivation

IsOnSale property

  • Read-only boolean
  • Indicates active sale status
  • Calculated from:
    • Current date/time
    • SaleStart/SaleEnd range
    • PriceBreak.SalePrice existence

SalePrice property

  • Overrides standard Price
  • Active during sale period
  • Pricing precedence:
    1. BundlePrice (if defined)
    2. SubscriptionPrice (subscription orders)
    3. SalePrice (during sale period)
    4. Standard Price

Current limitations

The IsOnSale property:

  • Not searchable
  • Not filterable
  • Calculated at runtime

Implementation guide

Prerequisites

This guide builds on the Same Product, Multiple Price Schedules example:

  • Existing products
  • Configured categories
  • Established catalogs
  • Valid assignments

Price schedule verification

Check enterprise schedule

http
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;

Check startup schedule

http
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;

Configure sale pricing

Enterprise price schedule

March sale configuration:

http
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
json
{
  "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
    }
  ]
}

Startup price schedule

April sale configuration:

http
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
json
{
  "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
    }
  ]
}

Verification steps

Active sale verification

  1. Authenticate as Jane Doe (CloudTech)
  2. Call GET https://sandboxapi.ordercloud.io/v1/me/products/usb-product-id
  3. Verify:
    • IsOnSale: true
    • SalePrice: 2.99 applies
    • Standard Price: 3.99 overridden

Inactive sale verification

  1. Authenticate as John Deer (ComputerDudes)
  2. Call GET https://sandboxapi.ordercloud.io/v1/me/products/usb-product-id
  3. Verify:
    • IsOnSale: false
    • SalePrice: 4.99 not active
    • Standard Price: 5.99 applies

Note: Use JWT.io to verify authentication tokens.

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