---
title: "Mutate Return Registration (Batch)"
method: POST
path: "/v4/returns/return-registrations/mutate/"
tags: ["Return Registration"]
---

# Mutate Return Registration (Batch)

`POST /v4/returns/return-registrations/mutate/`

## Request

- The document declares no server URL.
- Auth: one of:
  - API key in header `Authorization`
  - HTTP bearer

Return Registrations represent a return request from a customer. There might be multiple
return registrations for a single order. There might also be multiple labels for one return
registration, if requested by the customer.

 A return registration is linked to a configuration bundle (field 'code'), multiple configurations
 might be available on one account (e.g. country-specific courier configurations).

 Return registrations are created by the parcelLab return portal, or by the retailer via the parcelLab API.

Certain fields of the return registration are not mutable via requests on the registration resource, but require
'action' payloads to be submitted (e.g. 'AddLabel') to the 'mutate' action.

## Request body

- MutateReturnRegistrationCollectionRequest: Update (mutate) a return registration
  - `mutations` UpdateArticleStatusMutation[]
    - `operation_id` string, uuid: The unique ID of the operation, generated by parcelLab, if not provided
    - `result` MutationResult: The result of a mutation
      - `success` boolean: Whether the mutation was successful
      - `message` string: A message describing the result of the mutation
      - `errors` object: A dictionary of errors that occurred during the mutation
      - `warnings` string[]: Non-fatal warnings raised while processing the mutation
    - `type` 'update_article_status'
    - `account` integer, required: The account ID to create this return registration on.
    - `request` UpdateArticleStatusRequest, required
      - `identifier` string, required: Identifier of the return registration to update the status for
      - `identifier_type` 'reference' | 'external_id' | 'external_reference', required
      - `tracking_number` string, required: The tracking number to update the status for
      - `article_status_updates` ArticleStatusUpdate[]: The status updates for the articles
        - `fulfillment` string, nullable
        - `identifier` string, required: Identifier of the article to update the status for
        - `identifier_type` 'product_id' | 'line_item_id' | 'sku' | 'variant_id' | 'barcode' | 'order_item_id', required
        - `accepted_quantity` integer: The quantity of the article that was accepted
        - `rejected_quantity` integer: The quantity of the article that was rejected
        - `reason` string: The reason for the rejection of the article
        - `restock` boolean: Whether accepted returned items should be restocked
        - `status_reason_code` 'missing_quantity' | 'quality_issue' | 'other'
        - `condition` string: Condition of the received article
        - `article_images` ReturnImage[]: Images documenting the received article
          - `url` string, required
          - `name` string, required
          - `mime_type` string, required
      - `receive_status` ReceiveStatus, required: Receive status data stored when a return is processed via the staff receive flow.
        - `received_by` string: Identifier of the operator or station that received the return.
        - `received_at` string, date-time, nullable: Timestamp when the return was fully received.
        - `status` 'completely_rejected' | 'completely_accepted' | 'partially_accepted' | 'partially_received'
        - `receive_note` string, nullable: Optional note recorded during receive.
        - `receive_images` ReturnImage[]: URLs of captured evidence images.
          - `url` string, required
          - `name` string, required
          - `mime_type` string, required
        - `is_fully_received` boolean: Whether the return is fully processed in receive flow.
        - `label_notes` object: Internal notes keyed by tracking number.

## Response `200`

- ReturnRegistration: Represents a return registration
  - `account` integer, required: Account, that is linked to this registration.
  - `config` integer, nullable
  - `code` string, required: Configuration code of the return configuration
  - `version` string, nullable
  - `client_key` string, required: Name of the client, as configured in account setup.
  - `reference` string, required: Retailer reference, e.g. the order number, not unique
  - `external_id` string, uuid: Unique identifier for this return registration, generated by parcelLab
  - `external_reference` string: Additional identifier (e.g. shop system id) for this return registration, generated by the retailer
  - `display_name` string, required
  - `sequence_number` string, required
  - `status` 'created' | 'pending_payment' | 'submitted' | 'pending_approval' | 'pending_label' | 'approved' | 'rejected' | 'cancelled' | 'closed' | 'processing_failed' | 'invalid': * `created` - Created * `pending_payment` - Pending Payment * `submitted` - Submitted * `pending_approval` - Pending Approval * `pending_label` - Pending Label * `approved` - Approved * `rejected` - Rejected * `cancelled` - Cancelled * `closed` - Closed * `processing_failed` - Processing Failed * `invalid` - Invalid
  - `status_reason` string: Reason for the current status
  - `cancellable` boolean, required
  - `closable` boolean, required
  - `original_courier` string
  - `original_order_id` string, nullable
  - `order_date` string, date-time, nullable: Date of the order
  - `order_currency` string: Currency of the order, e.g. USD, EUR (ISO 4217)
  - `order_total_amount` string, decimal, nullable: Total amount of the original order
  - `order_shipping_amount` string, decimal, nullable: Total shipping amount of the original order
  - `order_tax_amount` string, decimal, nullable: Total tax amount of the original order
  - `order_delivery_date` string, date-time, nullable: Date of the order delivery
  - `order_shipping_date` string, date-time, nullable: Date of the order shipment
  - `order_payment_method` string[]: Payment method used for the order, as setup as reference items in the accounts configuration
  - `language_iso2` string: ISO 639-1 language code of the recipient, if known, required for localized communication
  - `is_gift_returns_portal` boolean, required
  - `customer_email` union, required: Customers email address, must be provided, in case email is not known or should be unset, use the literal string '_unset' instead.
    - string, email
    - '_unset'
  - `customer_phone` string: Customer phone number
  - `customer_salutation` string
  - `customer_first_name` string
  - `customer_last_name` string
  - `customer_country_iso3` string: ISO 3166-1 alpha-3 code of country
  - `customer_address` union, required
    - ValidatedAddressSchema
      - `first_name` string
      - `last_name` string
      - `company_name` string
      - `address_line` string, required: Address line, e.g. street and house number, or PO Box
      - `address_line_extra` string: Additional address line, e.g. apartment number or company name
      - `postal_code` string, required
      - `city` string, required: City name (min-length of 1 due to logographic languages)
      - `country_iso3` string, required: ISO 3166-1 alpha-3 code of country
      - `region_code` string: Region code, e.g. state or province code (ISO 3166-2), if available
      - `phone` string: Phone number related to this address, if any
    - Empty
  - `customer` string, required
  - `destinations` ReturnDestination[], nullable
    - `id` string, required
    - `address` AddressSchema, required
      - `first_name` string
      - `last_name` string
      - `company_name` string
      - `address_line` string, required: Address line, e.g. street and house number, or PO Box
      - `address_line_extra` string: Additional address line, e.g. apartment number or company name
      - `postal_code` string, required
      - `city` string, required: City name (min-length of 1 due to logographic languages)
      - `country_iso3` string, required: ISO 3166-1 alpha-3 code of country
      - `region_code` string: Region code, e.g. state or province code (ISO 3166-2), if available
      - `phone` string: Phone number related to this address, if any
  - `destination_id` string, nullable: Destination that articles without their own destination_id return to.
  - `articles_order` LineItemForReturn[]
    - `version` 'v1' | 'v2'
    - `line_item_id` string, required: Retailer ID of the line item, only the last number part of the whole line item id string
    - `product_id` string: Parent product identifier in the retailer's system (shared across variants).
    - `variant_id` string: SKU/variant identifier; prefer for matching when available since parent product IDs are reused across variants.
    - `sku` string: Stock Keeping Unit of the line item
    - `barcode` string: Barcode associated with the line item variant or product
    - `order_item_id` string, nullable: Line Item ID in the order (stripped), shared across fulfillments
    - `article_name` string: Name of the article
    - `article_description` string: Description of the article
    - `article_category` string: Category of the article
    - `article_store_url` string: URL to the article in the store
    - `article_image_url` string: URL to the image of the article
    - `article_brand` string: Brand of the article (reference only)
    - `size` string: Size of the article (reference only)
    - `color` string: Color of the article (reference only)
    - `width` number: Width of the article (in millimeters)
    - `height` number: Height of the article (in millimeters)
    - `length` number: Length of the article (in millimeters)
    - `length_unit` 'cm'
    - `weight` number: Weight of the article (in grams, kg, lbs, or oz)
    - `weight_unit` 'kg' | 'g' | 'lbs' | 'oz'
    - `unit_price` string: Paid unit price of the article (post-discount)
    - `unit_price_original` string: Original unit price of the article (pre-discount)
    - `quantity` integer: Unit quantity of the article
    - `amount_invoiced` string: Paid line total amount for this line item (post-discount)
    - `tax_amount` string: Total tax amount for this line item (regardless of taxesIncluded)
    - `harmonized_system_code` string: HS/HTS code for customs classification
    - `origin_country_iso3` string: ISO 3166-1 alpha-3 code of articles country of origin, might be required based on shipment regulations
    - `is_bulky` boolean: If the article is bulky
    - `tags` string[]: Tags for the line item, e.g. 'category:home-apparel', or 'customergroup:vip'
    - `bundle` BundleInfo
      - `group_id` string, required: Bundle group identifier in the retailer's system.
      - `role` 'parent' | 'component', required
      - `return_policy` 'parent_only' | 'components_only' | 'parent_and_components'
      - `parent_product_id` string: Parent bundle product identifier in the retailer's system.
      - `parent_variant_id` string: Parent bundle variant identifier in the retailer's system.
      - `parent_sku` string: Parent bundle SKU, if available.
      - `parent_title` string: Display title for the bundle parent, if available.
      - `parent_quantity` integer: Quantity of the bundle parent purchased in the order.
      - `component_quantity_per_parent` integer: Component quantity per single bundle parent (if determinable).
      - `selection_mode` 'individual' | 'group_on_first_pick'
      - `allocation_method` 'none' | 'component_price' | 'msrp_ratio' | 'equal'
      - `allocated_unit_price` string: Snapshot of allocated component unit price (if derived from bundle totals).
      - `allocated_amount_invoiced` string: Snapshot of allocated component invoiced amount (if derived from bundle totals).
    - `additional_attributes` AdditionalAttribute[]: Additional attributes for this line item
      - `key` string, required: The key of the additional attribute
      - `value` unknown
    - `destination_id` string: Reference to a destination on the return registration; overrides the registration's destination_id
    - `unit_price_msrp_current` string, nullable: Current catalog/MSRP unit price for the same variant.
    - `current_product_tags` string[], nullable: The product's live tags at return time (rules use `tags`, the order-creation tags). Captured for audit/filtering; unset when not captured.
    - `reference_date_for_return` string, date: The date, which is used to evaluate the line item return period
    - `reference_date_type` 'order_date' | 'shipping_date' | 'delivery_date'
    - `fulfillment` string, nullable: Id of the fulfillment that this item belongs to
    - `quantity_returned` integer: Quantity of already returned items in this line.
    - `delivered_date` string, date: Date when the line item was delivered (same as the fulfillment delivered date)
  - `articles_return` LineItemReturn[]
    - `version` 'v1' | 'v2'
    - `line_item_id` string, required: Retailer ID of the line item, only the last number part of the whole line item id string
    - `product_id` string: Parent product identifier in the retailer's system (shared across variants).
    - `variant_id` string: SKU/variant identifier; prefer for matching when available since parent product IDs are reused across variants.
    - `sku` string: Stock Keeping Unit of the line item
    - `barcode` string: Barcode associated with the line item variant or product
    - `order_item_id` string, nullable: Line Item ID in the order (stripped), shared across fulfillments
    - `article_name` string: Name of the article
    - `article_description` string: Description of the article
    - `article_category` string: Category of the article
    - `article_store_url` string: URL to the article in the store
    - `article_image_url` string: URL to the image of the article
    - `article_brand` string: Brand of the article (reference only)
    - `size` string: Size of the article (reference only)
    - `color` string: Color of the article (reference only)
    - `width` number: Width of the article (in millimeters)
    - `height` number: Height of the article (in millimeters)
    - `length` number: Length of the article (in millimeters)
    - `length_unit` 'cm'
    - `weight` number: Weight of the article (in grams, kg, lbs, or oz)
    - `weight_unit` 'kg' | 'g' | 'lbs' | 'oz'
    - `unit_price` string: Paid unit price of the article (post-discount)
    - `unit_price_original` string: Original unit price of the article (pre-discount)
    - `quantity` integer: Unit quantity of the article
    - `amount_invoiced` string: Paid line total amount for this line item (post-discount)
    - `tax_amount` string: Total tax amount for this line item (regardless of taxesIncluded)
    - `harmonized_system_code` string: HS/HTS code for customs classification
    - `origin_country_iso3` string: ISO 3166-1 alpha-3 code of articles country of origin, might be required based on shipment regulations
    - `is_bulky` boolean: If the article is bulky
    - `tags` string[]: Tags for the line item, e.g. 'category:home-apparel', or 'customergroup:vip'
    - `bundle` BundleInfo
      - `group_id` string, required: Bundle group identifier in the retailer's system.
      - `role` 'parent' | 'component', required
      - `return_policy` 'parent_only' | 'components_only' | 'parent_and_components'
      - `parent_product_id` string: Parent bundle product identifier in the retailer's system.
      - `parent_variant_id` string: Parent bundle variant identifier in the retailer's system.
      - `parent_sku` string: Parent bundle SKU, if available.
      - `parent_title` string: Display title for the bundle parent, if available.
      - `parent_quantity` integer: Quantity of the bundle parent purchased in the order.
      - `component_quantity_per_parent` integer: Component quantity per single bundle parent (if determinable).
      - `selection_mode` 'individual' | 'group_on_first_pick'
      - `allocation_method` 'none' | 'component_price' | 'msrp_ratio' | 'equal'
      - `allocated_unit_price` string: Snapshot of allocated component unit price (if derived from bundle totals).
      - `allocated_amount_invoiced` string: Snapshot of allocated component invoiced amount (if derived from bundle totals).
    - `additional_attributes` AdditionalAttribute[]: Additional attributes for this line item
      - `key` string, required: The key of the additional attribute
      - `value` unknown
    - `destination_id` string: Reference to a destination on the return registration; overrides the registration's destination_id
    - `unit_price_msrp_current` string, nullable: Current catalog/MSRP unit price for the same variant.
    - `current_product_tags` string[], nullable: The product's live tags at return time (rules use `tags`, the order-creation tags). Captured for audit/filtering; unset when not captured.
    - `reference_date_for_return` string, date: The date, which is used to evaluate the line item return period
    - `reference_date_type` 'order_date' | 'shipping_date' | 'delivery_date'
    - `fulfillment` string, nullable: Id of the fulfillment that this item belongs to
    - `quantity_returned` integer: Quantity of already returned items in this line.
    - `delivered_date` string, date: Date when the line item was delivered (same as the fulfillment delivered date)
    - `return_reason` string: Full return reason path (as configured in the respective return configuration for this object)
    - `return_reason_pretty` string: Pretty text for the return reason, e.g. 'Doesn't Fit'
    - `return_quantity` integer: Quantity to be returned
    - `problem_description` string: Description of the problem with this line item
    - `condition` string: Article condition, if provided
    - `article_images` ReturnImage[]
      - `url` string, required
      - `name` string, required
      - `mime_type` string, required
    - `compensation_method` string: Compensation method for this line item, e.g. exchange, refund, credit
    - `accepted_quantity` integer: Quantity of the article that was accepted by warehouse
    - `rejected_quantity` integer: Quantity of the article that was rejected by warehouse
    - `restock` boolean: Whether accepted returned items should be restocked.
    - `status_reason` string: Reason for the rejection / acceptance of the article
    - `status_reason_code` string: Structured reason code, e.g. quality_issue
    - `return_reason_code` string, nullable, required: Final code of return reason (leaf code)
  - `item_count` integer, required
  - `return_labels` ReturnLabel[], required
    - `source` 'generated' | 'customer_provided'
    - `courier` string, required: Return label courier code or drop-off code, e.g. barcode
    - `service_level` string: Service level of the return label
    - `tracking_number` string, nullable: Tracking number of the return label (or in case of Barcode the barcode)
    - `type` 'shipping' | 'custom'
    - `flags` ReturnLabelFlagsEnum[]: Flags (extra markers) for the return label, such as 'has_dangerous_goods', or 'is_pickup'
    - `documents` Document[]: Documents related to this return label (e.g. print label, barcode, packing slip, wallet-passes)
      - `url` string, required: URL to the document, in most cases this is a http URL, but it could also be a data URL (base64)
      - `content_type` string: MIME content type of the document, e.g. 'application/pdf'
      - `type` DocumentTypeEnum[]: Type or types of the document, maybe multiple, if bundled
      - `expires_at` string, date-time: Expiry date of the document, after which it might not be retrievable
    - `locations_url` string: URL to a courier-specific location finder page.
    - `locations` ReturnLabelLocation[]: Nearby drop-off locations captured for this return label.
      - `name` string, nullable
      - `address` string, required
      - `distance_km` number, required
      - `distance_miles` number, required
      - `latitude` number, nullable
      - `longitude` number, nullable
      - `opening_hours` ReturnLabelLocationOpeningHours[]
        - `day` integer[], required
        - `open` string, required
        - `close` string, required
      - `has_opening_hours` boolean
    - `destination_id` string: Destination ID for the return label, e.g. warehouse code
    - `line_item_ids` string[]: The line item IDs to which the label should be attached
    - `is_free_label` boolean: Indicates if the return label is free of charge
    - `label_cost_amount` string: Cost of the return label
    - `tracking_id` string: Tracking ID of the shipment in the parcelLab system
    - `external_reference` string: Unique retailer-provided reference of the shipment, either this tracking number is required
    - `delivery_status` 'Pending' | 'Transit' | 'Customs' | 'LastMile' | 'ReadyToCollect' | 'Delivered' | 'SentBack' | 'Returned' | 'Failed' | 'Cancelled'
    - `pickup_date` string, date: Scheduled pickup date for the return label. Nullable if not a pickup return.
    - `earliest_pickup_time` string, time: Earliest scheduled pickup time for the return label. Nullable if not a pickup return.
    - `latest_pickup_time` string, time: Latest scheduled pickup time for the return label. Nullable if not a pickup return.
    - `pickup_confirmation_code` string: Confirmation code customer must present on pickup
    - `safe_place` string: Safe place instruction provided by the customer for pickup
    - `is_pickup` boolean: Indicates if the return is a pickup order.
    - `configuration_id` integer, nullable: Selected return option mapping ID used to create this label.
    - `group_code` string: The group code the courier belongs, when from a courier broker interface
    - `courier_code_overwrite` string: The group code the courier belongs, when from a courier broker interface
  - `refund_method` string: Refund method selected by customer
  - `tags` string[]: Order level tags.
  - `additional_fields` object: Free-form JSON object for custom return-registration metadata. Send a JSON object keyed by your field names; values may be scalars, arrays, or nested objects. This is not the order API `additional_attributes` list of `{key, value}` pairs.
  - `verification_code_used` string: Verification code (e.g. zip/email) used for this return registration
  - `created_at` string, date-time, required
  - `submitted_at` string, date-time, nullable, required: Date(-time) when the customer submitted the return registration.
  - `updated_at` string, date-time, required
  - `mutations` union[]
    - union
      - AddLabelMutation
        - `operation_id` string, uuid: The unique ID of the operation, generated by parcelLab, if not provided
        - `result` MutationResult: The result of a mutation
          - `success` boolean: Whether the mutation was successful
          - `message` string: A message describing the result of the mutation
          - `errors` object: A dictionary of errors that occurred during the mutation
          - `warnings` string[]: Non-fatal warnings raised while processing the mutation
        - `type` 'add_label'
        - `request` AddLabelRequest, required: Adds a label to a return registration
          - `type` 'shipping' | 'custom', required
          - `courier` string, required: The courier for which a label should be created
          - `tracking_number` string: Only for custom label: custom tracking number for the label
          - `service_level` string: The service level for the label
          - `destination_id` string: The warehouse or other identifier, to which the courier should ship, corresponds to a warehouse code
          - `destination_address` AddressSchema
            - `first_name` string
            - `last_name` string
            - `company_name` string
            - `address_line` string, required: Address line, e.g. street and house number, or PO Box
            - `address_line_extra` string: Additional address line, e.g. apartment number or company name
            - `postal_code` string, required
            - `city` string, required: City name (min-length of 1 due to logographic languages)
            - `country_iso3` string, required: ISO 3166-1 alpha-3 code of country
            - `region_code` string: Region code, e.g. state or province code (ISO 3166-2), if available
            - `phone` string: Phone number related to this address, if any
          - `template_id` string: The identifier of the template to use for the label (if multiple templates are configured), e.g. the language code 'en' or 'de_at'. This is setup specific, if no match is found and a default template is configured, the default template will be used.
          - `flags` AddLabelFlagsEnum[]: A list of special flags that apply to the label or shipment
          - `label_types` LabelTypesEnum[]: Optional: Restriction on types of the label to create, e.g. 'code' for a QR code label or 'print' for a PDF/image label (needs to be supported for integration, please reach out to our support team).
          - `line_item_ids` string[]: The line item IDs to which the label should be attached
          - `additional_fields` object: Custom fields to pass through to label generation and returns document.
          - `weight_in_grams` integer: Overrides the parcel weight sent to the courier, instead of the weight calculated from the returned articles
      - AddCustomerProvidedLabelMutation
        - `operation_id` string, uuid: The unique ID of the operation, generated by parcelLab, if not provided
        - `result` MutationResult: The result of a mutation
          - `success` boolean: Whether the mutation was successful
          - `message` string: A message describing the result of the mutation
          - `errors` object: A dictionary of errors that occurred during the mutation
          - `warnings` string[]: Non-fatal warnings raised while processing the mutation
        - `type` 'add_customer_provided_label'
        - `request` AddCustomerProvidedLabelRequest, required: Attaches tracking for return postage the customer bought elsewhere
          - `courier` string, required: Courier code of the customer's shipment, must be allowed by the portal
          - `tracking_number` string, required: Tracking number of the customer's shipment
          - `line_item_ids` string[]: Line item IDs in the shipment, defaults to all returned items
      - CreatePickupMutation
        - `operation_id` string, uuid: The unique ID of the operation, generated by parcelLab, if not provided
        - `result` MutationResult: The result of a mutation
          - `success` boolean: Whether the mutation was successful
          - `message` string: A message describing the result of the mutation
          - `errors` object: A dictionary of errors that occurred during the mutation
          - `warnings` string[]: Non-fatal warnings raised while processing the mutation
        - `type` 'create_pickup'
        - `request` CreatePickupRequest, required
          - `configuration_id` integer, required: The returns portal courier mapping ID for the pickup selection
          - `courier` string, required: The courier for which a label should be created
          - `pickup_date` string, date, nullable: The date on which the pickup should be scheduled
          - `earliest_pickup_time` string, nullable: The earliest pickup time value as returned by the 3rd-party provider availability response (raw provider string).
          - `latest_pickup_time` string, nullable: The latest pickup time value as returned by the 3rd-party provider availability response (raw provider string).
          - `safe_place` string: The safe place where the package should be picked up
          - `courier_identifier` string: Identifier for the given courier
      - CancelPickupMutation
        - `operation_id` string, uuid: The unique ID of the operation, generated by parcelLab, if not provided
        - `result` MutationResult: The result of a mutation
          - `success` boolean: Whether the mutation was successful
          - `message` string: A message describing the result of the mutation
          - `errors` object: A dictionary of errors that occurred during the mutation
          - `warnings` string[]: Non-fatal warnings raised while processing the mutation
        - `type` 'cancel_pickup'
      - UpdateItemMutation: Update registered article items
        - `operation_id` string, uuid: The unique ID of the operation, generated by parcelLab, if not provided
        - `result` MutationResult: The result of a mutation
          - `success` boolean: Whether the mutation was successful
          - `message` string: A message describing the result of the mutation
          - `errors` object: A dictionary of errors that occurred during the mutation
          - `warnings` string[]: Non-fatal warnings raised while processing the mutation
        - `type` 'update_items'
        - `items` LineItemReturn[]: Items for this return registration after update is a applied
          - `version` 'v1' | 'v2'
          - `line_item_id` string, required: Retailer ID of the line item, only the last number part of the whole line item id string
          - `product_id` string: Parent product identifier in the retailer's system (shared across variants).
          - `variant_id` string: SKU/variant identifier; prefer for matching when available since parent product IDs are reused across variants.
          - `sku` string: Stock Keeping Unit of the line item
          - `barcode` string: Barcode associated with the line item variant or product
          - `order_item_id` string, nullable: Line Item ID in the order (stripped), shared across fulfillments
          - `article_name` string: Name of the article
          - `article_description` string: Description of the article
          - `article_category` string: Category of the article
          - `article_store_url` string: URL to the article in the store
          - `article_image_url` string: URL to the image of the article
          - `article_brand` string: Brand of the article (reference only)
          - `size` string: Size of the article (reference only)
          - `color` string: Color of the article (reference only)
          - `width` number: Width of the article (in millimeters)
          - `height` number: Height of the article (in millimeters)
          - `length` number: Length of the article (in millimeters)
          - `length_unit` 'cm'
          - `weight` number: Weight of the article (in grams, kg, lbs, or oz)
          - `weight_unit` 'kg' | 'g' | 'lbs' | 'oz'
          - `unit_price` string: Paid unit price of the article (post-discount)
          - `unit_price_original` string: Original unit price of the article (pre-discount)
          - `quantity` integer: Unit quantity of the article
          - `amount_invoiced` string: Paid line total amount for this line item (post-discount)
          - `tax_amount` string: Total tax amount for this line item (regardless of taxesIncluded)
          - `harmonized_system_code` string: HS/HTS code for customs classification
          - `origin_country_iso3` string: ISO 3166-1 alpha-3 code of articles country of origin, might be required based on shipment regulations
          - `is_bulky` boolean: If the article is bulky
          - `tags` string[]: Tags for the line item, e.g. 'category:home-apparel', or 'customergroup:vip'
          - `bundle` BundleInfo
            - `group_id` string, required: Bundle group identifier in the retailer's system.
            - `role` 'parent' | 'component', required
            - `return_policy` 'parent_only' | 'components_only' | 'parent_and_components'
            - `parent_product_id` string: Parent bundle product identifier in the retailer's system.
            - `parent_variant_id` string: Parent bundle variant identifier in the retailer's system.
            - `parent_sku` string: Parent bundle SKU, if available.
            - `parent_title` string: Display title for the bundle parent, if available.
            - `parent_quantity` integer: Quantity of the bundle parent purchased in the order.
            - `component_quantity_per_parent` integer: Component quantity per single bundle parent (if determinable).
            - `selection_mode` 'individual' | 'group_on_first_pick'
            - `allocation_method` 'none' | 'component_price' | 'msrp_ratio' | 'equal'
            - `allocated_unit_price` string: Snapshot of allocated component unit price (if derived from bundle totals).
            - `allocated_amount_invoiced` string: Snapshot of allocated component invoiced amount (if derived from bundle totals).
          - `additional_attributes` AdditionalAttribute[]: Additional attributes for this line item
            - `key` string, required: The key of the additional attribute
            - `value` unknown
          - `destination_id` string: Reference to a destination on the return registration; overrides the registration's destination_id
          - `unit_price_msrp_current` string, nullable: Current catalog/MSRP unit price for the same variant.
          - `current_product_tags` string[], nullable: The product's live tags at return time (rules use `tags`, the order-creation tags). Captured for audit/filtering; unset when not captured.
          - `reference_date_for_return` string, date: The date, which is used to evaluate the line item return period
          - `reference_date_type` 'order_date' | 'shipping_date' | 'delivery_date'
          - `fulfillment` string, nullable: Id of the fulfillment that this item belongs to
          - `quantity_returned` integer: Quantity of already returned items in this line.
          - `delivered_date` string, date: Date when the line item was delivered (same as the fulfillment delivered date)
          - `return_reason` string: Full return reason path (as configured in the respective return configuration for this object)
          - `return_reason_pretty` string: Pretty text for the return reason, e.g. 'Doesn't Fit'
          - `return_quantity` integer: Quantity to be returned
          - `problem_description` string: Description of the problem with this line item
          - `condition` string: Article condition, if provided
          - `article_images` ReturnImage[]
            - `url` string, required
            - `name` string, required
            - `mime_type` string, required
          - `compensation_method` string: Compensation method for this line item, e.g. exchange, refund, credit
          - `accepted_quantity` integer: Quantity of the article that was accepted by warehouse
          - `rejected_quantity` integer: Quantity of the article that was rejected by warehouse
          - `restock` boolean: Whether accepted returned items should be restocked.
          - `status_reason` string: Reason for the rejection / acceptance of the article
          - `status_reason_code` string: Structured reason code, e.g. quality_issue
          - `return_reason_code` string, nullable, required: Final code of return reason (leaf code)
      - CloseReturnMutation: Close a return registration (finalize return + refund).
        - `operation_id` string, uuid: The unique ID of the operation, generated by parcelLab, if not provided
        - `result` MutationResult: The result of a mutation
          - `success` boolean: Whether the mutation was successful
          - `message` string: A message describing the result of the mutation
          - `errors` object: A dictionary of errors that occurred during the mutation
          - `warnings` string[]: Non-fatal warnings raised while processing the mutation
        - `type` 'close_return'
        - `status_reason` string: Optional reason for closing the return registration.
        - `trigger_refund` boolean: Whether to issue a monetary refund when closing the return.
        - `release_exchange_items` boolean: Whether to release exchange items when closing the return.
        - `refund_shipping_fees` boolean: Whether to refund the original order shipping cost.
        - `tracking_number` string: Optional tracking number used for receive-status synchronization when article status updates are provided.
        - `received_by` string: Optional source shown in receive status when article status updates are provided. Defaults to API (close_return mutation).
        - `receive_note` string: Optional receive note stored with receive status and synchronized to tracking returnReceive.note when article status updates are provided.
        - `article_status_updates` ArticleStatusUpdate[]: Optional receive-style article status updates to apply before closing the return registration.
          - `fulfillment` string, nullable
          - `identifier` string, required: Identifier of the article to update the status for
          - `identifier_type` 'product_id' | 'line_item_id' | 'sku' | 'variant_id' | 'barcode' | 'order_item_id', required
          - `accepted_quantity` integer: The quantity of the article that was accepted
          - `rejected_quantity` integer: The quantity of the article that was rejected
          - `reason` string: The reason for the rejection of the article
          - `restock` boolean: Whether accepted returned items should be restocked
          - `status_reason_code` 'missing_quantity' | 'quality_issue' | 'other'
          - `condition` string: Condition of the received article
          - `article_images` ReturnImage[]: Images documenting the received article
            - `url` string, required
            - `name` string, required
            - `mime_type` string, required
      - CancelReturnMutation: Cancel a return registration and its tracking.
        - `operation_id` string, uuid: The unique ID of the operation, generated by parcelLab, if not provided
        - `result` MutationResult: The result of a mutation
          - `success` boolean: Whether the mutation was successful
          - `message` string: A message describing the result of the mutation
          - `errors` object: A dictionary of errors that occurred during the mutation
          - `warnings` string[]: Non-fatal warnings raised while processing the mutation
        - `type` 'cancel_return'
        - `status_reason` string: Optional reason for cancelling the return registration.

## Other responses

- `400`
- `403`
- `404`

## Changes

- **2026-11-03** `84524f38b6c9`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/parcellab/apis/parcellab-api/changes/v4/returns/return-registrations/mutate/post.md)

---

[API](https://skmtc.dev/parcellab/apis/parcellab-api.md) - [All operations](https://skmtc.dev/parcellab/apis/parcellab-api/llms.txt) - [OpenAPI document](https://skmtc.dev/parcellab/apis/parcellab-api/revisions/84524f38b6c9?raw)