> For the complete documentation index, see [llms.txt](https://apidocs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.akinon.com/commerce-openapis/admin/package-notifications.md).

# Package Notifications

A single administrative endpoint that turns a **package** event into an outbound email to the seller (stock location) the package belongs to. The caller — Omnitron or any integration that observes package events — posts the event and the package it concerns, and the endpoint sends the notification mail that matches the event type.

The endpoint is **stateless** — no package record is created, read, or stored. Each request renders one email from the payload it carries and hands it to the mail backend, so there is nothing to list, retrieve, update, or delete. `POST /packages/notify/` is the only operation on `/packages/`; no other path or method under that prefix is routed.

### Core Capabilities

**1. Event-driven Seller Notification**

* Accept a package webhook body (`event` + `payload`) and send the email that corresponds to the event type.
* The recipient is the email address of the stock location carried in the payload, plus any fixed addresses configured on the installation.

**2. Template Selection by Event Type**

* The event type selects both the subject template and the body template. The entire `payload` object is exposed to those templates as `data`, so the mail content is fully determined by what the caller sends.
* Templates are resolved through the Jinja loader configured for the environment (`TEMPLATE_LOADER`). Akinon Cloud deployments use a loader that also serves templates stored in the database, so a project can override the shipped body and subject there without a code change; otherwise the files under `shop_templates/` are used.

### Event Types

Only the two event types below are accepted; any other value is rejected with `400` before an email is composed.

| `event.type`               | Purpose                                                                           | Body template                        | Subject template                             |
| -------------------------- | --------------------------------------------------------------------------------- | ------------------------------------ | -------------------------------------------- |
| `package.created`          | Tells the seller a new package has been created and is awaiting its confirmation. | `emails/orders/package-created.html` | `emails/orders/package-created-subject.html` |
| `package.status.preparing` | Tells the seller its offer was accepted and the package has moved to preparing.   | `emails/orders/offer-accepted.html`  | `emails/orders/offer-accepted-subject.html`  |

### Payload Requirements

`payload` is a free-form object — it is handed to the template as `data` — but two members are consulted by the server itself:

| Field                  | Required | Used for                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ---------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `stock_location`       | Yes      | Must be present as an object. Omitting it entirely leaves the server unable to resolve a recipient and the request fails with `500`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `stock_location.email` | Yes      | The primary recipient of the email. A `stock_location` that carries no `email` is rejected with `400` and the body `{"payload": ["stock location requires email"]}`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `created_date`         | Yes      | Required for **both** event types. Parsed as a UTC timestamp that must match `YYYY-MM-DDTHH:MM:SS.fffZ` — date and time separated by `T`, fractional seconds (1–6 digits) and a trailing `Z`, for example `2020-03-23T12:12:12.123Z`. It is converted to the installation's local time zone and then moved forward by `PACKAGE_EXTRA_MINUTES` before being exposed to the template as `data.created_date`, which is how the shipped package-created template shows the seller a confirmation *deadline* rather than the creation instant. The offer-accepted template does not render it, but the value is still parsed for that event. A missing value or a different format cannot be parsed and the request fails with `500`. |

Every other member is optional as far as validation goes. The shipped templates read the fields below and render them empty when they are absent, so send the full package representation from Omnitron rather than a trimmed object.

| Payload field                                                                                                                                                                                                                                                          | Used by                                                     |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| `number`                                                                                                                                                                                                                                                               | Both templates — the package number shown in the mail.      |
| `order_number`                                                                                                                                                                                                                                                         | `package.created` — the order the package belongs to.       |
| `stock_location.name`                                                                                                                                                                                                                                                  | Both templates — the seller name in the greeting.           |
| `stock_location.address.city.name`, `stock_location.address.township.name`                                                                                                                                                                                             | `package.created` — the pickup address shown to the seller. |
| `shipping_address.customer.first_name`, `shipping_address.customer.last_name`, `shipping_address.line`, `shipping_address.postcode`, `shipping_address.district.name`, `shipping_address.township.name`, `shipping_address.city.name`, `shipping_address.country.name` | `package.status.preparing` — the delivery address block.    |
| `packageitem_set[].id`                                                                                                                                                                                                                                                 | `package.created` — the package item identifier per line.   |
| `packageitem_set[].order_item.product.name`, `packageitem_set[].order_item.product.sku`                                                                                                                                                                                | Both templates — the product lines of the package.          |
| `packageitem_set[].order_item.price_currency`, `packageitem_set[].order_item.extra_field.price_extra_field.offer_price`                                                                                                                                                | `package.created` — the offered price per line.             |

The shipped package-created template also references `SHOP_NAME`, `LOGO_URL` and `INSTORE_URL`. These are **not** taken from the payload and are not defined by the platform's default Jinja configuration, so they render empty unless the installation supplies them through its own template environment.

### Delivery Semantics

The email is composed and sent **synchronously**, within the request. A `200` response therefore means the request was valid and processing finished — but it does **not** guarantee a message was handed to the mail backend, because the send is skipped silently in these cases:

* the body template for the event is switched off through `DISABLED_EMAIL_TEMPLATES`;
* the subject template is missing or raises while rendering;
* the body template is missing or raises while rendering.

In all three cases the response is still `200` with an empty object; check the application logs when an expected mail does not arrive.

Delivery is **not** fail-silent, however: when a message is actually composed and the mail backend rejects it or is unreachable, the error propagates and the request fails with `500`. Retrying such a request re-sends the mail, so treat the operation as at-least-once rather than idempotent.

### Dynamic Settings & Environment Variables

Both dynamic settings below are registered in `omnishop/users/settings/conf.py` and are keyed by **template key** — the template path with its extension removed (`emails/orders/package-created`, `emails/orders/offer-accepted`). They are shared with every other outbound email of the platform; only the two keys used by this endpoint are described here.

| Key                        | Type                                                      | Default                                                                      | Effect                                                                                                                                                                                                                                                                                                                                                                                             |
| -------------------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DISABLED_EMAIL_TEMPLATES` | object — template key → boolean                           | Every template key `false`, except `emails/orders/preparing` which is `true` | Per-template kill switch, evaluated on the **body** template of the incoming event: `emails/orders/package-created` for `package.created`, `emails/orders/offer-accepted` for `package.status.preparing`. When the relevant key is `true`, `POST /packages/notify/` still validates the request and answers `200`, but no email is sent. Neither of the two keys used here is disabled by default. |
| `EMAIL_BCC_AND_CC`         | object — template key → `{"cc": [email], "bcc": [email]}` | Every template key mapped to `{"cc": [], "bcc": []}`                         | Fixed copy recipients added to the message, looked up by the same body-template key. The addresses in `cc` are visible to the recipient, those in `bcc` are not. Both lists are validated as email addresses when the setting is written.                                                                                                                                                          |

**Django settings / environment variables**

| Setting                 | Type                    | Default              | Effect                                                                                                                                                                                                                                                                            |
| ----------------------- | ----------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PACKAGE_CREATED_MAILS` | list of email addresses | `[]`                 | Appended to the recipient (`To`) list of **every** notification sent by this endpoint, alongside the stock location's own address. Read with a fallback, so an installation that does not define it simply sends to the stock location only.                                      |
| `PACKAGE_EXTRA_MINUTES` | integer (minutes)       | `180` (3 hours)      | Added to `payload.created_date` before it is given to the template, producing the confirmation deadline the seller sees. Read with a fallback.                                                                                                                                    |
| `NO_REPLY_EMAIL`        | string (email)          | `noreply@akinon.com` | The `From` address of the message. Set per environment through the `NO_REPLY_EMAIL` environment variable. This endpoint reads the **Django setting**; the same-named dynamic setting registered in `omnishop/cms/settings/conf.py` is used by other flows and has no effect here. |

The mail backend itself (`EMAIL_BACKEND`, `EMAIL_HOST`, `EMAIL_HOST_USER`, `EMAIL_HOST_PASSWORD`, `EMAIL_PORT`, `EMAIL_USE_TLS`) is configured per environment and applies to all platform email, not only to this endpoint.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://apidocs.akinon.com/commerce-openapis/admin/package-notifications.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
