> ## Documentation Index
> Fetch the complete documentation index at: https://developers.gojoe.de/llms.txt
> Use this file to discover all available pages before exploring further.

# Order lifecycle

> Order statuses, who sets each one, and the calls your ERP makes.

Every order has exactly one `status`. Your ERP sets some statuses through the
API. GO JOE sets the others when the patient, the doctor or the courier acts,
and sends you an event each time.

## Statuses

| Status | Meaning | Set by |
| - | - | - |
| `new` | The order is paid and approved by a doctor. Your ERP has not accepted it yet. | GO JOE |
| `accepted` | Your ERP has accepted the order. | You, with `POST /orders/{id}/accept` |
| `packed` | The order is packed. | You, with `POST /orders/{id}/status` |
| `ready_for_pickup` | The order is ready for the patient at the counter. | You |
| `out_for_delivery` | The courier or carrier has the order. | GO JOE for express orders, you for shipping orders |
| `completed` | The patient has received the order. | GO JOE for courier deliveries, you otherwise |
| `returning` | The courier could not deliver and is returning the package. | GO JOE |
| `returned` | The package is back at the pharmacy. | You |
| `rejected` | You have reported that you cannot fill the order. | You, with `POST /orders/{id}/reject` |
| `cancelled` | The order is cancelled or refunded. Do not dispense it. | GO JOE |

## Fulfilment types

`fulfilment.type` and `fulfilment.courier` in the order show how the order
reaches the patient.

### Express

`fulfilment.type` is `express` and `fulfilment.courier` is `gojoe`. GO JOE's
courier collects the order from the pharmacy.

`new` → `accepted` → `packed` → `out_for_delivery` → `completed`

1. Accept the order.
2. Report `packed`.
3. GO JOE sets `out_for_delivery` when the courier has collected the order and
   `completed` when it is delivered. Do not report these two statuses.

When the courier is booked depends on the pharmacy's `courier_booking` setting
in `GET /me`:

| `courier_booking` | Behaviour |
| - | - |
| `on_packed` | GO JOE books the courier when you report `packed`. |
| `manual` | Pharmacy staff book the courier in the GO JOE dashboard. |

If a delivery fails, the status changes to `returning`. The courier needs
`fulfilment.return_pin` to hand the package back to the pharmacy. Report
`returned` when the package is back. If the patient then collects the order at
the counter, report `ready_for_pickup` and `completed`.

### Shipping

`fulfilment.type` is `shipping` and `fulfilment.courier` is `pharmacy`. You
ship the order with your own carrier.

`new` → `accepted` → `out_for_delivery` → `completed`

1. Accept the order.
2. Report `out_for_delivery` with `tracking` when you hand the parcel to the
   carrier.
3. Report `completed` when the parcel is delivered.

Reporting `packed` before `out_for_delivery` is optional.

The patient sees `tracking.url` as a link. It must be an `https` link to the
tracking page of one of these carriers: DHL, Deutsche Post, DPD, GLS, Hermes,
UPS, FedEx, GO! or trans-o-flex. For any other carrier, send only
`tracking.number`.

### Pick-up

`fulfilment.type` is `pickup`. The patient collects the order at the pharmacy.

`new` → `accepted` → `ready_for_pickup` → `completed`

1. Accept the order.
2. Report `ready_for_pickup` when the order is ready at the counter.
3. Report `completed` when the patient has collected it.

Reporting `packed` before `ready_for_pickup` is optional.

## Reject an order

If you cannot fill an order, call `POST /orders/{id}/reject` with a
`reason_code` and an optional `note`.

| `reason_code` | Use when |
| - | - |
| `out_of_stock` | A product is not in stock. |
| `prescription_issue` | There is a problem with the prescription. |
| `cannot_deliver` | You cannot deliver or hand over the order. |
| `other` | None of the above applies. Explain in `note`. |

You can reject an order while its status is `new`, `accepted` or `packed`.

After a rejection:

* The status is `rejected` and you receive `order.status_changed`.
* The GO JOE team decides how to proceed, for example with a refund.
* The API refuses further status reports for the order (`409 order_rejected`).
* You can no longer download the prescription.

If GO JOE then cancels the order, the status changes to `cancelled`.

## Cancelled orders

When GO JOE cancels an order, you receive `order.cancelled` and the status is
`cancelled`. Stop processing the order and do not dispense it.

Whether you can still download the prescription depends on when the order
was cancelled:

| Cancelled | Prescription download |
| - | - |
| Before you accepted the order | Not available (`409 order_cancelled`). |
| After you accepted the order | Available, so that a pharmacy that has already dispensed can keep the prescription in its records. |

## Keep your ERP in sync

An event tells you that an order changed. It does not contain the order. After
each event, fetch the order with `GET /orders/{id}` and use the response as
the current state.

To find changes that you did not receive as an event, call
`GET /orders?updated_since=<timestamp>` about once an hour. Use the time of
your previous call minus a few minutes as the timestamp. The response contains
every order that changed since then.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.