> ## Documentation Index > Fetch the complete documentation index at: https://docs.loopreturns.com/llms.txt > Use this file to discover all available pages before exploring further. # Regenerate Label > Queue a new Loop label for a return that already has one, for example when the original label expired before the shopper dropped off the package. This does the same thing as a merchant clicking Regenerate label on the return in Loop admin. The request only checks that the return can be regenerated and then queues the work. The regeneration runs asynchronously in the background, and the response returns before the new label is bought. #### Required API key scope - Returns A key without the Returns scope gets a `403`, even if it has Labels write. #### Which returns can be regenerated - The return must be open. - The return must not use third party labels. Third party label returns are not supported by this endpoint. - The return must not have multiple labels enabled. - The return must have exactly one label bought through Loop. - That label must still be `new` or `pre_transit`. A label that has been scanned or is already in the carrier network (for example `in_transit`, `out_for_delivery`, or `delivered`) is left in place and cannot be regenerated. #### Retrieving the New Label After the request is queued (202 response), call [Get Return Details](/api-reference/latest/return-data/get-return-details) to read the new label from the `labels` array once it is ready. If the background regeneration fails, the failure is stored the same way as for [Generate Label](/api-reference/latest/label-requests/generate-label). The old label has already been removed at that point, so a retry of this endpoint returns `unexpected_label_count`, and a Generate Label call can return `label_generation_failed`. #### Successful Response Returns HTTP 202 (Accepted) when the label regeneration has been successfully queued. A repeat call while a regeneration for the same return is still pending is also accepted with 202, and the regeneration is not queued again. #### Error Responses - **401 Unauthorized**: The request could not be authorized - **403 Forbidden**: The API key does not have the Returns scope - **404 Not Found** (`return_not_found`): The specified return does not exist - **409 Conflict** (`label_in_use`): The label has already been scanned or is in the carrier network, so it is not `new` or `pre_transit`. The existing label is left in place - **422 Unprocessable Entity** (`return_not_open`): The return is not open - **422 Unprocessable Entity** (`third_party_labels_not_supported`): The return uses third party labels - **422 Unprocessable Entity** (`unexpected_label_count`): The return does not have exactly one label bought through Loop, or the return has multiple labels enabled. This is also returned when no label is left after a failed regeneration - **422 Unprocessable Entity** (`label_generation_failed`): A previous label generation or regeneration job for this return failed ## OpenAPI ````yaml post /returns/{returnId}/labels/regenerate openapi: 3.1.0 info: title: Labels API description: API for managing label requests version: v1 servers: - url: https://api.loopreturns.com/api/2026-10 description: 2026-10 (Stable) - url: https://api.loopreturns.com/api/2026-07 description: 2026-07 - url: https://api.loopreturns.com/api/unstable description: Unstable (Preview) security: [] tags: - name: Label Requests paths: /returns/{returnId}/labels/regenerate: post: tags: - Label Requests summary: Regenerate Label description: > Queue a new Loop label for a return that already has one, for example when the original label expired before the shopper dropped off the package. This does the same thing as a merchant clicking Regenerate label on the return in Loop admin. The request only checks that the return can be regenerated and then queues the work. The regeneration runs asynchronously in the background, and the response returns before the new label is bought. #### Required API key scope - Returns A key without the Returns scope gets a `403`, even if it has Labels write. #### Which returns can be regenerated - The return must be open. - The return must not use third party labels. Third party label returns are not supported by this endpoint. - The return must not have multiple labels enabled. - The return must have exactly one label bought through Loop. - That label must still be `new` or `pre_transit`. A label that has been scanned or is already in the carrier network (for example `in_transit`, `out_for_delivery`, or `delivered`) is left in place and cannot be regenerated. #### Retrieving the New Label After the request is queued (202 response), call [Get Return Details](/api-reference/latest/return-data/get-return-details) to read the new label from the `labels` array once it is ready. If the background regeneration fails, the failure is stored the same way as for [Generate Label](/api-reference/latest/label-requests/generate-label). The old label has already been removed at that point, so a retry of this endpoint returns `unexpected_label_count`, and a Generate Label call can return `label_generation_failed`. #### Successful Response Returns HTTP 202 (Accepted) when the label regeneration has been successfully queued. A repeat call while a regeneration for the same return is still pending is also accepted with 202, and the regeneration is not queued again. #### Error Responses - **401 Unauthorized**: The request could not be authorized - **403 Forbidden**: The API key does not have the Returns scope - **404 Not Found** (`return_not_found`): The specified return does not exist - **409 Conflict** (`label_in_use`): The label has already been scanned or is in the carrier network, so it is not `new` or `pre_transit`. The existing label is left in place - **422 Unprocessable Entity** (`return_not_open`): The return is not open - **422 Unprocessable Entity** (`third_party_labels_not_supported`): The return uses third party labels - **422 Unprocessable Entity** (`unexpected_label_count`): The return does not have exactly one label bought through Loop, or the return has multiple labels enabled. This is also returned when no label is left after a failed regeneration - **422 Unprocessable Entity** (`label_generation_failed`): A previous label generation or regeneration job for this return failed operationId: regenerate-label parameters: - in: path name: returnId schema: type: integer example: 12345 required: true description: The unique identifier for the return, created by Loop. responses: '202': description: Label regeneration queued successfully content: application/json: schema: $ref: '#/components/schemas/GenerateLabelResponse' example: message: Label regeneration queued returnId: 12345 '401': $ref: '#/components/responses/Unauthorized' '403': description: The API key does not have the Returns scope. content: application/json: schema: $ref: '#/components/schemas/LabelOperationError' example: errors: Unauthorized. '404': $ref: '#/components/responses/GenerateLabelNotFound' '409': $ref: '#/components/responses/RegenerateLabelConflict' '422': $ref: '#/components/responses/RegenerateLabelUnprocessableEntity' security: - oauth2: - returns - returns: [] components: schemas: GenerateLabelResponse: type: object properties: message: type: string description: Confirmation message that label generation has been queued. example: Label generation queued returnId: type: integer format: int64 description: The return ID for which label generation was queued. example: 12345 required: - message - returnId LabelOperationError: type: object description: > Error envelope for a label or label-request failure response. Unlike the generic error responses, `errors` is a single message string rather than an object or array. required: - errors properties: errors: type: string example: Label not found. responses: Unauthorized: description: The request could not be authorized. content: application/json: schema: type: object required: - errors properties: errors: type: string example: Unauthorized. GenerateLabelNotFound: description: The specified return could not be found. content: application/json: schema: type: object properties: code: type: string example: return_not_found errors: type: array items: type: string example: - Return not found. RegenerateLabelConflict: description: > The return's label has already been scanned or is in the carrier network, so it cannot be regenerated. The existing label is left in place. content: application/json: schema: type: object properties: code: type: string enum: - label_in_use example: label_in_use errors: type: array items: type: string example: - Return [12345] has a label that is already in use. RegenerateLabelUnprocessableEntity: description: > The return is not eligible for label regeneration, or a previous label generation job for this return failed. content: application/json: schema: type: object properties: code: type: string enum: - return_not_open - third_party_labels_not_supported - unexpected_label_count - label_generation_failed example: return_not_open errors: type: array items: type: string example: - Return [12345] is not open. securitySchemes: oauth2: type: oauth2 flows: authorizationCode: authorizationUrl: https://oauth.loopreturns.com/authorize tokenUrl: https://oauth.loopreturns.com/oauth/token scopes: labels:read: Read access to labels labels:write: Create and modify labels label_requests:read: Read access to label requests label_requests:write: Create and modify label requests returns: Access to returns operations returns: name: X-Authorization type: apiKey in: header description: 'API Scope: "Returns"' x-scope: Returns ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.