---
title: "Register Return"
method: POST
path: "/v4/returns/return-registrations/"
tags: ["Return Registration"]
---

# Register Return

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

## Request

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

Create a new return registration

## Query parameters

- `courier_testing` boolean
- `draft` boolean
- `pre_register_backend_tracking` boolean
- `return_init_v2` boolean

## Request body

- ReturnRegistrationRequest: 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
  - `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
  - `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
  - `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
  - `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
  - `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)
  - `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
  - `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.

## Response `201`

- 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/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)