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

# Listing Requests

> List, view, accept, and decline pharmacy listing requests via the Management API

# Listing Requests

Pharmacies can ask a shop to list a product they already carry. The Management API
exposes the organisation inbox for those requests: list them, inspect the submitted
fields, and record an accept or decline decision.

Accept and decline **record the decision only**. They do not create catalog rows
(`Product`, `SKU`, `ShopProduct`) and they do not push anything to Shopify or
WooCommerce.

All endpoints are scoped to the organisation that owns the API key. UIDs that
belong to another organisation are treated as not found.

Configuration of which fields a pharmacy must supply is done in the admin
interface, not on this API.

## Permissions

Listing-request endpoints are gated by two permissions:

* `listing_request:read` — required for all read (`GET`) endpoints.
* `listing_request:write` — required to accept or decline a request.

A key with `listing_request:write` is not automatically granted
`listing_request:read`; add both if you need to read and write. Contact your
RxScale account manager to adjust permissions.

All requests authenticate with the `X-API-Key` header. See
[Authentication](/authentication) for details.

## Request shape

There is **no top-level `pzn` field**. PZN is an ordinary extras key: a shop must
configure a `pzn` extras requirement before a pharmacy can send one, and the
value then appears under `extras.pzn` in the response.

`price_indication` is an integer in **minor units** (cents), matching pharmacy
SKU prices.

<Note>
  Attribute (`attr.*`) and PZN query filters are **not** available on the
  Management API in v1. They are admin-only. Filter here with `shop_uid`,
  `pharmacy_uid`, and `status` only.
</Note>

## List Listing Requests

```bash theme={null}
GET /v1/management/listing-requests
```

Returns a paginated list of listing requests for the organisation.

**Required permission:** `listing_request:read`

<ParamField query="page" type="integer" default="0">
  Page number (0-indexed)
</ParamField>

<ParamField query="limit" type="integer" default="50">
  Number of listing requests per page
</ParamField>

<ParamField query="shop_uid" type="string">
  Filter by shop UID. Unknown shops for this organisation return 404.
</ParamField>

<ParamField query="pharmacy_uid" type="string">
  Filter by pharmacy UID
</ParamField>

<ParamField query="status" type="string">
  Filter by status. One of `PENDING`, `ACCEPTED`, `DECLINED`, or `WITHDRAWN`.
</ParamField>

#### Example Request

```bash theme={null}
curl -X GET "https://api.rxscale.com/v1/management/listing-requests?page=0&limit=25&status=PENDING" \
  -H "X-API-Key: your-api-key-here"
```

#### Response

```json theme={null}
{
  "data": [
    {
      "uid": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "shop_uid": "a8c829ca-de1a-4b5e-9f6d-c1957d28aa4a",
      "pharmacy_uid": "22c49130-90aa-4384-aff2-4551f227cab4",
      "product_name": "Ibuprofen 400mg",
      "price_indication": 1250,
      "additional_notes": null,
      "status": "PENDING",
      "decision_note": null,
      "decided_at": null,
      "decided_by_user_uid": null,
      "decided_by_identifier": null,
      "extras": {
        "pzn": {
          "value": "01234567",
          "value_normalized": "01234567",
          "field_requirement_uid": "3f17e567-77c2-49e1-9eb2-2d8d901a4bb7",
          "display_name": "PZN",
          "field_type": "TEXT"
        }
      }
    }
  ],
  "totalRegistries": 1,
  "totalPages": 1
}
```

## Get a Listing Request

```bash theme={null}
GET /v1/management/listing-requests/{listing_request_uid}
```

**Required permission:** `listing_request:read`

<ParamField path="listing_request_uid" type="string" required>
  Listing request UID
</ParamField>

#### Example Request

```bash theme={null}
curl -X GET "https://api.rxscale.com/v1/management/listing-requests/7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -H "X-API-Key: your-api-key-here"
```

#### Response

```json theme={null}
{
  "uid": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "shop_uid": "a8c829ca-de1a-4b5e-9f6d-c1957d28aa4a",
  "pharmacy_uid": "22c49130-90aa-4384-aff2-4551f227cab4",
  "product_name": "Ibuprofen 400mg",
  "price_indication": 1250,
  "additional_notes": null,
  "status": "PENDING",
  "decision_note": null,
  "decided_at": null,
  "decided_by_user_uid": null,
  "decided_by_identifier": null,
  "extras": {
    "pzn": {
      "value": "01234567",
      "value_normalized": "01234567",
      "field_requirement_uid": "3f17e567-77c2-49e1-9eb2-2d8d901a4bb7",
      "display_name": "PZN",
      "field_type": "TEXT"
    }
  }
}
```

A missing UID, or a UID that belongs to another organisation, returns `404`.

## Accept a Listing Request

```bash theme={null}
POST /v1/management/listing-requests/{listing_request_uid}/accept
```

Records an accept decision. Does **not** create catalog products or push to a
storefront.

**Required permission:** `listing_request:write`

<ParamField path="listing_request_uid" type="string" required>
  Listing request UID
</ParamField>

<ParamField body="decision_note" type="string">
  Optional note stored with the decision
</ParamField>

#### Example Request

```bash theme={null}
curl -X POST "https://api.rxscale.com/v1/management/listing-requests/7c9e6679-7425-40de-944b-e07fc1f90ae7/accept" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"decision_note": "Will list internally"}'
```

Only `PENDING` requests can be accepted. A request that is already decided
returns `400`.

## Decline a Listing Request

```bash theme={null}
POST /v1/management/listing-requests/{listing_request_uid}/decline
```

Records a decline decision.

**Required permission:** `listing_request:write`

<ParamField path="listing_request_uid" type="string" required>
  Listing request UID
</ParamField>

<ParamField body="decision_note" type="string">
  Optional note stored with the decision
</ParamField>

#### Example Request

```bash theme={null}
curl -X POST "https://api.rxscale.com/v1/management/listing-requests/7c9e6679-7425-40de-944b-e07fc1f90ae7/decline" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"decision_note": "Already listed under a different SKU"}'
```

Only `PENDING` requests can be declined. A request that is already decided
returns `400`.