> For the complete documentation index, see [llms.txt](https://docs.productrentalspro.com/user-guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.productrentalspro.com/user-guide/integrations/developer-api.md).

# Developer API

Use PRP data in your own applications

{% hint style="warning" %}
API access requires the **Volume Plan**. Unfortunately, there are no exceptions to this.
{% endhint %}

{% hint style="info" %}
The API is new and **in Beta.** It is fully operational, however some request or response structures may change without backward compatibility. Any changes will be documented here.
{% endhint %}

The PRP Developer API allows you to fetch PRP data from your own external applications. It is currently read-only, with the exception of being able to write return tracking details against a rental.

It can be used to:

* fetch your store’s rentals, including by product or variant
* check whether a product/variants are available to rent for specified dates and delivery method
* write a return tracking number and return tracking link to a rental record in PRP&#x20;

{% hint style="warning" %}
Don't attempt to call the PRP API from your theme code. Client-side HTTP requests will expose your API key to anyone that can access your public website. API requests should only be made server-side from your application or service.
{% endhint %}

## API base URL

`https://api.productrentalspro.com/api/v1/`

## Authentication

{% hint style="info" %}
Create keys in the app under **Settings → API**. The full key is shown once. Store it then. You can create more than one key, and you can revoke a key at any time. A revoked key stops working immediately.
{% endhint %}

To authenticate, send both of these headers with every API request:

| Header                | Value                      |
| --------------------- | -------------------------- |
| Authorization         | `Bearer your_prp_api_key`  |
| X-Shopify-Shop-Domain | Your `*.myshopify.com` URL |

```
curl "https://api.productrentalspro.com/api/v1/rentals" \
  -H "Authorization: Bearer prp_YOUR_KEY" \
  -H "X-Shopify-Shop-Domain: your-store.myshopify.com"
```

A missing key, a wrong key, a wrong shop domain, and a method other than the one documented for that path all return the same body:

```json
{ "error": "Unauthorized" }
```

A valid key on a store that is not on an active Volume plan returns:

```json
{ "error": "Volume plan required" }
```

## Limits

| Limit                                         | Value                                |
| --------------------------------------------- | ------------------------------------ |
| Requests per store                            | 20 per minute, across every endpoint |
| Requests per IP                               | 20 per minute                        |
| Variants on one availability request          | 10                                   |
| Distinct products on one availability request | 1                                    |

Over the store or IP limit, the response is `429` with a `Retry-After` header. The value is the number of seconds to wait. Over the shared limit, the response is `503`.

```json
{ "error": "Too many requests" }
```

## Rental object

The same rental object is returned for all of the endpoints relating to fetching rental data.

Dates on the rental are `YYYY-MM-DD`. `createdAt` is the store’s timezone, formatted `YYYY-MM-DD HH:mm:ss`. `createdAtUtc` is the same clock time in UTC. If the store has no timezone, `createdAt` is UTC as well.

`deliveryAddress` is one string with line breaks, or `null` when the rental has no street address. The first line is the street, then apartment, then city, province, and postal code, then country.

`rentalStatus` is one of `reserved`, `confirmed`, `packed`, `dispatched`, `returned`, `cancelled`.

`deliveryMethod` is one of `pickup`, `post`, `local_delivery`.

`startBufferType` and `endBufferType` are `business_days` or `calendar_days`.

```json
{
  "rentalNumber": 1042,
  "shopifyOrderNumber": 1646,
  "rentalStatus": "confirmed",
  "deliveryMethod": "post",
  "startDate": "2026-11-01",
  "endDate": "2026-11-05",
  "startBuffer": 1,
  "startBufferType": "business_days",
  "endBuffer": 1,
  "endBufferType": "calendar_days",
  "customerFirstName": "Ada",
  "customerLastName": "Lovelace",
  "email": "ada@example.com",
  "phone": "+15555550123",
  "deliveryAddress": "123 Main St\nApt 4\nPortland, OR, 97201\nUnited States",
  "orderNotes": null,
  "rentalNotes": null,
  "returnTrackingNumber": null,
  "returnTrackingLink": null,
  "tags": ["vip"],
  "rentalItems": [
    {
      "shopifyProductId": "8351194874115",
      "shopifyVariantId": "44886557131011",
      "productName": "Camping tent",
      "variantName": "4-person",
      "quantity": 1
    }
  ],
  "createdAt": "2026-10-20 09:30:00",
  "createdAtUtc": "2026-10-20 16:30:00"
}
```

Rentals that do not have a rental number are left out of these responses.

## Endpoints

### Rental List Endpoints

`GET /api/v1/rentals`, `GET /api/v1/rentals/product/:productId`, and `GET /api/v1/rentals/variant/:variantId` return a list of rentals. Each of these endpoints share these query parameters.

| Parameter | Required | Notes                                                                   |
| --------- | -------- | ----------------------------------------------------------------------- |
| `limit`   | No       | Integer from 1 to 25. Defaults to 25.                                   |
| `cursor`  | No       | `nextCursor` from the previous page.                                    |
| `minDate` | No       | `YYYY-MM-DD`. Keeps rentals that end on or after this date.             |
| `maxDate` | No       | `YYYY-MM-DD`. Keeps rentals that start on or before this date.          |
| `sort`    | No       | `rentalNumber`, `startDate`, or `endDate`. Defaults to `rentalNumber`.  |
| `order`   | No       | `asc` or `desc`. Defaults to `desc`. `rentalNumber` can only be `desc`. |

With both `minDate` and `maxDate`, a rental is included when its dates overlap that range. Either parameter can be used on its own.

{% hint style="info" %}
`nextCursor` is an opaque string. Pass it back as `cursor` unchanged, with the same `sort` and `order`. Repeat `minDate`, `maxDate`, and any product or variant filters too. The cursor remembers the position in that sort, not the filters.
{% endhint %}

Stop when `nextCursor` is `null`. A full page includes a `nextCursor`. The following request can come back with an empty `rentals` array. That empty page means you are done.

Each of the Rental List endpoints returns data in the following form:

```json
{
  "rentals": [array of rental objects],
  "nextCursor": "eyJ2IjoxLCJzIjoicmVudGFsTnVtYmVyIiwiZCI6ImRlc2MiLCJyIjoxMDE4LCJpIjo1MH0"
}
```

#### Get rentals

`GET /api/v1/rentals`

Returns a page of the store’s rentals. With no `sort`, the page is newest rental number first.

```bash
curl "https://api.productrentalspro.com/api/v1/rentals?sort=endDate&order=asc&minDate=2026-11-01&maxDate=2026-11-30&limit=10" \
  -H "Authorization: Bearer prp_YOUR_KEY" \
  -H "X-Shopify-Shop-Domain: your-store.myshopify.com"
```

#### Get rentals for a product

`GET /api/v1/rentals/product/:productId`

`productId` is the Shopify product id. A rental is included when any of its line items is that product. The rental object still includes the rental’s other line items.

`404` when that product is not on your store. A product with no matching rentals returns an empty `rentals` array.

```bash
curl "https://api.productrentalspro.com/api/v1/rentals/product/8351194874115?minDate=2026-11-01" \
  -H "Authorization: Bearer prp_YOUR_KEY" \
  -H "X-Shopify-Shop-Domain: your-store.myshopify.com"
```

#### Get rentals for a variant

`GET /api/v1/rentals/variant/:variantId`

`variantId` is the Shopify variant id. A rental is included when any of its line items matches.

| Parameter                 | Required | Notes                                  |
| ------------------------- | -------- | -------------------------------------- |
| `includeMatchingVariants` | No       | `true` or `false`. Defaults to `true`. |

When `includeMatchingVariants` is `true`, rentals of other variants are included when every option matches except the duration option. A 3-day Red Medium and a 7-day Red Medium are returned together. A different color or size is not. If the product has no duration option, only the requested variant is returned.

Set `includeMatchingVariants` to `false` to keep rentals of that variant only.

`404` when that variant is not on your store. A variant with no matching rentals returns an empty `rentals` array.

```bash
curl "https://api.productrentalspro.com/api/v1/rentals/variant/44886557131011?includeMatchingVariants=false" \
  -H "Authorization: Bearer prp_YOUR_KEY" \
  -H "X-Shopify-Shop-Domain: your-store.myshopify.com"
```

### Get one rental by PRP rental ID

`GET /api/v1/rentals/:rentalNumber`

`rentalNumber` is the integer from Product Rentals Pro, not the Shopify order number.

```bash
curl "https://api.productrentalspro.com/api/v1/rentals/1042" \
  -H "Authorization: Bearer prp_YOUR_KEY" \
  -H "X-Shopify-Shop-Domain: your-store.myshopify.com"
```

```json
{ "rental": {rental object} }
```

`404` when that rental number is not on your store.

### Get rentals for a Shopify order

`GET /api/v1/rentals/order/:orderNumber`

`orderNumber` is the Shopify order number, such as `1646` from order `#1646`. One order can be linked to multiple rentals so the endpoint can also return multipl rentals. The response is newest rental number first.

```bash
curl "https://api.productrentalspro.com/api/v1/rentals/order/1646" \
  -H "Authorization: Bearer prp_YOUR_KEY" \
  -H "X-Shopify-Shop-Domain: your-store.myshopify.com"
```

```json
{ "rentals": [array of rental objects] }
```

`404` when the order has no rentals.

### Check availability

`POST /api/v1/availability`

Checks if a product/variant(s) are available for specific dates and delivery method.

Send `Content-Type: application/json` with JSON body containing the following properties.

{% hint style="info" %}
**Note** that only **one product can be requested** per request. Multiple variants of the same product can be requested.
{% endhint %}

| Field                      | Required                                                                                | Notes                                                         |
| -------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| `startDate`                | Yes                                                                                     | `YYYY-MM-DD`                                                  |
| `endDate`                  | <p>No if using predefined durations.<br>Yes if using manually-selected date ranges.</p> | `YYYY-MM-DD`                                                  |
| `deliveryMethod`           | Yes                                                                                     | `pickup`, `post`, or `local_delivery`                         |
| `items`                    | Yes                                                                                     | 1 to 10 rows. Every row must use the same `shopifyProductId`. |
| `items[].shopifyProductId` | Yes                                                                                     | Shopify product id, as a string                               |
| `items[].shopifyVariantId` | Yes                                                                                     | Shopify variant id, as a string                               |
| `items[].quantity`         | Yes                                                                                     | Integer from 1 to 999                                         |

**Example Request**

```bash
curl -X POST "https://api.productrentalspro.com/api/v1/availability" \
  -H "Authorization: Bearer prp_YOUR_KEY" \
  -H "X-Shopify-Shop-Domain: your-store.myshopify.com" \
  -H "Content-Type: application/json" \
  -d '{
    "startDate": "2026-11-01",
    "endDate": "2026-11-05",
    "deliveryMethod": "pickup",
    "items": [
      {
        "shopifyProductId": "8351194874115",
        "shopifyVariantId": "44886557131011",
        "quantity": 1
      }
    ]
  }'
```

**Example Response**

```json
{
  "results": [
    { "shopifyVariantId": "44886557131011", "available": true }
  ]
}
```

`available` is `false` when the variant is unavailable for the requested dates and delivery method.

### Set return tracking

`POST /api/v1/rentals/return-tracking`

Writes `returnTrackingNumber` and `returnTrackingLink` onto one rental. Send exactly one identifier.

`shopifyOrderId` is the Shopify order id, such as `5678901234567`, not the order number from `#1646`. A numeric value or `gid://shopify/Order/5678901234567` is accepted. When that order has one rental, the rental is updated. When it has more than one, nothing is written and the response lists each `rentalId` so you can update one of them.

`rentalId` is the rental id shown in Product Rentals Pro. It is the same integer as `rentalNumber` on the rental object.

| Field                  | Required                          | Notes                                                          |
| ---------------------- | --------------------------------- | -------------------------------------------------------------- |
| `shopifyOrderId`       | One of shopifyOrderId or rentalId | Shopify order ID, as a string or number. Not the order number. |
| `rentalId`             | One of shopifyOrderId or rentalId | Rental ID from Product Rentals Pro.                            |
| `returnTrackingNumber` | Yes                               | Non-empty string, up to 200 characters                         |
| `returnTrackingLink`   | Yes                               | `http` or `https` URL, up to 2000 characters                   |

**One rental on the order**

```bash
curl -X POST "https://app.productrentalspro.com/api/v1/rentals/return-tracking" \
  -H "Authorization: Bearer prp_YOUR_KEY" \
  -H "X-Shopify-Shop-Domain: your-store.myshopify.com" \
  -H "Content-Type: application/json" \
  -d '{
    "shopifyOrderId": "5678901234567",
    "returnTrackingNumber": "1Z999AA10123456784",
    "returnTrackingLink": "https://www.ups.com/track?tracknum=1Z999AA10123456784"
  }'
```

```json
{
  "rentalId": 1042,
  "returnTrackingNumber": "1Z999AA10123456784",
  "returnTrackingLink": "https://www.ups.com/track?tracknum=1Z999AA10123456784"
}
```

**Several rentals on the order.** Nothing is written.

```json
{
  "error": "Multiple rentals match this order",
  "rentalIds": [1043, 1042]
}
```

Update one of those rentals with its `rentalId`:

```bash
curl -X POST "https://app.productrentalspro.com/api/v1/rentals/return-tracking" \
  -H "Authorization: Bearer prp_YOUR_KEY" \
  -H "X-Shopify-Shop-Domain: your-store.myshopify.com" \
  -H "Content-Type: application/json" \
  -d '{
    "rentalId": 1043,
    "returnTrackingNumber": "1Z999AA10123456784",
    "returnTrackingLink": "https://www.ups.com/track?tracknum=1Z999AA10123456784"
  }'
```

## Errors

Error bodies are JSON with one `error` string.

| Status | `error`                             | When                                                                                       |
| ------ | ----------------------------------- | ------------------------------------------------------------------------------------------ |
| 400    | `Invalid cursor`                    | `cursor` is not a cursor from this API, or it was issued for a different `sort` or `order` |
| 400    | `Invalid limit`                     | `limit` is not an integer from 1 to 25                                                     |
| 400    | `Invalid sort`                      | `sort` is not `rentalNumber`, `startDate`, or `endDate`, or rental number is not `desc`    |
| 400    | `Invalid order`                     | `order` is not `asc` or `desc`                                                             |
| 400    | `Invalid dates`                     | A date is not `YYYY-MM-DD`, is not a real calendar date, or `minDate` is after `maxDate`   |
| 400    | `Invalid product id`                | Product id in the path is not a Shopify product id                                         |
| 400    | `Invalid variant id`                | Variant id in the path is not a Shopify variant id                                         |
| 400    | `Invalid includeMatchingVariants`   | Not `true` or `false`                                                                      |
| 400    | `Invalid rental number`             | Rental number in the path is not a positive integer                                        |
| 400    | `Invalid order number`              | Order number in the path is not a positive integer                                         |
| 400    | `Invalid JSON`                      | Request body is not JSON                                                                   |
| 400    | `Invalid request`                   | Body is not an object, or return tracking does not send exactly one identifier             |
| 400    | `Invalid shopify order id`          | Not a Shopify order id. An `Order` gid is accepted and read as its numeric id              |
| 400    | `Invalid rental id`                 | Not the positive integer Product Rentals Pro shows as the rental id                        |
| 400    | `Invalid return tracking number`    | Missing, blank, or longer than 200 characters                                              |
| 400    | `Invalid return tracking link`      | Missing, blank, longer than 2000 characters, or not an `http` or `https` URL               |
| 400    | `Invalid delivery method`           | Not `pickup`, `post`, or `local_delivery`                                                  |
| 400    | `Invalid items`                     | Items are missing, empty, or a row is incomplete                                           |
| 400    | `Too many variants`                 | More than 10 items                                                                         |
| 400    | `Only one product is allowed`       | Items use more than one product id                                                         |
| 401    | `Unauthorized`                      | Key, shop, or method was not accepted                                                      |
| 403    | `Volume plan required`              | The store is not on an active Volume plan                                                  |
| 404    | `Not found`                         | No matching rental, product, or variant, or the path does not exist                        |
| 409    | `Multiple rentals match this order` | That Shopify order has more than one rental. Nothing is written. `rentalIds` lists them    |
| 413    | `Payload too large`                 | Availability body is over 16 KB                                                            |
| 429    | `Too many requests`                 | A per-store, per-IP, or failed-key limit was hit                                           |
| 503    | `Unavailable`                       | The API could not complete the request. Retry later                                        |
