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 paths: "/conditions": get: summary: List all conditions description: Returns a list of conditions. operationId: getConditions parameters: - $ref: "#/components/parameters/Limit" - $ref: "#/components/parameters/Page" tags: - Conditions responses: "429": $ref: "#/components/responses/TooManyRequests" "200": description: A paged array of conditions content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/Condition" nextPage: type: ["null", string] "/locations": get: summary: List all locations description: Returns a list of locations. operationId: getLocations parameters: - $ref: "#/components/parameters/Limit" - $ref: "#/components/parameters/Page" tags: - Locations responses: "429": $ref: "#/components/responses/TooManyRequests" "200": description: A paged array of locations content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/Location" nextPage: type: ["null", string] "/availability_timelines": get: summary: Variant availability timeline description: Returns per-day available inventory counts for a variant over a forward window. operationId: getAvailabilityTimeline parameters: - name: variant_shopify_id in: query required: true description: Shopify GraphQL ID numeric segment for the variant (same as storefront `variant_shopify_id`). schema: type: string - name: location_id in: query required: false description: When the shop has locations enabled, filter items to this Shopify location ID. schema: type: string - name: delivery_method_type in: query required: false description: Logistics profile used to pad unavailability (shipping or pick_up). Defaults to shipping. schema: type: string enum: [shipping, pick_up] tags: - AvailabilityTimelines responses: "429": $ref: "#/components/responses/TooManyRequests" "200": description: Availability timeline for the variant content: application/json: schema: $ref: "#/components/schemas/AvailabilityTimeline" "404": description: Variant not found for this shop content: application/json: schema: type: object required: [error] properties: error: type: string example: "Variant not found" "/blocked_dates": get: summary: List blocked dates description: | Returns manually blocked date ranges for items, variants, products, and the entire store. Rental scheduling blocks are excluded; only merchant-created blocked dates are returned. Use the `activeFrom` and `activeTo` filters to find blocked dates that overlap a calendar window. For incremental sync, use the `updated` filter together with `updatedAt` on each record. operationId: getBlockedDates parameters: - $ref: "#/components/parameters/Limit" - $ref: "#/components/parameters/Page" - name: resourceType in: query description: Filter by resource type. Comma-separated list of `Item`, `Shopify::Variant`, `Shopify::Product`, or `Shop`. required: false schema: type: string example: "Item,Shopify::Variant" - name: itemId in: query description: Filter blocked dates for a specific item ID. required: false schema: type: integer format: int64 - name: shopifyVariantId in: query description: Filter blocked dates for a specific Shopify variant ID. required: false schema: type: integer format: int64 - name: shopifyProductId in: query description: Filter blocked dates for a specific Shopify product ID. required: false schema: type: integer format: int64 - name: activeFrom in: query description: Return blocked dates that end on or after this calendar date (YYYY-MM-DD), including open-ended blocks. required: false schema: type: string format: date - name: activeTo in: query description: Return blocked dates that start on or before this calendar date (YYYY-MM-DD), including open-ended blocks. required: false schema: type: string format: date - name: search in: query description: Filter blocked dates by description text. required: false schema: type: string - name: created in: query description: Filter blocked dates by created at datetime (ISO 8601), using gt, lt, gte, lte operators which may be combined. required: false schema: type: object $ref: "#/components/schemas/DateRangeFilter" - name: updated in: query description: Filter blocked dates by when they were last updated (ISO 8601), using gt, lt, gte, lte; operators may be combined. required: false schema: type: object $ref: "#/components/schemas/DateRangeFilter" tags: - BlockedDates responses: "429": $ref: "#/components/responses/TooManyRequests" "200": description: A paged array of blocked dates content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/BlockedDate" nextPage: type: ["null", string] "404": description: Filtered resource not found for this shop content: application/json: schema: type: object required: [error] properties: error: type: string example: "Blocked date not found" post: summary: Create a blocked date description: | Creates a manually blocked date range for an item, variant, product, or the entire store. Rental scheduling blocks cannot be created through this endpoint. Specify the resource with `resourceType` and `resourceId` (Supercycle internal IDs). Calendar dates are inclusive; omit `from` or `to` for open-ended blocks. operationId: postBlockedDate requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/BlockedDateCreate" tags: - BlockedDates responses: "429": $ref: "#/components/responses/TooManyRequests" "201": description: Blocked date created successfully content: application/json: schema: $ref: "#/components/schemas/BlockedDate" "404": description: Resource not found for this shop content: application/json: schema: type: object required: [error] properties: error: type: string example: "Resource not found" "422": $ref: "#/components/responses/UnprocessableEntity" "/blocked_dates/{blockedDateId}": get: summary: Get a blocked date description: Returns a single manually blocked date range by ID. operationId: getBlockedDate parameters: - name: blockedDateId in: path required: true schema: type: integer format: int64 description: Numeric ID of the blocked date. tags: - BlockedDates responses: "429": $ref: "#/components/responses/TooManyRequests" "200": description: Blocked date details content: application/json: schema: $ref: "#/components/schemas/BlockedDate" "404": description: Blocked date not found content: application/json: schema: type: object required: [error] properties: error: type: string example: "Blocked date not found" "/custom_field_definitions": get: summary: List custom field definitions description: Returns a list of custom field definitions filtered by owner type. operationId: getCustomFieldDefinitions parameters: - $ref: "#/components/parameters/Limit" - $ref: "#/components/parameters/Page" - name: owner_type in: query description: Filter definitions by owner type (required) required: true schema: type: string enum: [item, rental] tags: - CustomFieldDefinitions responses: "429": $ref: "#/components/responses/TooManyRequests" "200": description: A paged array of custom field definitions content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/CustomFieldDefinition" nextPage: type: ["null", string] "400": description: Bad request - missing or invalid owner_type content: application/json: schema: type: object properties: error: type: string example: "owner_type parameter is required (item or rental)" "/custom_field_definitions/{id}": parameters: - $ref: "#/components/parameters/CustomFieldDefinitionId" get: summary: Retrieve a custom field definition description: Returns details of a specific custom field definition. operationId: getCustomFieldDefinition tags: - CustomFieldDefinitions responses: "429": $ref: "#/components/responses/TooManyRequests" "200": description: Expected response to a valid request content: application/json: schema: $ref: "#/components/schemas/CustomFieldDefinition" "/custom_fields": post: summary: Create a custom field description: Create a custom field on an item or rental. Specify the definition either by definitionId, or by key and ownerType. operationId: postCustomField requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CustomFieldCreate" tags: - CustomFields responses: "429": $ref: "#/components/responses/TooManyRequests" "201": description: Custom field created successfully content: application/json: schema: $ref: "#/components/schemas/CustomField" "422": $ref: "#/components/responses/UnprocessableEntity" "/custom_fields/{id}": parameters: - $ref: "#/components/parameters/CustomFieldId" put: summary: Update a custom field description: Update the value of an existing custom field. operationId: putCustomField requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CustomFieldUpdate" tags: - CustomFields responses: "429": $ref: "#/components/responses/TooManyRequests" "200": description: Custom field updated successfully content: application/json: schema: $ref: "#/components/schemas/CustomField" "422": $ref: "#/components/responses/UnprocessableEntity" delete: summary: Delete a custom field description: Delete an existing custom field. operationId: deleteCustomField tags: - CustomFields responses: "429": $ref: "#/components/responses/TooManyRequests" "204": description: Custom field deleted successfully "404": description: Custom field not found "/items": get: summary: List all items description: Returns a list of items and their details given parameters. Used by merchants to view their inventory. operationId: getItems parameters: - $ref: "#/components/parameters/Limit" - $ref: "#/components/parameters/Page" - name: sku in: query description: Filter items by Shopify variant SKU schema: type: string - name: serial in: query description: Filter items by serial schema: type: string - name: search in: query description: Filter items by titles, serials and SKU schema: type: string - name: visibility in: query description: Filter items by visibility status schema: type: string enum: [available, unavailable, sold, retired] - name: withActiveRental in: query description: When true, filter rentals by ones with active rentals required: false allowEmptyValue: true schema: type: boolean default: false - name: activeReturnOrderStatus 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" tags: - Items responses: "429": $ref: "#/components/responses/TooManyRequests" "200": description: A paged array of items content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/Item" nextPage: type: ["null", string] post: summary: Create an item description: Create a new item against a product that has already been imported into Supercycle. operationId: postItems requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ItemCreate" tags: - Items responses: "429": $ref: "#/components/responses/TooManyRequests" "200": description: Expected response to a valid request content: application/json: schema: type: array items: $ref: "#/components/schemas/Item" "422": $ref: "#/components/responses/UnprocessableEntity" "/items/{itemId}": parameters: - $ref: "#/components/parameters/ItemId" get: summary: Retrieve an item description: Returns all fields on an item. Can include timeline events if requested. operationId: getItem tags: - Items responses: "429": $ref: "#/components/responses/TooManyRequests" "200": description: Expected response to a valid request content: application/json: schema: $ref: "#/components/schemas/Item" put: summary: Update an item description: Update an item's serial, condition, processing status, or, in future, its metafields. operationId: putItem requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ItemUpdate" tags: - Items responses: "429": $ref: "#/components/responses/TooManyRequests" "200": description: Expected response to a valid request content: application/json: schema: $ref: "#/components/schemas/Item" "422": $ref: "#/components/responses/UnprocessableEntity" "/products": get: summary: List all products description: Returns a list of all products in Supercycle. Likely to be used in conjunction with Shopify API to display information about the products. operationId: getProducts parameters: - $ref: "#/components/parameters/Limit" - $ref: "#/components/parameters/Page" - name: search in: query description: Filter items by product title and variant SKU required: false schema: type: string tags: - Products responses: "429": $ref: "#/components/responses/TooManyRequests" "200": description: A paged array of products content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/Product" nextPage: type: ["null", string] post: summary: Import products description: Import Shopify products into Supercycle by list. operationId: postProductsImport requestBody: required: true content: application/json: schema: type: object properties: productIds: type: array items: type: integer format: int64 tags: - Products responses: "429": $ref: "#/components/responses/TooManyRequests" "201": description: An array of imported product IDs content: application/json: schema: type: object properties: productIds: type: array items: type: integer format: int64 "/products/{productId}/subscription_method": post: summary: Create or update subscription method description: Creates or updates a subscription method for a product. operationId: postProductSubscriptionMethod parameters: - name: productId in: path required: true description: The Shopify product ID schema: type: integer format: int64 requestBody: required: true content: application/json: schema: type: object properties: status: type: string enum: [enabled, disabled] optionsAttributes: type: array items: $ref: "#/components/schemas/SubscriptionOptionInput" tags: - Products responses: "429": $ref: "#/components/responses/TooManyRequests" "200": description: The updated subscription method content: application/json: schema: $ref: "#/components/schemas/SubscriptionMethod" "201": description: The created subscription method content: application/json: schema: $ref: "#/components/schemas/SubscriptionMethod" "404": description: Product not found content: application/json: schema: type: object properties: message: type: string "422": $ref: "#/components/responses/UnprocessableEntity" "/products/{productId}/subscription_method/options": post: summary: Create subscription method option description: Creates an option for a product's subscription method. If the method does not exist, it is created first. operationId: postProductSubscriptionMethodOption parameters: - name: productId in: path required: true description: The Shopify product ID schema: type: integer format: int64 requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/SubscriptionOptionInput" tags: - Products responses: "429": $ref: "#/components/responses/TooManyRequests" "201": description: The created subscription method option content: application/json: schema: $ref: "#/components/schemas/SubscriptionOption" "404": description: Product not found content: application/json: schema: type: object properties: message: type: string "422": $ref: "#/components/responses/UnprocessableEntity" "/products/{productId}/calendar_method": post: summary: Create or update calendar method description: Creates or updates a calendar method for a product. operationId: postProductCalendarMethod parameters: - name: productId in: path required: true description: The Shopify product ID schema: type: integer format: int64 requestBody: required: true content: application/json: schema: type: object properties: status: type: string enum: [enabled, disabled] customRestockDurationCount: type: integer optionsAttributes: type: array items: $ref: "#/components/schemas/CalendarOptionInput" tags: - Products responses: "429": $ref: "#/components/responses/TooManyRequests" "200": description: The updated calendar method content: application/json: schema: $ref: "#/components/schemas/CalendarMethod" "201": description: The created calendar method content: application/json: schema: $ref: "#/components/schemas/CalendarMethod" "/products/{productId}/calendar_method/options": post: summary: Create calendar method option description: Creates an option for a product's calendar method. If the method does not exist, it is created first. operationId: postProductCalendarMethodOption parameters: - name: productId in: path required: true description: The Shopify product ID schema: type: integer format: int64 requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CalendarOptionInput" tags: - Products responses: "429": $ref: "#/components/responses/TooManyRequests" "201": description: The created calendar method option content: application/json: schema: $ref: "#/components/schemas/CalendarOption" "404": description: Product not found content: application/json: schema: type: object properties: message: type: string "422": $ref: "#/components/responses/UnprocessableEntity" "/products/{productId}/membership_method": post: summary: Create or update membership method description: Creates or updates a membership method for a product. operationId: postProductMembershipMethod parameters: - name: productId in: path required: true description: The Shopify product ID schema: type: integer format: int64 requestBody: required: true content: application/json: schema: type: object properties: status: type: string enum: [enabled, disabled] optionsAttributes: type: array items: $ref: "#/components/schemas/MembershipOptionInput" tags: - Products responses: "429": $ref: "#/components/responses/TooManyRequests" "200": description: The updated membership method content: application/json: schema: $ref: "#/components/schemas/MembershipMethod" "201": description: The created membership method content: application/json: schema: $ref: "#/components/schemas/MembershipMethod" "/products/{productId}/membership_method/options": post: summary: Create membership method option description: Creates an option for a product's membership method. If the method does not exist, it is created first. operationId: postProductMembershipMethodOption parameters: - name: productId in: path required: true description: The Shopify product ID schema: type: integer format: int64 requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/MembershipOptionInput" tags: - Products responses: "429": $ref: "#/components/responses/TooManyRequests" "201": description: The created membership method option content: application/json: schema: $ref: "#/components/schemas/MembershipOption" "404": description: Product not found content: application/json: schema: type: object properties: message: type: string "422": $ref: "#/components/responses/UnprocessableEntity" "/products/{productId}/resale_method": post: summary: Create or update resale method description: Creates or updates a resale method for a product. operationId: postProductResaleMethod parameters: - name: productId in: path required: true description: The Shopify product ID schema: type: integer format: int64 requestBody: required: true content: application/json: schema: type: object properties: status: type: string enum: [enabled, disabled] optionsAttributes: type: array items: $ref: "#/components/schemas/ResaleOptionInput" tags: - Products responses: "429": $ref: "#/components/responses/TooManyRequests" "200": description: The updated resale method content: application/json: schema: $ref: "#/components/schemas/ResaleMethod" "201": description: The created resale method content: application/json: schema: $ref: "#/components/schemas/ResaleMethod" "/products/{productId}/resale_method/options": post: summary: Create resale method option description: Creates an option for a product's resale method. If the method does not exist, it is created first. operationId: postProductResaleMethodOption parameters: - name: productId in: path required: true description: The Shopify product ID schema: type: integer format: int64 requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ResaleOptionInput" tags: - Products responses: "429": $ref: "#/components/responses/TooManyRequests" "201": description: The created resale method option content: application/json: schema: $ref: "#/components/schemas/ResaleOption" "404": description: Product not found content: application/json: schema: type: object properties: message: type: string "422": $ref: "#/components/responses/UnprocessableEntity" "/cycles": get: summary: List all cycles description: | Returns a list of cycles given parameters. Used by merchants to see cycles due for dispatch, return etc. For incremental sync, use the updated filter together with the updatedAt field on each cycle so you only fetch or process cycles that changed since your last request. operationId: getCycles parameters: - $ref: "#/components/parameters/Limit" - $ref: "#/components/parameters/Page" - name: shopifyOrderId in: query description: Filter cycles by Shopify Order ID required: false schema: type: string - name: customerId in: query description: Filter cycles 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 cycles to show only unfulfilled ones required: false allowEmptyValue: true schema: type: boolean default: false - name: created in: query description: Filter cycles by created at datetime (ISO 8601), using gt, lt, gte, lte operators which may be combined. required: false schema: type: object $ref: "#/components/schemas/DateRangeFilter" - name: updated in: query description: Filter cycles 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: type: object $ref: "#/components/schemas/DateRangeFilter" - name: rentalStart in: query description: Filter cycles by cycle start date (ISO 8601), using gt, lt, gte, lte operators which may be combined. required: false schema: type: object $ref: "#/components/schemas/DateRangeFilter" - name: receiveAt in: query description: Filter cycles by scheduled receive date (ISO 8601), using gt, lt, gte, lte operators which may be combined. required: false schema: type: object $ref: "#/components/schemas/DateRangeFilter" - name: receivedAt in: query description: Filter cycles by when they were received back from the customer (ISO 8601), using gt, lt, gte, lte operators which may be combined. required: false schema: type: object $ref: "#/components/schemas/DateRangeFilter" - name: fulfilledAt in: query description: Filter cycles by when they were fulfilled (ISO 8601), using gt, lt, gte, lte operators which may be combined. required: false schema: type: object $ref: "#/components/schemas/DateRangeFilter" - name: fulfillmentStatus in: query description: Filter cycles by fulfillment status, can be a comma-separated list of statuses. Use "overdue" to find cycles 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 cycles by receival status, can be a comma-separated list of statuses. Use "overdue" to find cycles 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 cycles by titles and customer text schema: type: string - name: excludeCancelled in: query description: When true, omit cycles that have been cancelled (cancelledAt set). Defaults to false so cancelled cycles 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" tags: - Cycles responses: "429": $ref: "#/components/responses/TooManyRequests" "200": description: A paged array of cycles content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/Rental" nextPage: type: ["null", string] "/cycles/{cycleId}": parameters: - $ref: "#/components/parameters/CycleId" get: summary: Retrieve a cycle description: View information about a single cycle. Can include timeline events if requested. operationId: getCycle tags: - Cycles responses: "429": $ref: "#/components/responses/TooManyRequests" "200": description: Expected response to a valid request content: application/json: schema: $ref: "#/components/schemas/Rental" put: summary: Update a cycle description: Update details about a cycle - either edits or despatch/return information. Merchants may also update the Shopify order/fulfillment at the same time via the Shopify API. operationId: putCycle requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/RentalUpdate" tags: - Cycles responses: "429": $ref: "#/components/responses/TooManyRequests" "200": description: Expected response to a valid request content: application/json: schema: $ref: "#/components/schemas/Rental" "422": $ref: "#/components/responses/UnprocessableEntity" "/rentals": get: summary: List all rentals (deprecated alias of /cycles) 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 deprecated: true 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: type: object $ref: "#/components/schemas/DateRangeFilter" - 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: type: object $ref: "#/components/schemas/DateRangeFilter" - 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: type: object $ref: "#/components/schemas/DateRangeFilter" - 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: type: object $ref: "#/components/schemas/DateRangeFilter" - 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: type: object $ref: "#/components/schemas/DateRangeFilter" - name: fulfilledAt in: query description: Filter rentals by when they were fulfilled (ISO 8601), using gt, lt, gte, lte operators which may be combined. required: false schema: type: object $ref: "#/components/schemas/DateRangeFilter" - 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" tags: - Rentals responses: "429": $ref: "#/components/responses/TooManyRequests" "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] "/rentals/{rentalId}": parameters: - $ref: "#/components/parameters/RentalId" get: summary: Retrieve a rental (deprecated alias of /cycles/{cycleId}) description: View information about a single rental. Can include timeline events if requested. operationId: getRental deprecated: true tags: - Rentals responses: "429": $ref: "#/components/responses/TooManyRequests" "200": description: Expected response to a valid request content: application/json: schema: $ref: "#/components/schemas/Rental" put: summary: Update a rental (deprecated alias of /cycles/{cycleId}) description: Update details about a rental - either edits or despatch/return information. Merchants may also update the Shopify order/fulfillment at the same time via the Shopify API. operationId: putRental deprecated: true requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/RentalUpdate" tags: - Rentals responses: "429": $ref: "#/components/responses/TooManyRequests" "200": description: Expected response to a valid request content: application/json: schema: $ref: "#/components/schemas/Rental" "422": $ref: "#/components/responses/UnprocessableEntity" "/return_orders": get: summary: List all returns description: Get a list of returns, their details and items, given parameters. Used by merchants to list registered returns to start, or check if an item already exists in a return. operationId: getReturns parameters: - $ref: "#/components/parameters/Limit" - $ref: "#/components/parameters/Page" - name: search in: query description: Filter returns by formatted IDs and customer names required: false schema: type: string - name: status in: query description: Filter return orders by status, can be a comma-separated list of statuses required: false schema: type: string enum: [requested, expected, received, in_progress, completed, cancelled] tags: - ReturnOrders responses: "429": $ref: "#/components/responses/TooManyRequests" "200": description: A paged array of returns content: application/json: schema: type: object properties: data: type: array items: $ref: "#/components/schemas/ReturnOrder" nextPage: type: ["null", string] post: summary: Create a return description: Create a return by items. Return line statuses and conditions can be specified. If an item is in an existing return and has not active rentals, the endpoint updates the return line. If the item has multiple active rentals, the rental ID must be specified (return rental IDs with error). operationId: postReturn requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ReturnOrderCreate" tags: - ReturnOrders responses: "429": $ref: "#/components/responses/TooManyRequests" "200": description: Expected response to a valid request content: application/json: schema: type: object properties: errors: type: array items: type: string example: "Invalid request body" returnOrders: type: array items: $ref: "#/components/schemas/ReturnOrder" "/return_orders/{returnOrderId}": parameters: - $ref: "#/components/parameters/ReturnOrderId" get: summary: Retrieve a return description: View information about a return. Can include timeline events if requested. operationId: getReturn tags: - ReturnOrders responses: "429": $ref: "#/components/responses/TooManyRequests" "200": description: Expected response to a valid request content: application/json: schema: $ref: "#/components/schemas/ReturnOrder" put: summary: Update a return description: Update the status of a return and its return lines. Allows updating the overall return order status and individual return line statuses. operationId: putReturn requestBody: required: true content: application/json: schema: type: object properties: status: type: string enum: [ requested, expected, received, in_progress, completed, cancelled, ] description: The overall status of the return order returnLines: type: array items: type: object properties: id: type: integer format: int64 description: Numeric ID of the return line to update status: type: string enum: [awaiting, received, missing] description: Status of the individual return line required: [id] tagsAttributes: type: array description: "Tags to add or remove. Entries are matched to the return's existing tags by title, so an unmatched title adds a new tag and a matched title with `_destroy: true` removes it. Removing an unmatched title is a no-op." items: type: object properties: title: type: string id: type: integer format: int64 _destroy: type: boolean description: Set true to remove the tag matched by title (or id). tags: - ReturnOrders responses: "429": $ref: "#/components/responses/TooManyRequests" "200": description: Expected response to a valid request content: application/json: schema: $ref: "#/components/schemas/ReturnOrder" "/membership_credits/{membershipCreditId}": parameters: - $ref: "#/components/parameters/MembershipCreditId" put: summary: Update a membership credit description: Return (recredit) or reclaim a membership credit on a rental. Set status to `returned` to credit the customer back, or `unreturned` to reclaim a previously returned credit. operationId: putMembershipCredit requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/MembershipCreditUpdate" tags: - Rentals responses: "429": $ref: "#/components/responses/TooManyRequests" "200": description: Expected response to a valid request content: application/json: schema: $ref: "#/components/schemas/MembershipCredit" "404": description: Membership credit not found content: application/json: schema: type: object properties: message: type: string "422": $ref: "#/components/responses/UnprocessableEntity" "/timeline_comments": post: summary: Create a timeline comment description: Creates a new comment associated with a timeline event for a specific resource in a shop. The resource must belong to the authenticated shop. operationId: postTimelineComment requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/TimelineCommentCreate" tags: - TimelineComments responses: "429": $ref: "#/components/responses/TooManyRequests" "201": description: Successfully created timeline comment content: application/json: schema: $ref: "#/components/schemas/TimelineComment" "403": description: Forbidden - Resource does not belong to the shop content: application/json: schema: type: object properties: error: type: string example: "Resource does not belong to the shop" "422": $ref: "#/components/responses/UnprocessableEntity" "/timeline_comments/{id}": delete: summary: Delete a timeline comment description: Deletes a timeline comment event for a specific shop. Only events with type 'comment' can be deleted. operationId: deleteTimelineComment parameters: - name: id in: path required: true schema: type: integer format: int64 description: Numeric ID of the timeline comment event to delete tags: - TimelineComments responses: "429": $ref: "#/components/responses/TooManyRequests" "204": description: Timeline comment successfully deleted "404": description: Timeline comment not found content: application/json: schema: type: object properties: error: type: string example: "Timeline comment not found" "422": description: Only comment events can be deleted content: application/json: schema: type: object properties: error: type: string example: "Only comment events can be deleted" tags: - name: AvailabilityTimelines - name: BlockedDates - name: Conditions - name: CustomFieldDefinitions - name: CustomFields - name: Items - name: Products - name: Variants - name: Cycles - name: Rentals - name: ReturnOrders - name: TimelineComments - name: Locations security: - bearerAuth: [] components: parameters: CustomFieldDefinitionId: name: id in: path required: true schema: type: integer description: Numeric ID of the custom field definition. CustomFieldId: name: id in: path required: true schema: type: integer description: Numeric ID of the custom field. ItemId: name: itemId in: path required: true schema: type: integer description: Numeric ID of the item to retrieve. 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 CycleId: name: cycleId in: path required: true schema: type: integer description: Numeric ID of the cycle to retrieve. RentalId: name: rentalId in: path required: true schema: type: integer description: Numeric ID of the rental to retrieve. ReturnOrderId: in: path name: returnOrderId schema: type: integer required: true description: Numeric ID of the return to retrieve. MembershipCreditId: in: path name: membershipCreditId schema: type: integer required: true description: Numeric ID of the membership credit to update. responses: UnprocessableEntity: description: Invalid request content: application/json: schema: type: object properties: errors: type: array items: type: string example: "Invalid request body" 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." schemas: AvailabilityTimeline: type: object unevaluatedProperties: false required: - occupancy - inventoryCount - futureAvailabilityInventoryCount - uncommitedInventoryCount properties: occupancy: type: object description: Map of ISO date strings (YYYY-MM-DD) to the count of items available on that day. additionalProperties: type: integer inventoryCount: type: integer description: Total items included in the timeline for this variant (after optional location filter). futureAvailabilityInventoryCount: type: integer description: Items not on an unbounded current rental (future availability scope). uncommitedInventoryCount: type: integer description: Items not on a current rental (uncommitted inventory). BlockedDateCreate: type: object unevaluatedProperties: false required: [resourceType, resourceId] properties: resourceType: type: string enum: [Item, Shopify::Variant, Shopify::Product, Shop] description: Type of resource the blocked dates apply to. Use `Shop` to block every product in the store. resourceId: type: integer format: int64 description: Numeric ID of the blocked resource in Supercycle. from: type: ["null", string] format: date description: First blocked calendar day (inclusive). Omit or null for an open-start block. to: type: ["null", string] format: date description: Last blocked calendar day (inclusive). Omit or null for an open-ended block. description: type: ["null", string] description: Optional note describing why the dates are blocked. BlockedDate: type: object unevaluatedProperties: false required: - id - createdAt - updatedAt - from - resourceType - resourceId - resource properties: id: type: integer format: int64 description: Numeric ID of the blocked date. description: type: ["null", string] description: Optional note describing why the dates are blocked. from: type: ["null", string] format: date description: First blocked calendar day (inclusive). Null when the block is open-start. to: type: ["null", string] format: date description: Last blocked calendar day (inclusive). Null when the block is open-ended. resourceType: type: string enum: [Item, Shopify::Variant, Shopify::Product, Shop] description: Type of resource the blocked dates apply to. Use `Shop` to block every product in the store. resourceId: type: integer format: int64 description: Numeric ID of the blocked resource in Supercycle. createdAt: type: string format: date-time description: When the blocked date was created. updatedAt: type: string format: date-time description: When the blocked date was last updated. resource: $ref: "#/components/schemas/BlockedDateResource" BlockedDateResource: type: object unevaluatedProperties: false required: [type, id, title] properties: type: type: string enum: [Item, Shopify::Variant, Shopify::Product, Shop] description: Type of the blocked resource. id: type: integer format: int64 description: Numeric ID of the blocked resource in Supercycle. formattedId: type: string description: Human-readable item number. Present when type is Item. title: type: string description: Display title for the blocked resource. imageUrl: type: ["null", string] description: Image URL for the blocked resource, when available. shopifyVariantId: type: ["null", integer] format: int64 description: Shopify variant ID when the resource is an item or variant. shopifyProductId: type: ["null", integer] format: int64 description: Shopify product ID when available for the blocked resource. shopifyDomain: type: ["null", string] description: Shopify domain when the resource is the entire store. 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. CustomFieldDefinition: type: object required: [id, key, name, ownerType, type, groupFulfillments] properties: id: type: integer format: int64 description: Numeric ID of the custom field definition. key: type: string description: Unique key identifier for the custom field. name: type: string description: Display name of the custom field. ownerType: type: string enum: [item, rental] description: Type of resource this custom field applies to. type: type: string enum: [ string, single_line_text_field, money, customer_reference, rental_reference, return_reference, multi_line_text_field, boolean, date, date_time, integer, item_reference, color, url, json, ] description: Data type of the custom field value. groupFulfillments: type: boolean description: Whether this field groups fulfillments together. 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, Cycle, Rental] description: Type of the owner resource. `Rental` is the legacy spelling of `Cycle`, returned only for rows created before the Rental -> Cycle data backfill. 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). CustomFieldCreate: type: object required: [owner_id, value] properties: definition_id: type: integer format: int64 description: ID of the custom field definition. Required if key/owner_type not provided. key: type: string description: Key of the custom field definition. Required with owner_type if definition_id not provided. owner_type: type: string enum: [item, rental] description: Type of owner resource. Required with key if definition_id not provided. owner_id: type: integer format: int64 description: ID of the item or rental to attach the custom field to. value: type: string description: Value of the custom field. CustomFieldUpdate: type: object required: [value] properties: value: type: string description: New value of the custom field. 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" - type: object description: Default address of the customer. $ref: "#/components/schemas/Address" email: type: ["null", string] firstName: type: ["null", string] lastName: type: ["null", string] shopifyId: type: integer format: int64 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) 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" - type: object $ref: "#/components/schemas/Condition" 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" - type: object description: Location of the item in the warehouse. $ref: "#/components/schemas/Location" 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" ItemCreate: type: object required: [shopifyVariantId, visibility] properties: shopifyVariantId: type: integer format: int64 quantity: type: integer maximum: 100 format: int32 description: "Number of items to create." serials: type: array items: type: string description: "Serials will be picked from the list and assigned to items." visibility: type: string enum: [available, unavailable, retired, sold] conditionId: oneOf: - type: "null" - type: integer format: int64 description: ID of the condition to set. May be null to remove condition. locationShopifyId: type: ["null", integer] format: int64 description: ID of the Shopify location to associate with the item. May be null if no specific location is needed. 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 needed. acquisitionCostCents: type: ["null", integer] description: Amount paid to acquire each new item, in cents. Applied to every created item when quantity > 1. May be null if not known yet. ItemUpdate: type: object properties: serial: type: ["null", string] shopifyVariantId: type: ["null", integer] status: type: string enum: [processed, unprocessed] visibility: type: string enum: [available, unavailable, retired, sold] conditionId: type: ["null", integer] description: ID of the condition to set. May be null to remove condition. locationShopifyId: type: ["null", integer] format: int64 description: ID of the Shopify location to associate with the item. May be null to remove location assignment. pickLocation: type: ["null", string] description: Physical location within warehouse using Zone-Aisle-Shelf-Bin format (e.g., "A1-02-B3"). May be null to remove pick location assignment. acquisitionCostCents: type: ["null", integer] description: Amount paid to acquire this item, in cents. May be null to clear. Product: type: object unevaluatedProperties: false required: [id, handle, title, createdAt, sequentialId, shopifyId] properties: id: type: integer format: int64 description: Numeric ID of the product. createdAt: type: string format: date-time handle: type: string imageUrl: type: ["null", string] sequentialId: type: integer format: int32 shopifyId: type: integer format: int64 title: type: string variants: type: array description: Variants of the product items: $ref: "#/components/schemas/Variant" readOnly: true Variant: type: object unevaluatedProperties: false required: [id, title, createdAt, imageUrl, shopifyId, sku] properties: id: type: integer format: int64 description: Numeric ID of the product. createdAt: type: string format: date-time imageUrl: type: ["null", string] shopifyId: type: integer format: int64 title: type: string sku: type: string 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. MembershipCreditUpdate: type: object required: [membershipCredit] properties: membershipCredit: type: object required: [status] properties: status: type: string enum: [unreturned, returned] description: Set to `returned` to recredit the customer, or `unreturned` to reclaim the credit. 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: type: object $ref: "#/components/schemas/Customer" item: type: object $ref: "#/components/schemas/Item" 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. prepareFrom: type: ["null", string] format: date-time description: Date and time preparation of the item starts ahead of fulfilment. 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" RentalUpdate: type: object properties: fulfillAt: type: [string] format: date-time fulfilledAt: type: ["null", string] format: date-time itemId: type: integer format: int64 reallocateConflictingRentals: type: boolean description: When true and itemId is changed, all other rentals on the newly assigned item are re-allocated to resolve conflicts. minimumRentalEnd: type: [string] format: date-time packingStatus: type: string enum: [pending, printed, packed] description: Status of the packing process. receiveAt: type: [string] format: date-time receivedAt: type: ["null", string] format: date-time restockBy: type: ["null", string] format: date description: Set the restock date (YYYY-MM-DD) on the rental's receival, overriding the computed restock buffer. Set null to revert to the computed date. prepareFrom: type: ["null", string] format: date description: Set the preparation start date (YYYY-MM-DD) on the rental's fulfillment, overriding the computed preparation buffer. Set null to revert to the computed date. rentalEnd: type: object properties: before: type: string format: date-time after: type: string format: date-time rentalStart: type: object properties: before: type: string format: date-time after: type: string format: date-time tagsAttributes: type: array description: "Tags to add or remove. Entries are matched to the rental's existing tags by title, so an unmatched title adds a new tag and a matched title with `_destroy: true` removes it. Removing an unmatched title is a no-op." items: type: object properties: title: type: string id: type: integer format: int64 _destroy: type: boolean description: Set true to remove the tag matched by title (or id). ReturnLine: type: object unevaluatedProperties: false required: [id, createdAt, rentalId, status] properties: id: type: integer format: int64 description: Numeric ID of the return line. createdAt: type: string format: date-time condition: oneOf: - type: "null" - type: object $ref: "#/components/schemas/Condition" item: type: object $ref: "#/components/schemas/Item" rentalId: type: integer format: int64 requestedAt: type: ["null", string] format: date-time restockedAt: type: ["null", string] format: date-time status: type: string enum: [awaiting, received, missing] description: Status of the return line. ReturnOrder: type: object required: [ id, createdAt, creditStatus, customer, returnLines, sequentialId, status, ] properties: id: type: integer format: int64 description: Numeric ID of the return. createdAt: type: string format: date-time creditStatus: type: string enum: [uncredited, partially_recredited, recredited] receivalStatus: type: string enum: [unreceived, partially_received, received] customer: type: object $ref: "#/components/schemas/Customer" returnLines: type: array items: type: object $ref: "#/components/schemas/ReturnLine" requestedAt: type: ["null", string] format: date-time sequentialId: type: integer format: int32 description: Sequential ID of the return. status: type: string enum: [requested, expected, received, in_progress, completed, cancelled] description: Status of the return. returnMethod: type: ["null", object] description: Return method information properties: type: type: string enum: [ReturnMethod::Collection, ReturnMethod::ReturnLabel] description: Type of return method trackingUrl: type: ["null", string] description: Tracking URL for return label method addressShopifyId: type: ["null", integer] format: int64 description: Shopify address ID for collection method collectionDate: type: ["null", string] format: date description: Collection date for collection method timelineEvents: type: array description: Timeline events for this return order items: $ref: "#/components/schemas/TimelineEvent" tags: type: array items: type: string ReturnOrderCreate: type: object required: [data] properties: data: type: array items: type: object required: [rentalId] properties: rentalId: type: integer format: int64 status: type: ["null", string] enum: [awaiting, received, missing] returnMethodAttributes: type: ["null", object] description: Return method attributes for creating return with specific method properties: type: type: string enum: [ReturnMethod::Collection, ReturnMethod::ReturnLabel] description: Type of return method to create trackingUrl: type: ["null", string] description: Tracking URL for return label method addressShopifyId: type: ["null", integer] format: int64 description: Shopify address ID for collection method collectionDate: type: ["null", string] format: date description: Collection date for collection method quantity: type: integer maximum: 100 format: int32 description: "Number of items to create." serials: type: array items: type: string description: "Serials will be picked from the list and assigned to items." visibility: type: string enum: [available, unavailable, retired, sold] TimelineComment: type: object unevaluatedProperties: false required: [id, eventableId, eventableType, eventType, message] 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, Cycle, ReturnOrder). Cycle rows created before the Rental -> Cycle rename returned `Rental` until the data backfill completed. eventType: type: string enum: [comment] description: Type of the timeline event. message: type: string description: The comment message associated with the timeline event. 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, Cycle, ReturnOrder). Cycle rows created before the Rental -> Cycle rename returned `Rental` until the data backfill completed. 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. 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. TimelineCommentCreate: type: object required: [timelineEvent] properties: timelineEvent: type: object required: [eventableId, eventableType, message] properties: eventableId: type: integer format: int64 description: Numeric ID of the resource to associate the comment with. eventableType: type: string enum: [Item, Cycle, Rental, ReturnOrder] description: Type of the resource, limited to Item, Cycle, or ReturnOrder. `Rental` is accepted forever as the legacy spelling of `Cycle`. message: type: string description: The comment message to be added to the timeline event. SubscriptionMethod: type: object required: [id, status, createdAt, updatedAt, options] properties: id: type: integer format: int64 status: type: string enum: [enabled, disabled] createdAt: type: string format: date-time updatedAt: type: string format: date-time options: type: array items: $ref: "#/components/schemas/SubscriptionOption" SubscriptionOption: type: object required: [id, name, recurringPriceCents, checkoutPriceCents, billingInterval, minimumTerm] properties: id: type: integer format: int64 name: type: string recurringPriceCents: type: integer description: Recurring price in cents. checkoutPriceCents: type: integer description: Initial checkout price in cents. Can differ from recurringPriceCents for introductory pricing. billingInterval: type: string description: "Billing interval in N.unit format. Valid units: second, minute, hour, day, week, month, year." example: "1.month" pattern: '^\d+\.(second|minute|hour|day|week|month|year)$' minimumTerm: type: string description: "Minimum rental term in N.unit format. Valid units: second, minute, hour, day, week, month, year." example: "1.month" pattern: '^\d+\.(second|minute|hour|day|week|month|year)$' depositVariantShopifyId: type: [integer, "null"] format: int64 description: Shopify variant ID of the deposit product variant associated with this option, if any. variantApplicationType: type: string enum: [all, some] description: Whether this option applies to all variants or only those listed in variantApplicationShopifyIds. marketApplicationType: type: string enum: [all, some] description: Whether this option applies to all markets or only those listed in marketApplicationShopifyIds. conditionApplicationType: type: string enum: [all, some] description: Whether this option applies to all item conditions or only those listed in conditionApplicationIds. variantApplicationShopifyIds: type: array description: "Shopify variant IDs this option applies to. Only relevant when variantApplicationType is 'some'." items: type: integer format: int64 marketApplicationShopifyIds: type: array description: "Shopify market IDs this option applies to. Only relevant when marketApplicationType is 'some'." items: type: integer format: int64 conditionApplicationIds: type: array description: "Internal Supercycle condition IDs this option applies to. Only relevant when conditionApplicationType is 'some'." items: type: integer format: int64 createdAt: type: string format: date-time updatedAt: type: string format: date-time SubscriptionOptionInput: type: object properties: id: type: integer format: int64 description: ID of an existing option to update. Omit when creating a new option. name: type: string recurringPriceCents: type: integer description: Recurring price in cents. checkoutPriceCents: type: integer description: Initial checkout price in cents. Can differ from recurringPriceCents for introductory pricing. billingInterval: type: string description: "Billing interval in N.unit format. Valid units: second, minute, hour, day, week, month, year." example: "1.month" pattern: '^\d+\.(second|minute|hour|day|week|month|year)$' minimumTerm: type: string description: "Minimum rental term in N.unit format. Valid units: second, minute, hour, day, week, month, year." example: "1.month" pattern: '^\d+\.(second|minute|hour|day|week|month|year)$' variantApplicationType: type: string enum: [all, some] description: Whether this option applies to all variants or only a specific subset. Defaults to 'all'. marketApplicationType: type: string enum: [all, some] description: Whether this option applies to all markets or only a specific subset. Defaults to 'all'. conditionApplicationType: type: string enum: [all, some] description: Whether this option applies to all item conditions or only a specific subset. Defaults to 'all'. _destroy: type: boolean description: When true and id is provided, deletes this option from the subscription method. CalendarMethod: type: object required: [id, status, createdAt, updatedAt, options] properties: id: type: integer format: int64 status: type: string customRestockDurationCount: type: ["null", integer] createdAt: type: string format: date-time updatedAt: type: string format: date-time options: type: array items: $ref: "#/components/schemas/CalendarOption" CalendarOption: type: object required: [id, name, durationCount, priceCents] properties: id: type: integer format: int64 name: type: string durationCount: type: integer priceCents: type: integer idVerificationRequired: type: boolean depositVariantShopifyId: type: [integer, "null"] format: int64 variantApplicationType: type: string marketApplicationType: type: string conditionApplicationType: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time CalendarOptionInput: type: object properties: id: type: integer format: int64 name: type: string durationCount: type: integer priceCents: type: integer idVerificationRequired: type: boolean depositVariantShopifyId: type: [integer, "null"] format: int64 variantApplicationType: type: string marketApplicationType: type: string conditionApplicationType: type: string variantApplicationShopifyIds: type: array items: type: integer format: int64 marketApplicationShopifyIds: type: array items: type: integer format: int64 conditionApplicationIds: type: array items: type: integer format: int64 _destroy: type: boolean MembershipMethod: type: object required: [id, status, createdAt, updatedAt, options] properties: id: type: integer format: int64 status: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time options: type: array items: $ref: "#/components/schemas/MembershipOption" MembershipOption: type: object required: [id, name, checkoutPriceCents, creditCost] properties: id: type: integer format: int64 name: type: string checkoutPriceCents: type: integer creditCost: type: integer variantApplicationType: type: string marketApplicationType: type: string conditionApplicationType: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time MembershipOptionInput: type: object properties: id: type: integer format: int64 name: type: string checkoutPriceCents: type: integer creditCost: type: integer variantApplicationType: type: string marketApplicationType: type: string conditionApplicationType: type: string variantApplicationShopifyIds: type: array items: type: integer format: int64 marketApplicationShopifyIds: type: array items: type: integer format: int64 conditionApplicationIds: type: array items: type: integer format: int64 _destroy: type: boolean ResaleMethod: type: object required: [id, status, createdAt, updatedAt, options] properties: id: type: integer format: int64 status: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time options: type: array items: $ref: "#/components/schemas/ResaleOption" ResaleOption: type: object required: [id, name, checkoutPriceCents, status] properties: id: type: integer format: int64 name: type: string status: type: string checkoutPriceCents: type: integer variantApplicationType: type: string marketApplicationType: type: string conditionApplicationType: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time ResaleOptionInput: type: object properties: id: type: integer format: int64 name: type: string status: type: string enum: [enabled, disabled] checkoutPriceCents: type: integer variantApplicationType: type: string marketApplicationType: type: string conditionApplicationType: type: string variantApplicationShopifyIds: type: array items: type: integer format: int64 marketApplicationShopifyIds: type: array items: type: integer format: int64 conditionApplicationIds: type: array items: type: integer format: int64 _destroy: type: boolean securitySchemes: bearerAuth: type: http scheme: bearer