> ## Documentation Index > Fetch the complete documentation index at: https://docs.supercycle.com/llms.txt > Use this file to discover all available pages before exploring further. # List all rentals > Returns a list of rentals given parameters. Used by merchants to see rentals due for dispatch, return etc. For incremental sync, use the updated filter together with the updatedAt field on each rental so you only fetch or process rentals that changed since your last request. ## OpenAPI ````yaml https://app.supercycle.com/docs/openapi-v1.yml get /rentals openapi: 3.1.0 info: title: Supercycle API version: 1.0.0 contact: name: Supercycle Support email: support@supercycle.com description: >+ The Supercycle API provides comprehensive endpoints designed to streamline inventory, rental, and return management for merchants using the Supercycle platform. This API facilitates the integration with external systems such as Shopify, enabling seamless synchronization of product data, rental operations, and returns processing. Key features include: - **Inventory Management:** Endpoints to create, update, and retrieve detailed information about items and products. - **Rental Operations:** Manage rentals from creation to dispatch, with automated serial allocation and synchronization with Shopify orders. - **Returns Processing:** Efficiently manage and track returns with the ability to update statuses and item conditions. - **Timeline Comments:** Add comments to timeline events associated with resources in a shop. - **Availability Timelines:** Per-variant day-by-day availability counts for back-office and OMS integrations (mirrors the storefront availability timeline). - **Blocked Dates:** List, retrieve, and create manually blocked date ranges on items, variants, and products that reduce availability. **Rate limits:** Requests are throttled per API key (Bearer token). Across all endpoints, a key may make at most **120 requests per minute**. The availability timeline endpoint (`GET /availability_timelines`) is limited to **10 requests per minute** per key because it is computationally expensive—cache responses client-side where possible. Requests without a Bearer token are limited to **30 requests per minute** per client IP. When exceeded, the API returns **429 Too Many Requests** with `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers. This API is essential for merchants looking to enhance their operational efficiency, providing the tools needed to manage their inventory, rentals, returns, timeline events, availability planning, and blocked dates all in one place. For support or enquiries, please contact [Supercycle Support](mailto:support@supercycle.com). servers: - url: https://app.supercycle.com/api/v1 security: - bearerAuth: [] tags: - name: AvailabilityTimelines - name: BlockedDates - name: Conditions - name: CustomFieldDefinitions - name: CustomFields - name: Items - name: Products - name: Variants - name: Rentals - name: ReturnOrders - name: TimelineComments - name: Locations paths: /rentals: get: tags: - Rentals summary: List all rentals description: > Returns a list of rentals given parameters. Used by merchants to see rentals due for dispatch, return etc. For incremental sync, use the updated filter together with the updatedAt field on each rental so you only fetch or process rentals that changed since your last request. operationId: getRentals parameters: - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Page' - name: shopifyOrderId in: query description: Filter rentals by Shopify Order ID required: false schema: type: string - name: customerId in: query description: Filter rentals by customer ID required: false schema: type: integer format: int64 - name: itemId in: query description: Filter by item ID required: false schema: type: integer format: int64 - name: shopifyVariantId in: query description: Filter by shopify variant ID required: false schema: type: integer format: int64 - name: shopifyLineItemId in: query description: Filter by shopify line item ID required: false schema: type: integer format: int64 - name: returnOrderStatus in: query description: >- Filter by return order status. Can be a comma-separated list of statuses. required: false schema: type: string example: requested,expected,received,in_progress,completed,cancelled - name: unfulfilled in: query description: When true, filter rentals to show only unfulfilled ones required: false allowEmptyValue: true schema: type: boolean default: false - name: created in: query description: >- Filter rentals by created at datetime (ISO 8601), using gt, lt, gte, lte operators which may be combined. required: false schema: $ref: '#/components/schemas/DateRangeFilter' type: object - name: updated in: query description: >- Filter rentals by when they were last updated (ISO 8601), using gt, lt, gte, lte; operators may be combined. For incremental sync, use gte (on or after) with the time you last pulled data. required: false schema: $ref: '#/components/schemas/DateRangeFilter' type: object - name: rentalStart in: query description: >- Filter rentals by rental start date (ISO 8601), using gt, lt, gte, lte operators which may be combined. required: false schema: $ref: '#/components/schemas/DateRangeFilter' type: object - name: receiveAt in: query description: >- Filter rentals by scheduled receive date (ISO 8601), using gt, lt, gte, lte operators which may be combined. required: false schema: $ref: '#/components/schemas/DateRangeFilter' type: object - name: receivedAt in: query description: >- Filter rentals by when they were received back from the customer (ISO 8601), using gt, lt, gte, lte operators which may be combined. required: false schema: $ref: '#/components/schemas/DateRangeFilter' type: object - name: fulfillmentStatus in: query description: >- Filter rentals by fulfillment status, can be a comma-separated list of statuses. Use "overdue" to find rentals whose fulfill date has passed but have not yet been fulfilled. required: false schema: type: string enum: - due - scheduled - overdue - complete - name: receivalStatus in: query description: >- Filter rentals by receival status, can be a comma-separated list of statuses. Use "overdue" to find rentals whose return date has passed but have not yet been received back. required: false schema: type: string enum: - due - scheduled - overdue - complete - name: search in: query description: Filter rentals by titles and customer text schema: type: string - name: excludeCancelled in: query description: >- When true, omit rentals that have been cancelled (cancelledAt set). Defaults to false so cancelled rentals are included for incremental sync and external dashboards. required: false schema: type: boolean default: false - name: include in: query description: Comma-separated list of relations to include (e.g., item) required: false schema: type: string example: item responses: '200': description: A paged array of rentals content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Rental' nextPage: type: - 'null' - string '429': $ref: '#/components/responses/TooManyRequests' components: parameters: Limit: name: limit in: query description: >- A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 50. required: false schema: type: integer maximum: 100 format: int32 Page: name: page in: query description: Cursor token to fetch next page of results. required: false schema: type: string schemas: DateRangeFilter: type: object properties: gt: type: string format: date description: After this date/time (ISO 8601) lt: type: string format: date description: Before this date/time (ISO 8601) gte: type: string format: date description: On or after this date/time (ISO 8601) lte: type: string format: date description: On or before this date/time (ISO 8601) Rental: type: object required: - id - createdAt - updatedAt - customer - itemId - packingStatus - shopifyOrderId - shopifyOrderLineId properties: id: type: integer format: int64 description: Numeric ID of the rental. methodType: type: string enum: - calendar - subscription - membership - resale description: Method type of the rental. createdAt: type: string format: date-time updatedAt: type: string format: date-time description: >- When this rental was last updated in Supercycle. Use with the list endpoint's updated filter to sync only rentals that changed since your last request. customer: $ref: '#/components/schemas/Customer' type: object item: $ref: '#/components/schemas/Item' type: object fulfillAt: type: - 'null' - string format: date-time description: Date and time the rental is due to be dispatched to the customer. fulfilledAt: type: - 'null' - string format: date-time description: Date and time the rental was dispatched to the customer. itemId: type: integer format: int64 minimumRentalEnd: type: - 'null' - string format: date-time originRentalIntentToken: type: - 'null' - string receiveAt: type: - 'null' - string format: date-time description: >- Date and time the rental is due to be received back from the customer. receivedAt: type: - 'null' - string format: date-time description: Date and time the rental was received back from the customer. rentalStart: type: - 'null' - string format: date-time description: >- Date and time the item was received by the customer and the rental period started. rentalEnd: type: - 'null' - string format: date-time description: Date and time the rental period is due to end. restockBy: type: - 'null' - string format: date-time description: Date and time the item is due to be restocked. restockedAt: type: - 'null' - string format: date-time description: Date and time the item was restocked. packingStatus: type: string enum: - pending - printed - packed description: Status of the packing process. sequentialId: oneOf: - type: 'null' - type: integer format: int32 description: Sequential ID of the rental. shopifyOrderName: type: string shopifyOrderId: type: integer format: int64 shopifyOrderLineId: type: integer format: int64 status: type: string enum: - scheduled - unfulfilled - fulfilled - unreceived - received - cancelled description: Status of the rental. fulfillmentStatus: type: string enum: - pending - scheduled - in_progress - overdue - complete description: >- Current fulfillment status of the rental. Indicates whether the item is due to be sent, scheduled, in progress, overdue, or has been dispatched. receivalStatus: type: string enum: - pending - scheduled - in_progress - overdue - complete description: >- Current receival status of the rental. Indicates whether the item is due to be returned, scheduled for return, overdue for return, or has been received back. returnOrderId: oneOf: - type: 'null' - type: integer format: int64 description: ID of the return order associated with this rental. membershipCredit: oneOf: - type: 'null' - $ref: '#/components/schemas/MembershipCredit' description: Membership credit associated with this rental, if any. timelineEvents: type: array description: Timeline events for this rental items: $ref: '#/components/schemas/TimelineEvent' tags: type: array items: type: string customFields: type: array description: Custom fields attached to this rental items: $ref: '#/components/schemas/CustomField' Customer: type: object unevaluatedProperties: false required: - id - createdAt - shopifyId properties: id: type: integer format: int64 description: Numeric ID of the customer. createdAt: type: string format: date-time defaultAddress: oneOf: - type: 'null' - $ref: '#/components/schemas/Address' type: object description: Default address of the customer. email: type: - 'null' - string firstName: type: - 'null' - string lastName: type: - 'null' - string shopifyId: type: integer format: int64 Item: type: object required: - id - createdAt - activeRentalId - productTitle - serial - sequentialId - shopifyVariantId - status - tags - variantTitle - visibility properties: id: type: integer format: int64 description: Numeric ID of the item. createdAt: type: string format: date-time activeRentalId: oneOf: - type: 'null' - type: integer format: int64 activeReturnId: oneOf: - type: 'null' - type: integer format: int64 condition: oneOf: - type: 'null' - $ref: '#/components/schemas/Condition' type: object conditionId: type: - 'null' - integer description: ID of the condition. May be null if no condition is set. imageUrl: type: - 'null' - string location: oneOf: - type: 'null' - $ref: '#/components/schemas/Location' type: object description: Location of the item in the warehouse. pickLocation: type: - 'null' - string description: >- Physical location within warehouse using Zone-Aisle-Shelf-Bin format (e.g., "A1-02-B3"). May be null if no pick location is set. acquisitionCostCents: type: - 'null' - integer description: Amount paid to acquire this item, in cents. May be null if not set. roiCents: type: - 'null' - integer description: >- Computed return on investment (lifecycle revenue minus acquisition cost), in cents. Null when acquisitionCostCents is null. productTitle: type: string serial: type: - 'null' - string sequentialId: type: integer format: int32 shopifyProductId: type: - 'null' - integer shopifyVariantId: type: - 'null' - integer status: type: string enum: - processed - unprocessed tags: type: array items: type: string variantTitle: type: - 'null' - string visibility: type: string enum: - available - unavailable - sold - retired timelineEvents: type: array description: Timeline events for this item items: $ref: '#/components/schemas/TimelineEvent' customFields: type: array description: Custom fields attached to this item items: $ref: '#/components/schemas/CustomField' MembershipCredit: type: object required: - id - creditCost - status properties: id: type: integer format: int64 description: Numeric ID of the membership credit. creditCost: type: integer description: Number of credits this rental costs the customer's membership. status: type: string enum: - unreturned - returned description: Whether the credit has been returned to the customer's membership. returnCondition: oneOf: - type: 'null' - type: string enum: - return_order_created - received_at description: >- When the credit is automatically returned, if configured on the shop. TimelineEvent: type: object required: - id - eventableId - eventableType - eventType properties: id: type: integer format: int64 description: Numeric ID of the timeline event. eventableId: type: integer format: int64 description: Numeric ID of the resource associated with the event. eventableType: type: string description: Type of the resource (e.g., Item, Rental, ReturnOrder). eventType: type: string description: Type of the timeline event. metadata: type: object description: Additional data associated with the timeline event. createdAt: type: string format: date-time description: Timestamp when the event was created. updatedAt: type: string format: date-time description: Timestamp when the event was last updated. author: type: string nullable: true description: Author of the timeline event. CustomField: type: object required: - id - ownerId - ownerType - definitionId - key - value properties: id: type: integer format: int64 description: Numeric ID of the custom field. ownerId: type: integer format: int64 description: ID of the item or rental that owns this custom field. ownerType: type: string enum: - Item - Rental description: Type of the owner resource. definitionId: type: integer format: int64 description: ID of the custom field definition. key: type: string description: Key of the custom field definition. value: type: string description: Raw stored value of the custom field. valueJson: description: >- Typed JSON value of the custom field (format depends on definition type). Address: type: object unevaluatedProperties: false required: - id - customerId - default properties: customerId: type: integer format: int64 description: Numeric ID of the customer. firstName: type: string lastName: type: string company: type: string address1: type: string address2: type: string city: type: string province: type: string country: type: string zip: type: string phone: type: string name: type: string provinceCode: type: string countryCode: type: string countryName: type: string default: type: boolean Condition: type: object unevaluatedProperties: false required: - id - createdAt - severityKey - severityTone - title properties: id: type: integer format: int64 description: Numeric ID of the condition. createdAt: type: string format: date-time description: Date and time the condition was created. severityKey: type: string description: Severity key of the condition. severityTone: type: string description: Tone of the condition. title: type: string description: Title of the condition. Location: type: object required: - shopifyId - name properties: shopifyId: type: integer format: int64 description: Numeric ID of the Shopify location. name: type: string description: Name of the location. responses: TooManyRequests: description: Rate limit exceeded headers: Retry-After: description: Seconds until the current throttle window resets. schema: type: integer example: 42 X-RateLimit-Limit: description: Maximum requests allowed in the window that triggered this response. schema: type: integer example: 120 X-RateLimit-Remaining: description: >- Remaining requests in the window (always 0 when this response is returned). schema: type: integer example: 0 X-RateLimit-Reset: description: ISO 8601 timestamp when the throttle window resets. schema: type: string format: date-time content: application/json: schema: type: object required: - error properties: error: type: string example: Rate limit exceeded. Retry after 42 seconds. securitySchemes: bearerAuth: type: http scheme: bearer ````