# REST API reference

All plugin REST routes use the namespace **`parcel2go-shipping/v1`**. Base URL is typically `rest_url('parcel2go-shipping/v1')` (e.g. `/wp-json/parcel2go-shipping/v1`). Endpoints require the user to have `manage_woocommerce` capability unless noted.

## Auth

| Method | Path | Purpose |
|--------|------|--------|
| POST | `/auth/authorise` | Generate PKCE pair, call accountlinking edge, return `{ authoriseUrl }` for the P2G consent page. Requires `manage_woocommerce`. |
| GET | `/auth/callback` | OAuth callback: receives `?code=` from the edge, exchanges code + stored PKCE verifier for tokens, stores them, then redirects to the plugin admin page. Public (unauthenticated). |
| GET | `/auth/status` | Returns `{ linked: true|false }` indicating whether an access token is stored. Requires `manage_woocommerce`. |
| GET | `/auth/user` | Returns linked account details parsed from JWT claims: `{ linked, accountNumber, email, name, forename, surname }`. Requires `manage_woocommerce`. |
| POST | `/auth/logout` | Removes stored access and refresh tokens. Requires `manage_woocommerce`. |

## Orders

| Method | Path | Purpose |
|--------|------|--------|
| GET | `/orders` | List processing orders (paginated). Query: `page`, `per_page` |
| GET | `/orders/(?P<id>[\d]+)` | Get a single order by ID |
| GET | `/orders/(?P<id>[\d]+)/ship` | Get order data needed for the ship flow (order, quotes, dropshops) |
| POST | `/orders/(?P<id>[\d]+)/shipping-status` | Update order shipping status: Paid, Booked, or Fulfilled (see below) |
| GET | `/order/p2g-status` | Poll P2G order status (query/body: `orderId`, `hash`) |

### POST `/orders/{id}/shipping-status`

Updates the WooCommerce order’s P2G shipping state. Flow: **Paid** (after payment) → **Booked** (when P2G confirms) → **Fulfilled** (tracking available; marks WC order completed).

**Body (JSON):**

| Field | Type | When | Description |
|-------|------|------|-------------|
| `status` | string | Required | One of: `Paid`, `Booked`, `Fulfilled` |
| `paymentDetails` | object | For `Paid` | `orderId`, `completeHash` from P2G payment (stored for polling) |
| `trackingNumber` | string or array | For `Fulfilled` | Single tracking number or list |
| `parcelNumbers` | array | For `Fulfilled` | List of parcel/tracking numbers (alternative to `trackingNumber`) |

**Response (success):** `{ "success": true, "wcOrderId": <id>, "status": "<Paid|Booked|Fulfilled>" }`

## Quotes

| Method | Path | Purpose |
|--------|------|--------|
| POST | `/quotes` | Get Parcel2Go shipping quotes (body: origin, destination, parcels, etc.) |

## Countries

| Method | Path | Purpose |
|--------|------|--------|
| GET | `/countries/origins` | List origin countries from P2G API (cached) |

## Dropshop

| Method | Path | Purpose |
|--------|------|--------|
| GET | `/dropshops` | Get dropshops near a postcode (query: `postcode`) |

## Checkout

| Method | Path | Purpose |
|--------|------|--------|
| POST | `/checkout` | Create order at Parcel2Go checkout |
| POST | `/checkout/validate` | Validate checkout/order at Parcel2Go |

## Payment

| Method | Path | Purpose |
|--------|------|--------|
| POST | `/payment/providers` | Get available payment providers |
| POST | `/payment/braintree/token` | Get Braintree client token |
| POST | `/payment/braintree` | Submit Braintree payment |
| GET | `/payment/prepay/balance` | Get prepay account balance |
| POST | `/payment/prepay` | Submit prepay payment |

## Settings

| Method | Path | Purpose |
|--------|------|--------|
| GET | `/settings` | Get plugin settings |
| GET | `/settings/store` | Get store settings (address etc.) |
| GET | `/settings/default-services` | Get default services configuration |
| PATCH | `/settings` | Update plugin settings (partial) |
| POST | `/settings` | Update plugin settings (full) |

## Shipments

| Method | Path | Purpose |
|--------|------|--------|
| GET | `/shipments` | List fulfilled shipments only (paginated). Returns orders where `_p2g_ship_status` = Fulfilled. Query: `page`, `per_page` |
| GET | `/shipments/(?P<id>[\d]+)/label` | Get label for a shipment (optional query: `size`, e.g. a4) |
| GET | `/shipments/(?P<id>[\d]+)/tracking` | Get tracking info for a shipment |