> ## 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. # Start a file upload for a custom field > Reserve a direct upload for one file on a file-type custom field (such as an image). PUT the file's bytes to `directUpload.url` with `directUpload.headers`, then create or update the custom field with the returned `signedId` as its value. The file is checked against the definition's allowed types and maximum size before the upload is allowed. **Beta:** file custom fields are part of the improved custom fields, which are enabled per shop. For a shop without them this endpoint responds 403. ## OpenAPI ````yaml https://app.supercycle.com/docs/openapi-v1.yml post /custom_field_uploads 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, create, and delete 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: Cycles - name: Rentals - name: ReturnOrders - name: TimelineComments - name: Locations paths: /custom_field_uploads: post: tags: - CustomFields summary: Start a file upload for a custom field description: >- Reserve a direct upload for one file on a file-type custom field (such as an image). PUT the file's bytes to `directUpload.url` with `directUpload.headers`, then create or update the custom field with the returned `signedId` as its value. The file is checked against the definition's allowed types and maximum size before the upload is allowed. **Beta:** file custom fields are part of the improved custom fields, which are enabled per shop. For a shop without them this endpoint responds 403. operationId: postCustomFieldUpload requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CustomFieldUploadCreate' responses: '201': description: Upload reserved content: application/json: schema: $ref: '#/components/schemas/CustomFieldUpload' '403': description: Improved custom fields are not enabled for this shop content: application/json: schema: type: object properties: errors: type: array items: type: string example: Custom field uploads are not enabled for this shop '404': description: Custom field definition not found '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/TooManyRequests' components: schemas: CustomFieldUploadCreate: type: object required: - definition_id - blob properties: definition_id: type: integer format: int64 description: ID of a file-type custom field definition. blob: type: object required: - filename - byte_size - checksum - content_type properties: filename: type: string example: condition-front.jpg byte_size: type: integer description: Size of the file in bytes. checksum: type: string description: Base64-encoded MD5 digest of the file. content_type: type: string example: image/jpeg CustomFieldUpload: type: object unevaluatedProperties: false required: - signedId - filename - contentType - byteSize - checksum - directUpload properties: signedId: type: string description: Save this as the custom field's value once the file is uploaded. filename: type: string contentType: type: string byteSize: type: integer checksum: type: string directUpload: type: object required: - url - headers properties: url: type: string description: Short-lived URL to PUT the file's bytes to. headers: type: object description: Headers to send with the PUT, exactly as named. additionalProperties: type: string 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. securitySchemes: bearerAuth: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.