---
title: "Schedule Order Notifications"
method: POST
path: "/notifications/schedule/orders"
tags: ["Notifications"]
---

# Schedule Order Notifications

`POST /notifications/schedule/orders`

## Request

- Base URL: `https://api.smartroutes.io/v2`
- URL: `https://api.smartroutes.io/v2/notifications/schedule/orders`
- Auth: none declared

Schedules SMS and/or email notifications to the customers on a set of orders, using up to two of your notification templates (see `GET /notifications/templates`). One notification is created for each order and template pair. It is sent at `send_time_utc`, or straight away if you leave that out.

- The recipient is the order's contact phone number or email. If the order has none, the linked customer's phone number or email is used.
- Each SMS uses one credit per 160 characters of the rendered message, and the credits are deducted when the notification is scheduled. If the depot has no SMS credits left, SMS templates are skipped without being reported in `errors`.
- Order and template ids that don't belong to this depot are ignored. If none of the orders are found, the response is `404 RESOURCE_NOT_FOUND`.
- Nothing checks for duplicates. Calling again for the same orders schedules the notifications again.

The request can partly succeed. The response is `200` with `notifications` listing the `order_id` of each notification created, and `errors` listing each order and template pair that was skipped and why (for example, no phone number, or an invalid email). Check `errors` even when the status is 200. To see the scheduled notifications, use `GET /notification-tasks`. Supports the `idempotency-key` header, so a retry won't schedule twice (see [Idempotency](#section/Getting-started/Idempotency)).

## Headers

- `idempotency-key` string

## Request body

- object
  - `orders` unknown[], required: Array of order IDs to create notifications for
    - unknown
  - `templates` unknown[], required: Array of template IDs to generate notifications for
    - unknown
  - `send_time_utc` string: UTC Timestamp at which to send the notifications, defaults to current time if not provided.

## Response `200`

Successful response

## Other responses

- `400`: Invalid input. The request body failed validation.
- `403`: Forbidden. Returned for rate-limit exhaustion (`name = FORBIDDEN`, with `details.retry_after_seconds` and `Retry-After` header) and permission gate failures (`name = PERMISSION`). Inspect `name` to disambiguate. Send `x-sr-api-features: rate-limit-429` to receive `429 RATE_LIMIT_EXCEEDED` for the rate-limit case instead, leaving `403` to mean permission failures only — see [API Features](#section/Getting-started/API-Features).
- `404`: The requested resource was not found.
- `409`: A request with this idempotency key is already in progress. Retry after the period given in the `Retry-After` header.
- `422`: The same idempotency key was used with a different request body for this endpoint.
- `429`: Rate limit exceeded (`name = RATE_LIMIT_EXCEEDED`). **Only returned to callers that opt in** with the `x-sr-api-features: rate-limit-429` request header; without it the same condition returns `403` with `name = FORBIDDEN` and an otherwise identical body. See [API Features](#section/Getting-started/API-Features).
- `500`: An unexpected server error occurred. The body carries only `name` and `description`: internal details are never returned.

---

[API](https://skmtc.dev/smartroutes/apis/smartroutes-api.md) · [All operations](https://skmtc.dev/smartroutes/apis/smartroutes-api/llms.txt) · [OpenAPI document](https://skmtc.dev/smartroutes/apis/smartroutes-api/revisions/a7ea507afac7?raw)