Scheduling

Developer Guide
Set it up once. It switches automatically.

Carrier rates aren't static. Peak season surcharges, promotional free shipping weekends, new-year tariff increases, planned carrier downtime — every ecommerce business faces moments where shipping rates need to change on a specific date and revert on another. Managing this manually means logging in at midnight, hoping you don't forget, and logging back in again to switch it back.

ShipRateAPI's Scheduling feature lets you configure those changes in advance. Every rate table has a validFrom and validTo datetime window. When a quote request is received, the rating engine checks the current date and time against those bounds and automatically includes or excludes each table — no manual intervention required.

You can have your entire Christmas pricing setup prepared weeks in advance. The moment the window opens, customers start seeing peak-period rates. The moment it closes, standard rates resume — automatically, reliably, at exactly the second you specified.

Screenshot: Rate Table edit form in admin portal — showing validFrom and validTo date/time pickers
How scheduling works

Every rate table has two optional datetime fields that define its active window. A table with no window set is always eligible. A table with both fields set is only evaluated when the current datetime falls within the range — inclusive of both bounds.

FieldTypeBehaviour
validFromISO 8601 datetimeTable becomes eligible at this datetime (inclusive). Null = no lower bound.
validToISO 8601 datetimeTable expires at this datetime (inclusive). Null = no upper bound.

Datetimes are evaluated in UTC. If your store operates in a specific timezone, offset your values accordingly — e.g. midnight GMT is 2024-12-25T00:00:00Z; midnight BST is 2024-12-25T00:00:00+01:00.

What you can do with scheduling

Scheduling applies to any rate type, any carrier, and any zone — which makes it one of the most versatile features in ShipRateAPI. Any rate table can be given a window, and multiple scheduled tables can coexist in the same zone as long as their windows don't overlap.

  • Peak season surcharges — create a rate table with higher amounts and set a validFrom/validTo window covering the peak delivery period. Your standard table's validTo should close just before the peak window opens. When the window closes, standard rates resume without any action on your part.
  • Promotional free shipping — set a free rate table with a window covering a sale weekend or campaign period. When the window ends, standard tables resume automatically — no risk of forgetting to turn it off.
  • Planned tariff increases — prepare next year's rates now by creating new rate tables with a validFrom set to the date the new tariff takes effect. Both tables sit in the admin simultaneously; only the correct one is ever evaluated. No last-minute changes, no midnight logins.
  • Carrier downtime windows — temporarily deactivate a carrier's rate table during a known maintenance or non-collection window without deleting any configuration.
  • Flash sale shipping — limited-time flat-rate or free shipping offers for specific hours. Set a tight window and the offer is live precisely when you need it.
Screenshot: Rate Tables list showing standard and Christmas tables side by side with schedule badges
Example — Christmas / Thanksgiving surcharge window

The most common scheduling pattern: a standard rate table that covers most of the year, a peak-period table that takes over during the holiday season, and the standard table resuming in the new year. The key is that the windows meet exactly — no gaps, no overlaps. Examples shown for UK, US, and EU carriers.

UK — Royal Mail Tracked 48

// Standard — active all year except the Christmas window
{
  "name":      "Royal Mail Tracked 48 — Standard",
  "type":      "weight",
  "validFrom": null,
  "validTo":   "2024-12-14T23:59:59Z"
}

// Christmas surcharge — Royal Mail peak period pricing
{
  "name":      "Royal Mail Tracked 48 — Christmas",
  "type":      "weight",
  "validFrom": "2024-12-15T00:00:00Z",
  "validTo":   "2025-01-05T23:59:59Z"
}

// Standard resumes in January
{
  "name":      "Royal Mail Tracked 48 — Standard",
  "type":      "weight",
  "validFrom": "2025-01-06T00:00:00Z",
  "validTo":   null
}

US — UPS Ground

// Standard — active all year except peak season
{
  "name":      "UPS Ground — Standard",
  "type":      "weight",
  "validFrom": null,
  "validTo":   "2024-11-24T23:59:59Z"
}

// Peak surcharge — UPS applies peak fees Thanksgiving through New Year
{
  "name":      "UPS Ground — Holiday Peak",
  "type":      "weight",
  "validFrom": "2024-11-25T00:00:00Z",
  "validTo":   "2025-01-05T23:59:59Z"
}

// Standard resumes after peak period
{
  "name":      "UPS Ground — Standard",
  "type":      "weight",
  "validFrom": "2025-01-06T00:00:00Z",
  "validTo":   null
}

EU — DHL Paket

// Standard — active all year except Christmas window
{
  "name":      "DHL Paket — Standard",
  "type":      "weight",
  "validFrom": null,
  "validTo":   "2024-12-15T23:59:59Z"
}

// Christmas surcharge — DHL peak period across DE / AT / CH
{
  "name":      "DHL Paket — Weihnachten",
  "type":      "weight",
  "validFrom": "2024-12-16T00:00:00Z",
  "validTo":   "2025-01-06T23:59:59Z"
}

// Standard resumes after Epiphany
{
  "name":      "DHL Paket — Standard",
  "type":      "weight",
  "validFrom": "2025-01-07T00:00:00Z",
  "validTo":   null
}
Avoid gaps between windows. If the standard table's validTo and the peak table's validFrom don't meet exactly, there will be a period where neither is eligible and the zone returns no rates. Use the Coverage Scanner to detect gaps before they affect customers.
Setting schedules in the admin portal

validFrom and validTo are set per rate table under Carriers → Rate Tables → Edit. Both fields accept a date and time picker. Leave a field blank to set it to null — no lower or upper bound.

After saving any scheduled change, run the Coverage Scanner to confirm your windows produce the intended coverage across all zones with no gaps or overlaps.

Screenshot: Coverage Scanner showing a scheduling gap warning between two rate tables
Scheduling works with every other feature
  • Any rate type can be scheduled — schedule a free table for a promotional weekend, a flat table during a delay period, or a configurable pipeline for peak-season complexity.
  • Combine with tag routing — schedule a carrier restriction for tagged products during specific periods. Exclude a standard carrier from dangerous-goods orders only during the Christmas period when specialist handling is required.
  • Validate with the Coverage Scanner — always run the Coverage Scanner after configuring scheduled windows. It's the only way to confirm that your windows meet without gaps and that every zone has valid coverage throughout the entire period.