# Return Registrations ## Overview These requests allow you to generate and modify return registrations with a single HTTPS request. You can retrieve return registrations associated with your account and a specific return request using its unique ID through these APIs. Additionally, you can retrieve article information for return items as well as generate return labels. ## Get Return Registrations You can retrieve a list of return registrations for your account using the `v4/returns/return-registrations` endpoint. ## List Return Registration > 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. ```json {"openapi":"3.1.0","info":{"title":"parcelLab API","version":"v4"},"security":[{"OAuth2 Authentication":[]},{"HeaderToken":[]}],"components":{"securitySchemes":{"OAuth2 Authentication":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"HeaderToken":{"type":"http","scheme":"bearer","bearerFormat":"Parcellab-API-Token base64(account_id:token)","description":"Send `Authorization: Parcellab-API-Token `.\n\n`` = `base64(account_id:token)` as provided in the portal."}},"schemas":{"PaginatedReturnRegistrationList":{"type":"object","required":["results"],"properties":{"next":{"type":"string","nullable":true,"format":"uri"},"previous":{"type":"string","nullable":true,"format":"uri"},"results":{"type":"array","items":{"$ref":"#/components/schemas/ReturnRegistration"}}}},"ReturnRegistration":{"type":"object","description":"Represents a return registration","properties":{"account":{"type":"integer","description":"Account, that is linked to this registration."},"code":{"type":"string","title":"Configuration Code","description":"Configuration code of the return configuration","maxLength":255},"version":{"type":["string","null"]},"client_key":{"type":"string","readOnly":true,"description":"Name of the client, as configured in account setup."},"reference":{"type":"string","title":"Reference / Order Number","description":"Retailer reference, e.g. the order number, not unique","maxLength":255},"external_id":{"type":"string","format":"uuid","title":"External Identifier","description":"Unique identifier for this return registration, generated by parcelLab"},"external_reference":{"type":"string","description":"Additional identifier (e.g. shop system id) for this return registration, generated by the retailer","maxLength":255},"sequence_number":{"type":"string","readOnly":true},"status":{"$ref":"#/components/schemas/ReturnRegistrationStatusEnum"},"status_reason":{"type":"string","description":"Reason for the current status","maxLength":255},"original_courier":{"type":"string","maxLength":255},"original_order_id":{"type":["string","null"],"maxLength":255},"order_date":{"type":["string","null"],"format":"date-time","description":"Date of the order"},"order_currency":{"type":"string","description":"Currency of the order, e.g. USD, EUR (ISO 4217)","maxLength":3},"order_total_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Total amount of the original order"},"order_shipping_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Total shipping amount of the original order"},"order_tax_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Total tax amount of the original order"},"order_delivery_date":{"type":["string","null"],"format":"date-time","description":"Date of the order delivery"},"order_shipping_date":{"type":["string","null"],"format":"date-time","description":"Date of the order shipment"},"order_payment_method":{"type":"array","items":{"type":"string","maxLength":255},"description":"Payment method used for the order, as setup as reference items in the accounts configuration"},"language_iso2":{"type":"string","description":"ISO 639-1 language code of the recipient, if known, required for localized communication","maxLength":3},"is_gift_returns_portal":{"type":"boolean","readOnly":true},"customer_email":{"anyOf":[{"format":"email","type":"string"},{"const":"_unset","enum":["_unset"],"type":"string"}],"description":"Customers email address, must be provided, in case email is not known or should be unset, use the literal string '_unset' instead."},"customer_phone":{"type":"string","description":"Customer phone number","maxLength":255},"customer_salutation":{"type":"string","maxLength":255},"customer_first_name":{"type":"string","maxLength":255},"customer_last_name":{"type":"string","maxLength":255},"customer_country_iso3":{"type":"string","description":"ISO 3166-1 alpha-3 code of country","maxLength":3},"customer_address":{"anyOf":[{"$ref":"#/components/schemas/ValidatedAddressSchema"},{"$ref":"#/components/schemas/Empty"}]},"articles_order":{"items":{"$ref":"#/components/schemas/LineItem"},"type":"array"},"articles_return":{"items":{"$ref":"#/components/schemas/LineItemReturn"},"type":"array"},"return_labels":{"items":{"$ref":"#/components/schemas/ReturnLabel"},"type":"array","readOnly":true},"refund_method":{"type":"string","description":"Refund method selected by customer","maxLength":255},"tags":{"type":"array","items":{"type":"string","maxLength":255},"description":"Order level tags."},"additional_fields":{"type":"object","additionalProperties":{},"description":"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":{"type":"string","description":"Verification code (e.g. zip/email) used for this return registration","maxLength":255},"created_at":{"type":"string","format":"date-time","readOnly":true},"updated_at":{"type":"string","format":"date-time","readOnly":true},"mutations":{"items":{"anyOf":[{"$ref":"#/components/schemas/AddLabelMutation"},{"$ref":"#/components/schemas/UpdateItemMutation"},{"$ref":"#/components/schemas/CloseReturnMutation"},{"$ref":"#/components/schemas/CancelReturnMutation"}],"title":"Mutations"},"type":"array"}},"required":["account","client_key","code","created_at","customer_address","customer_email","is_gift_returns_portal","reference","return_labels","sequence_number","updated_at"]},"ReturnRegistrationStatusEnum":{"enum":["created","submitted","pending_approval","pending_label","approved","rejected","cancelled","closed","processing_failed","invalid"],"type":"string","description":"* `created` - Created\n* `submitted` - Submitted\n* `pending_approval` - Pending Approval\n* `pending_label` - Pending Label\n* `approved` - Approved\n* `rejected` - Rejected\n* `cancelled` - Cancelled\n* `closed` - Closed\n* `processing_failed` - Processing Failed\n* `invalid` - Invalid"},"ValidatedAddressSchema":{"properties":{"first_name":{"title":"First Name","type":"string"},"last_name":{"title":"Last Name","type":"string"},"company_name":{"title":"Company Name, if any","type":"string"},"address_line":{"description":"Address line, e.g. street and house number, or PO Box","maxLength":256,"minLength":1,"title":"Address Line","type":"string"},"address_line_extra":{"description":"Additional address line, e.g. apartment number or company name","title":"Additional Address Line","type":"string"},"postal_code":{"maxLength":10,"minLength":2,"title":"Postal Code","type":"string"},"city":{"description":"City name (min-length of 1 due to logographic languages)","maxLength":40,"minLength":1,"title":"City","type":"string"},"country_iso3":{"description":"ISO 3166-1 alpha-3 code of country","pattern":"^\\w{3}$","title":"Country ISO3","type":"string"},"region_code":{"description":"Region code, e.g. state or province code (ISO 3166-2), if available","maxLength":25,"minLength":1,"title":"Region Code","type":"string"},"phone":{"description":"Phone number related to this address, if any","maxLength":30,"title":"Phone","type":"string"}},"required":["address_line","postal_code","city","country_iso3"],"title":"Address","type":"object"},"Empty":{"additionalProperties":false,"properties":{},"title":"Empty","type":"object"},"LineItem":{"additionalProperties":true,"properties":{"version":{"$ref":"#/components/schemas/LineItemVersionEnum","description":"Optional. Omit this key unless absolutely intended. The standard value is `v2`. If you send `version`, send `v2`.","title":"Version"},"line_item_id":{"description":"Retailer ID of the line item","title":"Line Item ID","type":"string"},"product_id":{"description":"Parent product identifier in the retailer's system (shared across variants).","title":"Product ID","type":"string"},"variant_id":{"description":"SKU/variant identifier; prefer for matching when available since parent product IDs are reused across variants.","title":"Variant ID","type":"string"},"sku":{"description":"Stock Keeping Unit of the line item","title":"SKU","type":"string"},"barcode":{"description":"Barcode associated with the line item variant or product","title":"Barcode","type":"string"},"order_item_id":{"description":"Line Item ID in the order (preferred when provided)","title":"Order Line Item ID","type":"string"},"article_name":{"description":"Name of the article","title":"Article Name","type":"string"},"article_category":{"description":"Category of the article","title":"Article Category","type":"string"},"article_store_url":{"description":"URL to the article in the store","title":"Article Store URL","type":"string"},"article_image_url":{"description":"URL to the image of the article","title":"Article Image URL","type":"string"},"article_brand":{"description":"Brand of the article (reference only)","title":"Article Brand","type":"string"},"size":{"description":"Size of the article (reference only)","title":"Size","type":"string"},"color":{"description":"Color of the article (reference only)","title":"Color","type":"string"},"width":{"description":"Width of the article (in millimeters)","title":"Width","type":"number"},"height":{"description":"Height of the article (in millimeters)","title":"Height","type":"number"},"length":{"description":"Length of the article (in millimeters)","title":"Length","type":"number"},"length_unit":{"const":"cm","default":"cm","title":"Length Unit","type":"string"},"weight":{"description":"Weight of the article (in grams, kg, lbs, or oz)","title":"Weight","type":"number"},"weight_unit":{"allOf":[{"$ref":"#/components/schemas/WeightUnitEnum"}],"default":"g","title":"Weight Unit"},"unit_price":{"description":"Paid unit price of the article (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Unit Price","type":"string"},"unit_price_original":{"description":"Original unit price of the article (pre-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Unit Price","type":"string"},"quantity":{"description":"Unit quantity of the article","title":"Unit Quantity","type":"integer"},"amount_invoiced":{"description":"Paid line total amount for this line item (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Invoiced","type":"string"},"tax_amount":{"description":"Total tax amount for this line item (regardless of taxesIncluded)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Tax Amount","type":"string"},"harmonized_system_code":{"description":"HS/HTS code for customs classification","title":"Harmonized System Code","type":"string"},"origin_country_iso3":{"description":"ISO 3166-1 alpha-3 code of articles country of origin, might be required based on shipment regulations","pattern":"^\\w{3}$","title":"Origin Country ISO3","type":"string"},"is_bulky":{"default":false,"description":"If the article is bulky","title":"Is Bulky","type":"boolean"},"tags":{"description":"Tags for the line item, e.g. 'category:home-apparel', or 'customergroup:vip'","items":{"type":"string"},"title":"Tags","type":"array"},"bundle":{"anyOf":[{"$ref":"#/components/schemas/BundleInfo"},{"type":"null"}],"default":null,"description":"Bundle relationship metadata when the item is part of a bundle.","title":"Bundle Info"},"additional_attributes":{"description":"Additional attributes for this line item","items":{"$ref":"#/components/schemas/AdditionalAttribute"},"title":"Additional Attributes","type":"array"}},"required":["line_item_id"],"title":"Line Item","type":"object"},"LineItemVersionEnum":{"enum":["v1","v2"],"title":"LineItemVersionEnum","type":"string"},"WeightUnitEnum":{"enum":["kg","g","lbs","oz"],"type":"string"},"BundleInfo":{"additionalProperties":true,"properties":{"group_id":{"description":"Bundle group identifier in the retailer's system.","title":"Bundle Group ID","type":"string"},"role":{"$ref":"#/components/schemas/BundleRoleEnum","description":"Whether this line item represents a bundle parent or a bundle component.","title":"Bundle Role"},"return_policy":{"$ref":"#/components/schemas/BundleReturnPolicyEnum","default":"components_only","description":"Which lines in this bundle group are selectable for return.","title":"Bundle Return Policy"},"parent_product_id":{"description":"Parent bundle product identifier in the retailer's system.","title":"Bundle Parent Product ID","type":"string"},"parent_variant_id":{"description":"Parent bundle variant identifier in the retailer's system.","title":"Bundle Parent Variant ID","type":"string"},"parent_sku":{"description":"Parent bundle SKU, if available.","title":"Bundle Parent SKU","type":"string"},"parent_title":{"description":"Display title for the bundle parent, if available.","title":"Bundle Parent Title","type":"string"},"parent_quantity":{"description":"Quantity of the bundle parent purchased in the order.","title":"Bundle Parent Quantity","type":"integer"},"component_quantity_per_parent":{"description":"Component quantity per single bundle parent (if determinable).","title":"Bundle Component Quantity Per Parent","type":"integer"},"allocation_method":{"$ref":"#/components/schemas/BundleAllocationMethodEnum","default":"none","description":"How pricing was allocated to bundle components.","title":"Bundle Allocation Method"},"allocated_unit_price":{"description":"Snapshot of allocated component unit price (if derived from bundle totals).","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Allocated Unit Price","type":"string"},"allocated_amount_invoiced":{"description":"Snapshot of allocated component invoiced amount (if derived from bundle totals).","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Allocated Amount Invoiced","type":"string"}},"required":["group_id","role"],"title":"Bundle Info","type":"object"},"BundleRoleEnum":{"enum":["parent","component"],"title":"BundleRoleEnum","type":"string"},"BundleReturnPolicyEnum":{"enum":["parent_only","components_only","parent_and_components"],"title":"BundleReturnPolicyEnum","type":"string"},"BundleAllocationMethodEnum":{"enum":["none","component_price","msrp_ratio","equal"],"title":"BundleAllocationMethodEnum","type":"string"},"AdditionalAttribute":{"properties":{"key":{"description":"The key of the additional attribute","title":"Key","type":"string"},"value":{"default":null,"description":"The value of the additional attribute","title":"Value"}},"required":["key"],"title":"AdditionalAttribute","type":"object"},"LineItemReturn":{"additionalProperties":true,"properties":{"version":{"$ref":"#/components/schemas/LineItemVersionEnum","description":"Optional. Omit this key unless absolutely intended. The standard value is `v2`. If you send `version`, send `v2`.","title":"Version"},"line_item_id":{"description":"Retailer ID of the line item, only the last number part of the whole line item id string","title":"Line Item ID","type":"string"},"product_id":{"description":"Parent product identifier in the retailer's system (shared across variants).","title":"Product ID","type":"string"},"variant_id":{"description":"SKU/variant identifier; prefer for matching when available since parent product IDs are reused across variants.","title":"Variant ID","type":"string"},"sku":{"description":"Stock Keeping Unit of the line item","title":"SKU","type":"string"},"barcode":{"description":"Barcode associated with the line item variant or product","title":"Barcode","type":"string"},"order_item_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Line Item ID in the order, the whole id of the fulfillment line item","title":"Order Line Item ID"},"article_name":{"description":"Name of the article","title":"Article Name","type":"string"},"article_category":{"description":"Category of the article","title":"Article Category","type":"string"},"article_store_url":{"description":"URL to the article in the store","title":"Article Store URL","type":"string"},"article_image_url":{"description":"URL to the image of the article","title":"Article Image URL","type":"string"},"article_brand":{"description":"Brand of the article (reference only)","title":"Article Brand","type":"string"},"size":{"description":"Size of the article (reference only)","title":"Size","type":"string"},"color":{"description":"Color of the article (reference only)","title":"Color","type":"string"},"width":{"description":"Width of the article (in millimeters)","title":"Width","type":"number"},"height":{"description":"Height of the article (in millimeters)","title":"Height","type":"number"},"length":{"description":"Length of the article (in millimeters)","title":"Length","type":"number"},"length_unit":{"const":"cm","default":"cm","title":"Length Unit","type":"string"},"weight":{"description":"Weight of the article (in grams, kg, lbs, or oz)","title":"Weight","type":"number"},"weight_unit":{"allOf":[{"$ref":"#/components/schemas/WeightUnitEnum"}],"default":"g","title":"Weight Unit"},"unit_price":{"description":"Paid unit price of the article (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Unit Price","type":"string"},"unit_price_original":{"description":"Original unit price of the article (pre-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Unit Price","type":"string"},"quantity":{"description":"Unit quantity of the article","title":"Unit Quantity","type":"integer"},"amount_invoiced":{"description":"Paid line total amount for this line item (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Invoiced","type":"string"},"tax_amount":{"description":"Total tax amount for this line item (regardless of taxesIncluded)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Tax Amount","type":"string"},"harmonized_system_code":{"description":"HS/HTS code for customs classification","title":"Harmonized System Code","type":"string"},"origin_country_iso3":{"description":"ISO 3166-1 alpha-3 code of articles country of origin, might be required based on shipment regulations","pattern":"^\\w{3}$","title":"Origin Country ISO3","type":"string"},"is_bulky":{"default":false,"description":"If the article is bulky","title":"Is Bulky","type":"boolean"},"tags":{"description":"Tags for the line item, e.g. 'category:home-apparel', or 'customergroup:vip'","items":{"type":"string"},"title":"Tags","type":"array"},"bundle":{"anyOf":[{"$ref":"#/components/schemas/BundleInfo"},{"type":"null"}],"default":null,"description":"Bundle relationship metadata when the item is part of a bundle.","title":"Bundle Info"},"additional_attributes":{"description":"Additional attributes for this line item","items":{"$ref":"#/components/schemas/AdditionalAttribute"},"title":"Additional Attributes","type":"array"},"unit_price_msrp_current":{"anyOf":[{"pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","type":"string"},{"type":"null"}],"default":null,"description":"Current catalog/MSRP unit price for the same variant.","title":"Current MSRP"},"reference_date_for_return":{"description":"The date, which is used to evaluate the line item return period","format":"date","title":"Reference Date for Return","type":"string"},"reference_date_type":{"allOf":[{"$ref":"#/components/schemas/ReferenceDateTypeEnum"}],"description":"The date type, which is used to evaluate the line item return period","title":"Reference Date Type"},"fulfillment":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Id of the fulfillment that this item belongs to","title":"Fulfillment"},"quantity_returned":{"description":"Quantity of already returned items in this line.","title":"Quantity Returned","type":"integer"},"delivered_date":{"description":"Date when the line item was delivered (same as the fulfillment delivered date)","format":"date","title":"Delivered Date","type":"string"},"return_reason":{"description":"Full return reason path (as configured in the respective return configuration for this object)","title":"Return Reason","type":"string"},"return_reason_pretty":{"description":"Pretty text for the return reason, e.g. 'Doesn't Fit'","title":"Return Reason Pretty","type":"string"},"return_quantity":{"description":"Quantity to be returned","title":"Return Quantity","type":"integer"},"problem_description":{"description":"Description of the problem with this line item","title":"Problem Description","type":"string"},"condition":{"description":"Article condition, if provided","title":"Condition","type":"string"},"article_images":{"items":{"$ref":"#/components/schemas/ReturnImage"},"title":"Article Images","type":"array"},"compensation_method":{"description":"Compensation method for this line item, e.g. exchange, refund, credit","title":"Compensation Method","type":"string"},"accepted_quantity":{"description":"Quantity of the article that was accepted by warehouse","title":"Accepted Quantity","type":"integer"},"rejected_quantity":{"description":"Quantity of the article that was rejected by warehouse","title":"Rejected Quantity","type":"integer"},"status_reason":{"description":"Reason for the rejection / acceptance of the article","title":"Rejection or Acceptance Reason","type":"string"},"status_reason_code":{"description":"Structured reason code, e.g. quality_issue","title":"Status Reason Code","type":"string"},"return_reason_code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Final code of return reason (leaf code)","readOnly":true,"title":"Return Reason Code"}},"required":["line_item_id","return_reason_code"],"title":"Line Item","type":"object"},"ReferenceDateTypeEnum":{"enum":["order_date","shipping_date","delivery_date"],"type":"string"},"ReturnImage":{"properties":{"url":{"title":"Url","type":"string"},"name":{"title":"Name","type":"string"},"mime_type":{"title":"Mime Type","type":"string"}},"required":["url","name","mime_type"],"title":"ReturnImage","type":"object"},"ReturnLabel":{"properties":{"courier":{"description":"Return label courier code or drop-off code, e.g. barcode","title":"Return Label Courier","type":"string"},"service_level":{"description":"Service level of the return label","title":"Service Level","type":"string"},"tracking_number":{"description":"Tracking number of the return label (or in case of Barcode the barcode)","title":"Tracking number","type":"string"},"type":{"$ref":"#/components/schemas/ReturnLabelTypeEnum","default":"shipping","description":"Type of the return label, e.g. 'shipping' for a real courier label, or barcode for a (custom) drop-off code","title":"Label Type"},"flags":{"description":"Flags (extra markers) for the return label, such as 'has_dangerous_goods', or 'is_pickup'","items":{"$ref":"#/components/schemas/ReturnLabelFlagsEnum"},"title":"Label Flags","type":"array"},"documents":{"description":"Documents related to this return label (e.g. print label, barcode, packing slip, wallet-passes)","items":{"$ref":"#/components/schemas/Document"},"title":"Label","type":"array"},"locations_url":{"description":"URL to a courier-specific location finder page.","title":"Locations URL","type":"string"},"destination_id":{"description":"Destination ID for the return label, e.g. warehouse code","title":"Destination ID","type":"string"},"line_item_ids":{"description":"The line item IDs to which the label should be attached","items":{"type":"string"},"title":"Line Item IDs","type":"array"},"is_free_label":{"default":false,"description":"Indicates if the return label is free of charge","title":"Is Free Label","type":"boolean"},"label_cost_amount":{"default":"0.0","description":"Cost of the return label","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Label Cost Amount","type":"string"},"tracking_id":{"description":"Tracking ID of the shipment in the parcelLab system","title":"ParcelLab Tracking ID","type":"string"},"external_reference":{"description":"Unique retailer-provided reference of the shipment, either this tracking number is required","title":"External Reference","type":"string"},"delivery_status":{"$ref":"#/components/schemas/TrackingStageChoices","default":"Pending","description":"Current shipping stage of the return label","title":"Current Shipping Stage"},"pickup_date":{"description":"Scheduled pickup date for the return label. Nullable if not a pickup return.","format":"date","title":"Pickup Date","type":"string"},"earliest_pickup_time":{"description":"Earliest scheduled pickup time for the return label. Nullable if not a pickup return.","format":"time","title":"Earliest Pickup Time","type":"string"},"latest_pickup_time":{"description":"Latest scheduled pickup time for the return label. Nullable if not a pickup return.","format":"time","title":"Latest Pickup Time","type":"string"},"pickup_confirmation_code":{"description":"Confirmation code customer must present on pickup","title":"Pickup Confirmation Code","type":"string"},"is_pickup":{"default":false,"description":"Indicates if the return is a pickup order.","title":"Is Pickup","type":"boolean"},"configuration_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Selected return option mapping ID used to create this label.","title":"Courier Mapping ID"}},"required":["courier","tracking_number"],"title":"Return Label","type":"object"},"ReturnLabelTypeEnum":{"enum":["shipping","custom"],"title":"ReturnLabelTypeEnum","type":"string"},"ReturnLabelFlagsEnum":{"enum":["is_cancellable","is_pickup","has_dangerous_goods"],"type":"string"},"Document":{"properties":{"url":{"description":"URL to the document, in most cases this is a http URL, but it could also be a data URL (base64)","title":"Document URL","type":"string"},"content_type":{"default":"application/pdf","description":"MIME content type of the document, e.g. 'application/pdf'","title":"Content Type","type":"string"},"type":{"default":[],"description":"Type or types of the document, maybe multiple, if bundled","items":{"$ref":"#/components/schemas/DocumentTypeEnum"},"title":"Document Type","type":"array"},"expires_at":{"description":"Expiry date of the document, after which it might not be retrievable","format":"date-time","title":"Document expiry date","type":"string"}},"required":["url"],"title":"Document","type":"object"},"DocumentTypeEnum":{"enum":["label","packing_slip","barcode","customs_document","wallet_pass_io","wallet_pass_android","commercial_invoice"],"type":"string"},"TrackingStageChoices":{"enum":["Pending","Transit","Customs","LastMile","ReadyToCollect","Delivered","SentBack","Returned","Failed","Cancelled"],"title":"TrackingStageChoices","type":"string"},"AddLabelMutation":{"properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"add_label","default":"add_label","title":"Type","type":"string"},"request":{"$ref":"#/components/schemas/AddLabelRequest","description":"The labels to be added to this return registration","title":"Label Requests"}},"required":["request"],"title":"AddLabelMutation","type":"object"},"MutationResult":{"description":"The result of a mutation","properties":{"success":{"default":false,"description":"Whether the mutation was successful","title":"Success","type":"boolean"},"message":{"default":"","description":"A message describing the result of the mutation","title":"Message","type":"string"},"errors":{"additionalProperties":{"type":"string"},"description":"A dictionary of errors that occurred during the mutation","title":"Errors","type":"object"},"warnings":{"description":"Non-fatal warnings raised while processing the mutation","items":{"type":"string"},"title":"Warnings","type":"array"}},"title":"MutationResult","type":"object"},"AddLabelRequest":{"description":"Adds a label to a return registration","properties":{"type":{"$ref":"#/components/schemas/ReturnLabelTypeEnum"},"courier":{"description":"The courier for which a label should be created","title":"Courier","type":"string"},"tracking_number":{"description":"Only for custom label: custom tracking number for the label","title":"Tracking Number","type":"string"},"service_level":{"description":"The service level for the label","title":"Service Level","type":"string"},"destination_id":{"description":"The warehouse or other identifier, to which the courier should ship, corresponds to a warehouse code","title":"Identifier / Warehouse","type":"string"},"destination_address":{"$ref":"#/components/schemas/AddressSchema","description":"Defines a destination address for this label, has precedence over default destination addresses setup in courier configuration. If the courier does not support a custom destination address & the destination address object is present, will raise an error ","title":"Destination Address"},"template_id":{"description":"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.","title":"Template ID","type":"string"},"flags":{"description":"A list of special flags that apply to the label or shipment","items":{"$ref":"#/components/schemas/AddLabelFlagsEnum"},"title":"Flags","type":"array"},"label_types":{"description":"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).","items":{"$ref":"#/components/schemas/LabelTypesEnum"},"title":"Label Types","type":"array"},"line_item_ids":{"description":"The line item IDs to which the label should be attached","items":{"type":"string"},"title":"Line Item IDs","type":"array"},"additional_fields":{"additionalProperties":true,"description":"Custom fields to pass through to label generation and returns document.","title":"Additional Fields","type":"object"}},"required":["type","courier"],"title":"AddLabelRequest","type":"object"},"AddressSchema":{"properties":{"first_name":{"title":"First Name","type":"string"},"last_name":{"title":"Last Name","type":"string"},"company_name":{"title":"Company Name, if any","type":"string"},"address_line":{"description":"Address line, e.g. street and house number, or PO Box","maxLength":256,"minLength":1,"title":"Address Line","type":"string"},"address_line_extra":{"description":"Additional address line, e.g. apartment number or company name","title":"Additional Address Line","type":"string"},"postal_code":{"maxLength":10,"minLength":2,"title":"Postal Code","type":"string"},"city":{"description":"City name (min-length of 1 due to logographic languages)","maxLength":40,"minLength":1,"title":"City","type":"string"},"country_iso3":{"description":"ISO 3166-1 alpha-3 code of country","pattern":"^\\w{3}$","title":"Country ISO3","type":"string"},"region_code":{"description":"Region code, e.g. state or province code (ISO 3166-2), if available","maxLength":25,"minLength":1,"title":"Region Code","type":"string"},"phone":{"description":"Phone number related to this address, if any","maxLength":30,"title":"Phone","type":"string"}},"required":["address_line","postal_code","city","country_iso3"],"title":"Address","type":"object"},"AddLabelFlagsEnum":{"enum":["has_dangerous_goods","is_pickup"],"type":"string"},"LabelTypesEnum":{"enum":["code","print"],"type":"string"},"UpdateItemMutation":{"description":"Update registered article items","properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"update_items","default":"update_items","title":"Type","type":"string"},"items":{"description":"Items for this return registration after update is a applied","items":{"$ref":"#/components/schemas/LineItemReturn"},"title":"Line Items to return","type":"array"}},"title":"Update Items Mutation","type":"object"},"CloseReturnMutation":{"description":"Close a return registration (finalize return + refund).","properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"close_return","default":"close_return","title":"Type","type":"string"},"status_reason":{"description":"Optional reason for closing the return registration.","title":"Status Reason","type":"string"},"trigger_refund":{"description":"Whether to issue a monetary refund when closing the return.","title":"Trigger Refund","type":"boolean"},"release_exchange_items":{"description":"Whether to release exchange items when closing the return.","title":"Release Exchange Items","type":"boolean"},"refund_shipping_fees":{"description":"Whether to refund the original order shipping cost.","title":"Refund Shipping Fees","type":"boolean"},"tracking_number":{"description":"Optional tracking number used for receive-status synchronization when article status updates are provided.","title":"Tracking Number","type":"string"},"received_by":{"description":"Optional source shown in receive status when article status updates are provided. Defaults to API (close_return mutation).","title":"Received By","type":"string"},"receive_note":{"description":"Optional receive note stored with receive status and synchronized to tracking returnReceive.note when article status updates are provided.","title":"Receive Note","type":"string"},"article_status_updates":{"description":"Optional receive-style article status updates to apply before closing the return registration.","items":{"$ref":"#/components/schemas/ArticleStatusUpdate"},"title":"Article Status Updates","type":"array"}},"title":"CloseReturnMutation","type":"object"},"ArticleStatusUpdate":{"properties":{"identifier":{"description":"Identifier of the article to update the status for","title":"Identifier of article","type":"string"},"identifier_type":{"$ref":"#/components/schemas/ArticleIdentifierType","description":"The type of the identifier","title":"Identifier Type"},"accepted_quantity":{"default":0,"description":"The quantity of the article that was accepted","title":"Accepted Quantity","type":"integer"},"rejected_quantity":{"default":0,"description":"The quantity of the article that was rejected","title":"Rejected Quantity","type":"integer"},"reason":{"default":null,"description":"The reason for the rejection of the article","title":"Reason","type":"string"}},"required":["identifier","identifier_type"],"title":"ArticleStatusUpdate","type":"object"},"ArticleIdentifierType":{"enum":["product_id","line_item_id","sku","variant_id","barcode","order_item_id"],"title":"ArticleIdentifierType","type":"string"},"CancelReturnMutation":{"description":"Cancel a return registration and its tracking.","properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"cancel_return","default":"cancel_return","title":"Type","type":"string"},"status_reason":{"description":"Optional reason for cancelling the return registration.","title":"Status Reason","type":"string"}},"title":"CancelReturnMutation","type":"object"},"Error400Response":{"type":"object","properties":{"type":{"type":"string"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/GenericErrorItem"}}},"required":["errors","type"]},"GenericErrorItem":{"type":"object","properties":{"code":{"type":"string"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["code","detail"]},"ErrorResponse403":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ClientErrorEnum"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error403"}}},"required":["errors","type"]},"ClientErrorEnum":{"enum":["client_error"],"type":"string","description":"* `client_error` - Client Error"},"Error403":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode403Enum"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["attr","code","detail"]},"ErrorCode403Enum":{"enum":["permission_denied"],"type":"string","description":"* `permission_denied` - Permission Denied"},"ErrorResponse404":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ClientErrorEnum"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error404"}}},"required":["errors","type"]},"Error404":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode404Enum"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["attr","code","detail"]},"ErrorCode404Enum":{"enum":["not_found"],"type":"string","description":"* `not_found` - Not Found"}}},"paths":{"/v4/returns/return-registrations/":{"get":{"operationId":"returns_return_registrations_list","description":"Return Registrations represent a return request from a customer. There might be multiple\nreturn registrations for a single order. There might also be multiple labels for one return\nregistration, if requested by the customer.\n\n A return registration is linked to a configuration bundle (field 'code'), multiple configurations\n might be available on one account (e.g. country-specific courier configurations).\n\n Return registrations are created by the parcelLab return portal, or by the retailer via the parcelLab API.\n\nCertain fields of the return registration are not mutable via requests on the registration resource, but require\n'action' payloads to be submitted (e.g. 'AddLabel') to the 'mutate' action.","summary":"List Return Registration","parameters":[{"in":"query","name":"account","schema":{"type":"array","items":{"type":"integer"}},"explode":true,"style":"form"},{"in":"query","name":"client","schema":{"type":"integer"}},{"in":"query","name":"courier","schema":{"type":"string"}},{"in":"query","name":"created_at_after","schema":{"type":"string","format":"date-time"}},{"in":"query","name":"created_at_before","schema":{"type":"string","format":"date-time"}},{"in":"query","name":"creation_method","schema":{"type":"array","items":{"type":"string","enum":["existing_order","self_registration"]}},"description":"Describes the method used to create this return registration\n\n* `self_registration` - Self registration\n* `existing_order` - Existing order","explode":true,"style":"form"},{"name":"cursor","required":false,"in":"query","description":"The pagination cursor value.","schema":{"type":"string"}},{"in":"query","name":"customer_country_iso3","schema":{"type":"string"}},{"in":"query","name":"customer_postal_code","schema":{"type":"string"}},{"in":"query","name":"external_id","schema":{"type":"string","format":"uuid"}},{"in":"query","name":"external_reference","schema":{"type":"string"}},{"in":"query","name":"language_iso2","schema":{"type":"string"}},{"name":"ordering","required":false,"in":"query","description":"Which field to use when ordering the results.","schema":{"type":"string"}},{"in":"query","name":"reference","schema":{"type":"string"}},{"in":"query","name":"return_reason","schema":{"type":"string"}},{"in":"query","name":"return_reason_pretty","schema":{"type":"string"}},{"in":"query","name":"search","schema":{"type":"string"}},{"in":"query","name":"status","schema":{"type":"array","items":{"type":"string","enum":["approved","cancelled","closed","created","invalid","pending_approval","pending_label","processing_failed","rejected","submitted"]}},"description":"* `created` - Created\n* `submitted` - Submitted\n* `pending_approval` - Pending Approval\n* `pending_label` - Pending Label\n* `approved` - Approved\n* `rejected` - Rejected\n* `cancelled` - Cancelled\n* `closed` - Closed\n* `processing_failed` - Processing Failed\n* `invalid` - Invalid","explode":true,"style":"form"},{"in":"query","name":"status_not","schema":{"type":"array","items":{"type":"string","enum":["approved","cancelled","closed","created","invalid","pending_approval","pending_label","processing_failed","rejected","submitted"]}},"description":"* `created` - Created\n* `submitted` - Submitted\n* `pending_approval` - Pending Approval\n* `pending_label` - Pending Label\n* `approved` - Approved\n* `rejected` - Rejected\n* `cancelled` - Cancelled\n* `closed` - Closed\n* `processing_failed` - Processing Failed\n* `invalid` - Invalid","explode":true,"style":"form"},{"in":"query","name":"tags","schema":{"type":"string"}},{"in":"query","name":"tracking_number","schema":{"type":"string"}},{"in":"query","name":"updated_at_after","schema":{"type":"string","format":"date-time"}},{"in":"query","name":"updated_at_before","schema":{"type":"string","format":"date-time"}}],"tags":["Return Registration"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedReturnRegistrationList"}}},"description":""},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}},"description":""},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse403"}}},"description":""},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"description":""}}}}}} ``` ## Get a Return Registration You can retrieve a specific return registration using the `v4/returns/return-registrations/{external_id}` endpoint. ## Retrieve Return Registration > 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. ```json {"openapi":"3.1.0","info":{"title":"parcelLab API","version":"v4"},"security":[{"OAuth2 Authentication":[]},{"HeaderToken":[]}],"components":{"securitySchemes":{"OAuth2 Authentication":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"HeaderToken":{"type":"http","scheme":"bearer","bearerFormat":"Parcellab-API-Token base64(account_id:token)","description":"Send `Authorization: Parcellab-API-Token `.\n\n`` = `base64(account_id:token)` as provided in the portal."}},"schemas":{"ReturnRegistration":{"type":"object","description":"Represents a return registration","properties":{"account":{"type":"integer","description":"Account, that is linked to this registration."},"code":{"type":"string","title":"Configuration Code","description":"Configuration code of the return configuration","maxLength":255},"version":{"type":["string","null"]},"client_key":{"type":"string","readOnly":true,"description":"Name of the client, as configured in account setup."},"reference":{"type":"string","title":"Reference / Order Number","description":"Retailer reference, e.g. the order number, not unique","maxLength":255},"external_id":{"type":"string","format":"uuid","title":"External Identifier","description":"Unique identifier for this return registration, generated by parcelLab"},"external_reference":{"type":"string","description":"Additional identifier (e.g. shop system id) for this return registration, generated by the retailer","maxLength":255},"sequence_number":{"type":"string","readOnly":true},"status":{"$ref":"#/components/schemas/ReturnRegistrationStatusEnum"},"status_reason":{"type":"string","description":"Reason for the current status","maxLength":255},"original_courier":{"type":"string","maxLength":255},"original_order_id":{"type":["string","null"],"maxLength":255},"order_date":{"type":["string","null"],"format":"date-time","description":"Date of the order"},"order_currency":{"type":"string","description":"Currency of the order, e.g. USD, EUR (ISO 4217)","maxLength":3},"order_total_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Total amount of the original order"},"order_shipping_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Total shipping amount of the original order"},"order_tax_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Total tax amount of the original order"},"order_delivery_date":{"type":["string","null"],"format":"date-time","description":"Date of the order delivery"},"order_shipping_date":{"type":["string","null"],"format":"date-time","description":"Date of the order shipment"},"order_payment_method":{"type":"array","items":{"type":"string","maxLength":255},"description":"Payment method used for the order, as setup as reference items in the accounts configuration"},"language_iso2":{"type":"string","description":"ISO 639-1 language code of the recipient, if known, required for localized communication","maxLength":3},"is_gift_returns_portal":{"type":"boolean","readOnly":true},"customer_email":{"anyOf":[{"format":"email","type":"string"},{"const":"_unset","enum":["_unset"],"type":"string"}],"description":"Customers email address, must be provided, in case email is not known or should be unset, use the literal string '_unset' instead."},"customer_phone":{"type":"string","description":"Customer phone number","maxLength":255},"customer_salutation":{"type":"string","maxLength":255},"customer_first_name":{"type":"string","maxLength":255},"customer_last_name":{"type":"string","maxLength":255},"customer_country_iso3":{"type":"string","description":"ISO 3166-1 alpha-3 code of country","maxLength":3},"customer_address":{"anyOf":[{"$ref":"#/components/schemas/ValidatedAddressSchema"},{"$ref":"#/components/schemas/Empty"}]},"articles_order":{"items":{"$ref":"#/components/schemas/LineItem"},"type":"array"},"articles_return":{"items":{"$ref":"#/components/schemas/LineItemReturn"},"type":"array"},"return_labels":{"items":{"$ref":"#/components/schemas/ReturnLabel"},"type":"array","readOnly":true},"refund_method":{"type":"string","description":"Refund method selected by customer","maxLength":255},"tags":{"type":"array","items":{"type":"string","maxLength":255},"description":"Order level tags."},"additional_fields":{"type":"object","additionalProperties":{},"description":"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":{"type":"string","description":"Verification code (e.g. zip/email) used for this return registration","maxLength":255},"created_at":{"type":"string","format":"date-time","readOnly":true},"updated_at":{"type":"string","format":"date-time","readOnly":true},"mutations":{"items":{"anyOf":[{"$ref":"#/components/schemas/AddLabelMutation"},{"$ref":"#/components/schemas/UpdateItemMutation"},{"$ref":"#/components/schemas/CloseReturnMutation"},{"$ref":"#/components/schemas/CancelReturnMutation"}],"title":"Mutations"},"type":"array"}},"required":["account","client_key","code","created_at","customer_address","customer_email","is_gift_returns_portal","reference","return_labels","sequence_number","updated_at"]},"ReturnRegistrationStatusEnum":{"enum":["created","submitted","pending_approval","pending_label","approved","rejected","cancelled","closed","processing_failed","invalid"],"type":"string","description":"* `created` - Created\n* `submitted` - Submitted\n* `pending_approval` - Pending Approval\n* `pending_label` - Pending Label\n* `approved` - Approved\n* `rejected` - Rejected\n* `cancelled` - Cancelled\n* `closed` - Closed\n* `processing_failed` - Processing Failed\n* `invalid` - Invalid"},"ValidatedAddressSchema":{"properties":{"first_name":{"title":"First Name","type":"string"},"last_name":{"title":"Last Name","type":"string"},"company_name":{"title":"Company Name, if any","type":"string"},"address_line":{"description":"Address line, e.g. street and house number, or PO Box","maxLength":256,"minLength":1,"title":"Address Line","type":"string"},"address_line_extra":{"description":"Additional address line, e.g. apartment number or company name","title":"Additional Address Line","type":"string"},"postal_code":{"maxLength":10,"minLength":2,"title":"Postal Code","type":"string"},"city":{"description":"City name (min-length of 1 due to logographic languages)","maxLength":40,"minLength":1,"title":"City","type":"string"},"country_iso3":{"description":"ISO 3166-1 alpha-3 code of country","pattern":"^\\w{3}$","title":"Country ISO3","type":"string"},"region_code":{"description":"Region code, e.g. state or province code (ISO 3166-2), if available","maxLength":25,"minLength":1,"title":"Region Code","type":"string"},"phone":{"description":"Phone number related to this address, if any","maxLength":30,"title":"Phone","type":"string"}},"required":["address_line","postal_code","city","country_iso3"],"title":"Address","type":"object"},"Empty":{"additionalProperties":false,"properties":{},"title":"Empty","type":"object"},"LineItem":{"additionalProperties":true,"properties":{"version":{"$ref":"#/components/schemas/LineItemVersionEnum","description":"Optional. Omit this key unless absolutely intended. The standard value is `v2`. If you send `version`, send `v2`.","title":"Version"},"line_item_id":{"description":"Retailer ID of the line item","title":"Line Item ID","type":"string"},"product_id":{"description":"Parent product identifier in the retailer's system (shared across variants).","title":"Product ID","type":"string"},"variant_id":{"description":"SKU/variant identifier; prefer for matching when available since parent product IDs are reused across variants.","title":"Variant ID","type":"string"},"sku":{"description":"Stock Keeping Unit of the line item","title":"SKU","type":"string"},"barcode":{"description":"Barcode associated with the line item variant or product","title":"Barcode","type":"string"},"order_item_id":{"description":"Line Item ID in the order (preferred when provided)","title":"Order Line Item ID","type":"string"},"article_name":{"description":"Name of the article","title":"Article Name","type":"string"},"article_category":{"description":"Category of the article","title":"Article Category","type":"string"},"article_store_url":{"description":"URL to the article in the store","title":"Article Store URL","type":"string"},"article_image_url":{"description":"URL to the image of the article","title":"Article Image URL","type":"string"},"article_brand":{"description":"Brand of the article (reference only)","title":"Article Brand","type":"string"},"size":{"description":"Size of the article (reference only)","title":"Size","type":"string"},"color":{"description":"Color of the article (reference only)","title":"Color","type":"string"},"width":{"description":"Width of the article (in millimeters)","title":"Width","type":"number"},"height":{"description":"Height of the article (in millimeters)","title":"Height","type":"number"},"length":{"description":"Length of the article (in millimeters)","title":"Length","type":"number"},"length_unit":{"const":"cm","default":"cm","title":"Length Unit","type":"string"},"weight":{"description":"Weight of the article (in grams, kg, lbs, or oz)","title":"Weight","type":"number"},"weight_unit":{"allOf":[{"$ref":"#/components/schemas/WeightUnitEnum"}],"default":"g","title":"Weight Unit"},"unit_price":{"description":"Paid unit price of the article (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Unit Price","type":"string"},"unit_price_original":{"description":"Original unit price of the article (pre-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Unit Price","type":"string"},"quantity":{"description":"Unit quantity of the article","title":"Unit Quantity","type":"integer"},"amount_invoiced":{"description":"Paid line total amount for this line item (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Invoiced","type":"string"},"tax_amount":{"description":"Total tax amount for this line item (regardless of taxesIncluded)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Tax Amount","type":"string"},"harmonized_system_code":{"description":"HS/HTS code for customs classification","title":"Harmonized System Code","type":"string"},"origin_country_iso3":{"description":"ISO 3166-1 alpha-3 code of articles country of origin, might be required based on shipment regulations","pattern":"^\\w{3}$","title":"Origin Country ISO3","type":"string"},"is_bulky":{"default":false,"description":"If the article is bulky","title":"Is Bulky","type":"boolean"},"tags":{"description":"Tags for the line item, e.g. 'category:home-apparel', or 'customergroup:vip'","items":{"type":"string"},"title":"Tags","type":"array"},"bundle":{"anyOf":[{"$ref":"#/components/schemas/BundleInfo"},{"type":"null"}],"default":null,"description":"Bundle relationship metadata when the item is part of a bundle.","title":"Bundle Info"},"additional_attributes":{"description":"Additional attributes for this line item","items":{"$ref":"#/components/schemas/AdditionalAttribute"},"title":"Additional Attributes","type":"array"}},"required":["line_item_id"],"title":"Line Item","type":"object"},"LineItemVersionEnum":{"enum":["v1","v2"],"title":"LineItemVersionEnum","type":"string"},"WeightUnitEnum":{"enum":["kg","g","lbs","oz"],"type":"string"},"BundleInfo":{"additionalProperties":true,"properties":{"group_id":{"description":"Bundle group identifier in the retailer's system.","title":"Bundle Group ID","type":"string"},"role":{"$ref":"#/components/schemas/BundleRoleEnum","description":"Whether this line item represents a bundle parent or a bundle component.","title":"Bundle Role"},"return_policy":{"$ref":"#/components/schemas/BundleReturnPolicyEnum","default":"components_only","description":"Which lines in this bundle group are selectable for return.","title":"Bundle Return Policy"},"parent_product_id":{"description":"Parent bundle product identifier in the retailer's system.","title":"Bundle Parent Product ID","type":"string"},"parent_variant_id":{"description":"Parent bundle variant identifier in the retailer's system.","title":"Bundle Parent Variant ID","type":"string"},"parent_sku":{"description":"Parent bundle SKU, if available.","title":"Bundle Parent SKU","type":"string"},"parent_title":{"description":"Display title for the bundle parent, if available.","title":"Bundle Parent Title","type":"string"},"parent_quantity":{"description":"Quantity of the bundle parent purchased in the order.","title":"Bundle Parent Quantity","type":"integer"},"component_quantity_per_parent":{"description":"Component quantity per single bundle parent (if determinable).","title":"Bundle Component Quantity Per Parent","type":"integer"},"allocation_method":{"$ref":"#/components/schemas/BundleAllocationMethodEnum","default":"none","description":"How pricing was allocated to bundle components.","title":"Bundle Allocation Method"},"allocated_unit_price":{"description":"Snapshot of allocated component unit price (if derived from bundle totals).","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Allocated Unit Price","type":"string"},"allocated_amount_invoiced":{"description":"Snapshot of allocated component invoiced amount (if derived from bundle totals).","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Allocated Amount Invoiced","type":"string"}},"required":["group_id","role"],"title":"Bundle Info","type":"object"},"BundleRoleEnum":{"enum":["parent","component"],"title":"BundleRoleEnum","type":"string"},"BundleReturnPolicyEnum":{"enum":["parent_only","components_only","parent_and_components"],"title":"BundleReturnPolicyEnum","type":"string"},"BundleAllocationMethodEnum":{"enum":["none","component_price","msrp_ratio","equal"],"title":"BundleAllocationMethodEnum","type":"string"},"AdditionalAttribute":{"properties":{"key":{"description":"The key of the additional attribute","title":"Key","type":"string"},"value":{"default":null,"description":"The value of the additional attribute","title":"Value"}},"required":["key"],"title":"AdditionalAttribute","type":"object"},"LineItemReturn":{"additionalProperties":true,"properties":{"version":{"$ref":"#/components/schemas/LineItemVersionEnum","description":"Optional. Omit this key unless absolutely intended. The standard value is `v2`. If you send `version`, send `v2`.","title":"Version"},"line_item_id":{"description":"Retailer ID of the line item, only the last number part of the whole line item id string","title":"Line Item ID","type":"string"},"product_id":{"description":"Parent product identifier in the retailer's system (shared across variants).","title":"Product ID","type":"string"},"variant_id":{"description":"SKU/variant identifier; prefer for matching when available since parent product IDs are reused across variants.","title":"Variant ID","type":"string"},"sku":{"description":"Stock Keeping Unit of the line item","title":"SKU","type":"string"},"barcode":{"description":"Barcode associated with the line item variant or product","title":"Barcode","type":"string"},"order_item_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Line Item ID in the order, the whole id of the fulfillment line item","title":"Order Line Item ID"},"article_name":{"description":"Name of the article","title":"Article Name","type":"string"},"article_category":{"description":"Category of the article","title":"Article Category","type":"string"},"article_store_url":{"description":"URL to the article in the store","title":"Article Store URL","type":"string"},"article_image_url":{"description":"URL to the image of the article","title":"Article Image URL","type":"string"},"article_brand":{"description":"Brand of the article (reference only)","title":"Article Brand","type":"string"},"size":{"description":"Size of the article (reference only)","title":"Size","type":"string"},"color":{"description":"Color of the article (reference only)","title":"Color","type":"string"},"width":{"description":"Width of the article (in millimeters)","title":"Width","type":"number"},"height":{"description":"Height of the article (in millimeters)","title":"Height","type":"number"},"length":{"description":"Length of the article (in millimeters)","title":"Length","type":"number"},"length_unit":{"const":"cm","default":"cm","title":"Length Unit","type":"string"},"weight":{"description":"Weight of the article (in grams, kg, lbs, or oz)","title":"Weight","type":"number"},"weight_unit":{"allOf":[{"$ref":"#/components/schemas/WeightUnitEnum"}],"default":"g","title":"Weight Unit"},"unit_price":{"description":"Paid unit price of the article (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Unit Price","type":"string"},"unit_price_original":{"description":"Original unit price of the article (pre-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Unit Price","type":"string"},"quantity":{"description":"Unit quantity of the article","title":"Unit Quantity","type":"integer"},"amount_invoiced":{"description":"Paid line total amount for this line item (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Invoiced","type":"string"},"tax_amount":{"description":"Total tax amount for this line item (regardless of taxesIncluded)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Tax Amount","type":"string"},"harmonized_system_code":{"description":"HS/HTS code for customs classification","title":"Harmonized System Code","type":"string"},"origin_country_iso3":{"description":"ISO 3166-1 alpha-3 code of articles country of origin, might be required based on shipment regulations","pattern":"^\\w{3}$","title":"Origin Country ISO3","type":"string"},"is_bulky":{"default":false,"description":"If the article is bulky","title":"Is Bulky","type":"boolean"},"tags":{"description":"Tags for the line item, e.g. 'category:home-apparel', or 'customergroup:vip'","items":{"type":"string"},"title":"Tags","type":"array"},"bundle":{"anyOf":[{"$ref":"#/components/schemas/BundleInfo"},{"type":"null"}],"default":null,"description":"Bundle relationship metadata when the item is part of a bundle.","title":"Bundle Info"},"additional_attributes":{"description":"Additional attributes for this line item","items":{"$ref":"#/components/schemas/AdditionalAttribute"},"title":"Additional Attributes","type":"array"},"unit_price_msrp_current":{"anyOf":[{"pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","type":"string"},{"type":"null"}],"default":null,"description":"Current catalog/MSRP unit price for the same variant.","title":"Current MSRP"},"reference_date_for_return":{"description":"The date, which is used to evaluate the line item return period","format":"date","title":"Reference Date for Return","type":"string"},"reference_date_type":{"allOf":[{"$ref":"#/components/schemas/ReferenceDateTypeEnum"}],"description":"The date type, which is used to evaluate the line item return period","title":"Reference Date Type"},"fulfillment":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Id of the fulfillment that this item belongs to","title":"Fulfillment"},"quantity_returned":{"description":"Quantity of already returned items in this line.","title":"Quantity Returned","type":"integer"},"delivered_date":{"description":"Date when the line item was delivered (same as the fulfillment delivered date)","format":"date","title":"Delivered Date","type":"string"},"return_reason":{"description":"Full return reason path (as configured in the respective return configuration for this object)","title":"Return Reason","type":"string"},"return_reason_pretty":{"description":"Pretty text for the return reason, e.g. 'Doesn't Fit'","title":"Return Reason Pretty","type":"string"},"return_quantity":{"description":"Quantity to be returned","title":"Return Quantity","type":"integer"},"problem_description":{"description":"Description of the problem with this line item","title":"Problem Description","type":"string"},"condition":{"description":"Article condition, if provided","title":"Condition","type":"string"},"article_images":{"items":{"$ref":"#/components/schemas/ReturnImage"},"title":"Article Images","type":"array"},"compensation_method":{"description":"Compensation method for this line item, e.g. exchange, refund, credit","title":"Compensation Method","type":"string"},"accepted_quantity":{"description":"Quantity of the article that was accepted by warehouse","title":"Accepted Quantity","type":"integer"},"rejected_quantity":{"description":"Quantity of the article that was rejected by warehouse","title":"Rejected Quantity","type":"integer"},"status_reason":{"description":"Reason for the rejection / acceptance of the article","title":"Rejection or Acceptance Reason","type":"string"},"status_reason_code":{"description":"Structured reason code, e.g. quality_issue","title":"Status Reason Code","type":"string"},"return_reason_code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Final code of return reason (leaf code)","readOnly":true,"title":"Return Reason Code"}},"required":["line_item_id","return_reason_code"],"title":"Line Item","type":"object"},"ReferenceDateTypeEnum":{"enum":["order_date","shipping_date","delivery_date"],"type":"string"},"ReturnImage":{"properties":{"url":{"title":"Url","type":"string"},"name":{"title":"Name","type":"string"},"mime_type":{"title":"Mime Type","type":"string"}},"required":["url","name","mime_type"],"title":"ReturnImage","type":"object"},"ReturnLabel":{"properties":{"courier":{"description":"Return label courier code or drop-off code, e.g. barcode","title":"Return Label Courier","type":"string"},"service_level":{"description":"Service level of the return label","title":"Service Level","type":"string"},"tracking_number":{"description":"Tracking number of the return label (or in case of Barcode the barcode)","title":"Tracking number","type":"string"},"type":{"$ref":"#/components/schemas/ReturnLabelTypeEnum","default":"shipping","description":"Type of the return label, e.g. 'shipping' for a real courier label, or barcode for a (custom) drop-off code","title":"Label Type"},"flags":{"description":"Flags (extra markers) for the return label, such as 'has_dangerous_goods', or 'is_pickup'","items":{"$ref":"#/components/schemas/ReturnLabelFlagsEnum"},"title":"Label Flags","type":"array"},"documents":{"description":"Documents related to this return label (e.g. print label, barcode, packing slip, wallet-passes)","items":{"$ref":"#/components/schemas/Document"},"title":"Label","type":"array"},"locations_url":{"description":"URL to a courier-specific location finder page.","title":"Locations URL","type":"string"},"destination_id":{"description":"Destination ID for the return label, e.g. warehouse code","title":"Destination ID","type":"string"},"line_item_ids":{"description":"The line item IDs to which the label should be attached","items":{"type":"string"},"title":"Line Item IDs","type":"array"},"is_free_label":{"default":false,"description":"Indicates if the return label is free of charge","title":"Is Free Label","type":"boolean"},"label_cost_amount":{"default":"0.0","description":"Cost of the return label","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Label Cost Amount","type":"string"},"tracking_id":{"description":"Tracking ID of the shipment in the parcelLab system","title":"ParcelLab Tracking ID","type":"string"},"external_reference":{"description":"Unique retailer-provided reference of the shipment, either this tracking number is required","title":"External Reference","type":"string"},"delivery_status":{"$ref":"#/components/schemas/TrackingStageChoices","default":"Pending","description":"Current shipping stage of the return label","title":"Current Shipping Stage"},"pickup_date":{"description":"Scheduled pickup date for the return label. Nullable if not a pickup return.","format":"date","title":"Pickup Date","type":"string"},"earliest_pickup_time":{"description":"Earliest scheduled pickup time for the return label. Nullable if not a pickup return.","format":"time","title":"Earliest Pickup Time","type":"string"},"latest_pickup_time":{"description":"Latest scheduled pickup time for the return label. Nullable if not a pickup return.","format":"time","title":"Latest Pickup Time","type":"string"},"pickup_confirmation_code":{"description":"Confirmation code customer must present on pickup","title":"Pickup Confirmation Code","type":"string"},"is_pickup":{"default":false,"description":"Indicates if the return is a pickup order.","title":"Is Pickup","type":"boolean"},"configuration_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Selected return option mapping ID used to create this label.","title":"Courier Mapping ID"}},"required":["courier","tracking_number"],"title":"Return Label","type":"object"},"ReturnLabelTypeEnum":{"enum":["shipping","custom"],"title":"ReturnLabelTypeEnum","type":"string"},"ReturnLabelFlagsEnum":{"enum":["is_cancellable","is_pickup","has_dangerous_goods"],"type":"string"},"Document":{"properties":{"url":{"description":"URL to the document, in most cases this is a http URL, but it could also be a data URL (base64)","title":"Document URL","type":"string"},"content_type":{"default":"application/pdf","description":"MIME content type of the document, e.g. 'application/pdf'","title":"Content Type","type":"string"},"type":{"default":[],"description":"Type or types of the document, maybe multiple, if bundled","items":{"$ref":"#/components/schemas/DocumentTypeEnum"},"title":"Document Type","type":"array"},"expires_at":{"description":"Expiry date of the document, after which it might not be retrievable","format":"date-time","title":"Document expiry date","type":"string"}},"required":["url"],"title":"Document","type":"object"},"DocumentTypeEnum":{"enum":["label","packing_slip","barcode","customs_document","wallet_pass_io","wallet_pass_android","commercial_invoice"],"type":"string"},"TrackingStageChoices":{"enum":["Pending","Transit","Customs","LastMile","ReadyToCollect","Delivered","SentBack","Returned","Failed","Cancelled"],"title":"TrackingStageChoices","type":"string"},"AddLabelMutation":{"properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"add_label","default":"add_label","title":"Type","type":"string"},"request":{"$ref":"#/components/schemas/AddLabelRequest","description":"The labels to be added to this return registration","title":"Label Requests"}},"required":["request"],"title":"AddLabelMutation","type":"object"},"MutationResult":{"description":"The result of a mutation","properties":{"success":{"default":false,"description":"Whether the mutation was successful","title":"Success","type":"boolean"},"message":{"default":"","description":"A message describing the result of the mutation","title":"Message","type":"string"},"errors":{"additionalProperties":{"type":"string"},"description":"A dictionary of errors that occurred during the mutation","title":"Errors","type":"object"},"warnings":{"description":"Non-fatal warnings raised while processing the mutation","items":{"type":"string"},"title":"Warnings","type":"array"}},"title":"MutationResult","type":"object"},"AddLabelRequest":{"description":"Adds a label to a return registration","properties":{"type":{"$ref":"#/components/schemas/ReturnLabelTypeEnum"},"courier":{"description":"The courier for which a label should be created","title":"Courier","type":"string"},"tracking_number":{"description":"Only for custom label: custom tracking number for the label","title":"Tracking Number","type":"string"},"service_level":{"description":"The service level for the label","title":"Service Level","type":"string"},"destination_id":{"description":"The warehouse or other identifier, to which the courier should ship, corresponds to a warehouse code","title":"Identifier / Warehouse","type":"string"},"destination_address":{"$ref":"#/components/schemas/AddressSchema","description":"Defines a destination address for this label, has precedence over default destination addresses setup in courier configuration. If the courier does not support a custom destination address & the destination address object is present, will raise an error ","title":"Destination Address"},"template_id":{"description":"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.","title":"Template ID","type":"string"},"flags":{"description":"A list of special flags that apply to the label or shipment","items":{"$ref":"#/components/schemas/AddLabelFlagsEnum"},"title":"Flags","type":"array"},"label_types":{"description":"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).","items":{"$ref":"#/components/schemas/LabelTypesEnum"},"title":"Label Types","type":"array"},"line_item_ids":{"description":"The line item IDs to which the label should be attached","items":{"type":"string"},"title":"Line Item IDs","type":"array"},"additional_fields":{"additionalProperties":true,"description":"Custom fields to pass through to label generation and returns document.","title":"Additional Fields","type":"object"}},"required":["type","courier"],"title":"AddLabelRequest","type":"object"},"AddressSchema":{"properties":{"first_name":{"title":"First Name","type":"string"},"last_name":{"title":"Last Name","type":"string"},"company_name":{"title":"Company Name, if any","type":"string"},"address_line":{"description":"Address line, e.g. street and house number, or PO Box","maxLength":256,"minLength":1,"title":"Address Line","type":"string"},"address_line_extra":{"description":"Additional address line, e.g. apartment number or company name","title":"Additional Address Line","type":"string"},"postal_code":{"maxLength":10,"minLength":2,"title":"Postal Code","type":"string"},"city":{"description":"City name (min-length of 1 due to logographic languages)","maxLength":40,"minLength":1,"title":"City","type":"string"},"country_iso3":{"description":"ISO 3166-1 alpha-3 code of country","pattern":"^\\w{3}$","title":"Country ISO3","type":"string"},"region_code":{"description":"Region code, e.g. state or province code (ISO 3166-2), if available","maxLength":25,"minLength":1,"title":"Region Code","type":"string"},"phone":{"description":"Phone number related to this address, if any","maxLength":30,"title":"Phone","type":"string"}},"required":["address_line","postal_code","city","country_iso3"],"title":"Address","type":"object"},"AddLabelFlagsEnum":{"enum":["has_dangerous_goods","is_pickup"],"type":"string"},"LabelTypesEnum":{"enum":["code","print"],"type":"string"},"UpdateItemMutation":{"description":"Update registered article items","properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"update_items","default":"update_items","title":"Type","type":"string"},"items":{"description":"Items for this return registration after update is a applied","items":{"$ref":"#/components/schemas/LineItemReturn"},"title":"Line Items to return","type":"array"}},"title":"Update Items Mutation","type":"object"},"CloseReturnMutation":{"description":"Close a return registration (finalize return + refund).","properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"close_return","default":"close_return","title":"Type","type":"string"},"status_reason":{"description":"Optional reason for closing the return registration.","title":"Status Reason","type":"string"},"trigger_refund":{"description":"Whether to issue a monetary refund when closing the return.","title":"Trigger Refund","type":"boolean"},"release_exchange_items":{"description":"Whether to release exchange items when closing the return.","title":"Release Exchange Items","type":"boolean"},"refund_shipping_fees":{"description":"Whether to refund the original order shipping cost.","title":"Refund Shipping Fees","type":"boolean"},"tracking_number":{"description":"Optional tracking number used for receive-status synchronization when article status updates are provided.","title":"Tracking Number","type":"string"},"received_by":{"description":"Optional source shown in receive status when article status updates are provided. Defaults to API (close_return mutation).","title":"Received By","type":"string"},"receive_note":{"description":"Optional receive note stored with receive status and synchronized to tracking returnReceive.note when article status updates are provided.","title":"Receive Note","type":"string"},"article_status_updates":{"description":"Optional receive-style article status updates to apply before closing the return registration.","items":{"$ref":"#/components/schemas/ArticleStatusUpdate"},"title":"Article Status Updates","type":"array"}},"title":"CloseReturnMutation","type":"object"},"ArticleStatusUpdate":{"properties":{"identifier":{"description":"Identifier of the article to update the status for","title":"Identifier of article","type":"string"},"identifier_type":{"$ref":"#/components/schemas/ArticleIdentifierType","description":"The type of the identifier","title":"Identifier Type"},"accepted_quantity":{"default":0,"description":"The quantity of the article that was accepted","title":"Accepted Quantity","type":"integer"},"rejected_quantity":{"default":0,"description":"The quantity of the article that was rejected","title":"Rejected Quantity","type":"integer"},"reason":{"default":null,"description":"The reason for the rejection of the article","title":"Reason","type":"string"}},"required":["identifier","identifier_type"],"title":"ArticleStatusUpdate","type":"object"},"ArticleIdentifierType":{"enum":["product_id","line_item_id","sku","variant_id","barcode","order_item_id"],"title":"ArticleIdentifierType","type":"string"},"CancelReturnMutation":{"description":"Cancel a return registration and its tracking.","properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"cancel_return","default":"cancel_return","title":"Type","type":"string"},"status_reason":{"description":"Optional reason for cancelling the return registration.","title":"Status Reason","type":"string"}},"title":"CancelReturnMutation","type":"object"},"Error400Response":{"type":"object","properties":{"type":{"type":"string"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/GenericErrorItem"}}},"required":["errors","type"]},"GenericErrorItem":{"type":"object","properties":{"code":{"type":"string"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["code","detail"]},"ErrorResponse403":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ClientErrorEnum"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error403"}}},"required":["errors","type"]},"ClientErrorEnum":{"enum":["client_error"],"type":"string","description":"* `client_error` - Client Error"},"Error403":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode403Enum"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["attr","code","detail"]},"ErrorCode403Enum":{"enum":["permission_denied"],"type":"string","description":"* `permission_denied` - Permission Denied"},"ErrorResponse404":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ClientErrorEnum"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error404"}}},"required":["errors","type"]},"Error404":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode404Enum"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["attr","code","detail"]},"ErrorCode404Enum":{"enum":["not_found"],"type":"string","description":"* `not_found` - Not Found"}}},"paths":{"/v4/returns/return-registrations/{external_id}/":{"get":{"operationId":"returns_return_registrations_retrieve","description":"Return Registrations represent a return request from a customer. There might be multiple\nreturn registrations for a single order. There might also be multiple labels for one return\nregistration, if requested by the customer.\n\n A return registration is linked to a configuration bundle (field 'code'), multiple configurations\n might be available on one account (e.g. country-specific courier configurations).\n\n Return registrations are created by the parcelLab return portal, or by the retailer via the parcelLab API.\n\nCertain fields of the return registration are not mutable via requests on the registration resource, but require\n'action' payloads to be submitted (e.g. 'AddLabel') to the 'mutate' action.","summary":"Retrieve Return Registration","parameters":[{"in":"path","name":"external_id","schema":{"type":"string","format":"uuid","title":"External Identifier","description":"Unique identifier for this return registration, generated by parcelLab"},"required":true}],"tags":["Return Registration"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnRegistration"}}},"description":""},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}},"description":""},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse403"}}},"description":""},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"description":""}}}}}} ``` ## Create a Return Registration You can generate a new return registration for your account using the `v4/returns/return-registrations` endpoint. ## Register Return > Create a new return registration ```json {"openapi":"3.1.0","info":{"title":"parcelLab API","version":"v4"},"security":[{"OAuth2 Authentication":[]},{"HeaderToken":[]}],"components":{"securitySchemes":{"OAuth2 Authentication":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"HeaderToken":{"type":"http","scheme":"bearer","bearerFormat":"Parcellab-API-Token base64(account_id:token)","description":"Send `Authorization: Parcellab-API-Token `.\n\n`` = `base64(account_id:token)` as provided in the portal."}},"schemas":{"ReturnRegistrationRequest":{"type":"object","description":"Represents a return registration","properties":{"account":{"type":"integer","description":"Account, that is linked to this registration."},"code":{"type":"string","minLength":1,"title":"Configuration Code","description":"Configuration code of the return configuration","maxLength":255},"version":{"type":["string","null"]},"reference":{"type":"string","minLength":1,"title":"Reference / Order Number","description":"Retailer reference, e.g. the order number, not unique","maxLength":255},"external_id":{"type":"string","format":"uuid","title":"External Identifier","description":"Unique identifier for this return registration, generated by parcelLab"},"external_reference":{"type":"string","description":"Additional identifier (e.g. shop system id) for this return registration, generated by the retailer","maxLength":255},"status":{"$ref":"#/components/schemas/ReturnRegistrationStatusEnum"},"status_reason":{"type":"string","description":"Reason for the current status","maxLength":255},"original_courier":{"type":"string","maxLength":255},"original_order_id":{"type":["string","null"],"maxLength":255},"order_date":{"type":["string","null"],"format":"date-time","description":"Date of the order"},"order_currency":{"type":"string","description":"Currency of the order, e.g. USD, EUR (ISO 4217)","maxLength":3},"order_total_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Total amount of the original order"},"order_shipping_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Total shipping amount of the original order"},"order_tax_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Total tax amount of the original order"},"order_delivery_date":{"type":["string","null"],"format":"date-time","description":"Date of the order delivery"},"order_shipping_date":{"type":["string","null"],"format":"date-time","description":"Date of the order shipment"},"order_payment_method":{"type":"array","items":{"type":"string","minLength":1,"maxLength":255},"description":"Payment method used for the order, as setup as reference items in the accounts configuration"},"language_iso2":{"type":"string","description":"ISO 639-1 language code of the recipient, if known, required for localized communication","maxLength":3},"customer_email":{"anyOf":[{"format":"email","type":"string"},{"const":"_unset","enum":["_unset"],"type":"string"}],"minLength":1,"description":"Customers email address, must be provided, in case email is not known or should be unset, use the literal string '_unset' instead."},"customer_phone":{"type":"string","description":"Customer phone number","maxLength":255},"customer_salutation":{"type":"string","maxLength":255},"customer_first_name":{"type":"string","maxLength":255},"customer_last_name":{"type":"string","maxLength":255},"customer_country_iso3":{"type":"string","description":"ISO 3166-1 alpha-3 code of country","maxLength":3},"customer_address":{"anyOf":[{"$ref":"#/components/schemas/ValidatedAddressSchema"},{"$ref":"#/components/schemas/Empty"}]},"articles_order":{"items":{"$ref":"#/components/schemas/LineItem"},"type":"array"},"articles_return":{"items":{"$ref":"#/components/schemas/LineItemReturn"},"type":"array"},"refund_method":{"type":"string","description":"Refund method selected by customer","maxLength":255},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":255},"description":"Order level tags."},"additional_fields":{"type":"object","additionalProperties":{},"description":"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":{"type":"string","description":"Verification code (e.g. zip/email) used for this return registration","maxLength":255},"mutations":{"items":{"anyOf":[{"$ref":"#/components/schemas/AddLabelMutation"},{"$ref":"#/components/schemas/UpdateItemMutation"},{"$ref":"#/components/schemas/CloseReturnMutation"},{"$ref":"#/components/schemas/CancelReturnMutation"}],"title":"Mutations"},"type":"array"}},"required":["account","code","customer_address","customer_email","reference"]},"ReturnRegistrationStatusEnum":{"enum":["created","submitted","pending_approval","pending_label","approved","rejected","cancelled","closed","processing_failed","invalid"],"type":"string","description":"* `created` - Created\n* `submitted` - Submitted\n* `pending_approval` - Pending Approval\n* `pending_label` - Pending Label\n* `approved` - Approved\n* `rejected` - Rejected\n* `cancelled` - Cancelled\n* `closed` - Closed\n* `processing_failed` - Processing Failed\n* `invalid` - Invalid"},"ValidatedAddressSchema":{"properties":{"first_name":{"title":"First Name","type":"string"},"last_name":{"title":"Last Name","type":"string"},"company_name":{"title":"Company Name, if any","type":"string"},"address_line":{"description":"Address line, e.g. street and house number, or PO Box","maxLength":256,"minLength":1,"title":"Address Line","type":"string"},"address_line_extra":{"description":"Additional address line, e.g. apartment number or company name","title":"Additional Address Line","type":"string"},"postal_code":{"maxLength":10,"minLength":2,"title":"Postal Code","type":"string"},"city":{"description":"City name (min-length of 1 due to logographic languages)","maxLength":40,"minLength":1,"title":"City","type":"string"},"country_iso3":{"description":"ISO 3166-1 alpha-3 code of country","pattern":"^\\w{3}$","title":"Country ISO3","type":"string"},"region_code":{"description":"Region code, e.g. state or province code (ISO 3166-2), if available","maxLength":25,"minLength":1,"title":"Region Code","type":"string"},"phone":{"description":"Phone number related to this address, if any","maxLength":30,"title":"Phone","type":"string"}},"required":["address_line","postal_code","city","country_iso3"],"title":"Address","type":"object"},"Empty":{"additionalProperties":false,"properties":{},"title":"Empty","type":"object"},"LineItem":{"additionalProperties":true,"properties":{"version":{"$ref":"#/components/schemas/LineItemVersionEnum","description":"Optional. Omit this key unless absolutely intended. The standard value is `v2`. If you send `version`, send `v2`.","title":"Version"},"line_item_id":{"description":"Retailer ID of the line item","title":"Line Item ID","type":"string"},"product_id":{"description":"Parent product identifier in the retailer's system (shared across variants).","title":"Product ID","type":"string"},"variant_id":{"description":"SKU/variant identifier; prefer for matching when available since parent product IDs are reused across variants.","title":"Variant ID","type":"string"},"sku":{"description":"Stock Keeping Unit of the line item","title":"SKU","type":"string"},"barcode":{"description":"Barcode associated with the line item variant or product","title":"Barcode","type":"string"},"order_item_id":{"description":"Line Item ID in the order (preferred when provided)","title":"Order Line Item ID","type":"string"},"article_name":{"description":"Name of the article","title":"Article Name","type":"string"},"article_category":{"description":"Category of the article","title":"Article Category","type":"string"},"article_store_url":{"description":"URL to the article in the store","title":"Article Store URL","type":"string"},"article_image_url":{"description":"URL to the image of the article","title":"Article Image URL","type":"string"},"article_brand":{"description":"Brand of the article (reference only)","title":"Article Brand","type":"string"},"size":{"description":"Size of the article (reference only)","title":"Size","type":"string"},"color":{"description":"Color of the article (reference only)","title":"Color","type":"string"},"width":{"description":"Width of the article (in millimeters)","title":"Width","type":"number"},"height":{"description":"Height of the article (in millimeters)","title":"Height","type":"number"},"length":{"description":"Length of the article (in millimeters)","title":"Length","type":"number"},"length_unit":{"const":"cm","default":"cm","title":"Length Unit","type":"string"},"weight":{"description":"Weight of the article (in grams, kg, lbs, or oz)","title":"Weight","type":"number"},"weight_unit":{"allOf":[{"$ref":"#/components/schemas/WeightUnitEnum"}],"default":"g","title":"Weight Unit"},"unit_price":{"description":"Paid unit price of the article (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Unit Price","type":"string"},"unit_price_original":{"description":"Original unit price of the article (pre-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Unit Price","type":"string"},"quantity":{"description":"Unit quantity of the article","title":"Unit Quantity","type":"integer"},"amount_invoiced":{"description":"Paid line total amount for this line item (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Invoiced","type":"string"},"tax_amount":{"description":"Total tax amount for this line item (regardless of taxesIncluded)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Tax Amount","type":"string"},"harmonized_system_code":{"description":"HS/HTS code for customs classification","title":"Harmonized System Code","type":"string"},"origin_country_iso3":{"description":"ISO 3166-1 alpha-3 code of articles country of origin, might be required based on shipment regulations","pattern":"^\\w{3}$","title":"Origin Country ISO3","type":"string"},"is_bulky":{"default":false,"description":"If the article is bulky","title":"Is Bulky","type":"boolean"},"tags":{"description":"Tags for the line item, e.g. 'category:home-apparel', or 'customergroup:vip'","items":{"type":"string"},"title":"Tags","type":"array"},"bundle":{"anyOf":[{"$ref":"#/components/schemas/BundleInfo"},{"type":"null"}],"default":null,"description":"Bundle relationship metadata when the item is part of a bundle.","title":"Bundle Info"},"additional_attributes":{"description":"Additional attributes for this line item","items":{"$ref":"#/components/schemas/AdditionalAttribute"},"title":"Additional Attributes","type":"array"}},"required":["line_item_id"],"title":"Line Item","type":"object"},"LineItemVersionEnum":{"enum":["v1","v2"],"title":"LineItemVersionEnum","type":"string"},"WeightUnitEnum":{"enum":["kg","g","lbs","oz"],"type":"string"},"BundleInfo":{"additionalProperties":true,"properties":{"group_id":{"description":"Bundle group identifier in the retailer's system.","title":"Bundle Group ID","type":"string"},"role":{"$ref":"#/components/schemas/BundleRoleEnum","description":"Whether this line item represents a bundle parent or a bundle component.","title":"Bundle Role"},"return_policy":{"$ref":"#/components/schemas/BundleReturnPolicyEnum","default":"components_only","description":"Which lines in this bundle group are selectable for return.","title":"Bundle Return Policy"},"parent_product_id":{"description":"Parent bundle product identifier in the retailer's system.","title":"Bundle Parent Product ID","type":"string"},"parent_variant_id":{"description":"Parent bundle variant identifier in the retailer's system.","title":"Bundle Parent Variant ID","type":"string"},"parent_sku":{"description":"Parent bundle SKU, if available.","title":"Bundle Parent SKU","type":"string"},"parent_title":{"description":"Display title for the bundle parent, if available.","title":"Bundle Parent Title","type":"string"},"parent_quantity":{"description":"Quantity of the bundle parent purchased in the order.","title":"Bundle Parent Quantity","type":"integer"},"component_quantity_per_parent":{"description":"Component quantity per single bundle parent (if determinable).","title":"Bundle Component Quantity Per Parent","type":"integer"},"allocation_method":{"$ref":"#/components/schemas/BundleAllocationMethodEnum","default":"none","description":"How pricing was allocated to bundle components.","title":"Bundle Allocation Method"},"allocated_unit_price":{"description":"Snapshot of allocated component unit price (if derived from bundle totals).","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Allocated Unit Price","type":"string"},"allocated_amount_invoiced":{"description":"Snapshot of allocated component invoiced amount (if derived from bundle totals).","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Allocated Amount Invoiced","type":"string"}},"required":["group_id","role"],"title":"Bundle Info","type":"object"},"BundleRoleEnum":{"enum":["parent","component"],"title":"BundleRoleEnum","type":"string"},"BundleReturnPolicyEnum":{"enum":["parent_only","components_only","parent_and_components"],"title":"BundleReturnPolicyEnum","type":"string"},"BundleAllocationMethodEnum":{"enum":["none","component_price","msrp_ratio","equal"],"title":"BundleAllocationMethodEnum","type":"string"},"AdditionalAttribute":{"properties":{"key":{"description":"The key of the additional attribute","title":"Key","type":"string"},"value":{"default":null,"description":"The value of the additional attribute","title":"Value"}},"required":["key"],"title":"AdditionalAttribute","type":"object"},"LineItemReturn":{"additionalProperties":true,"properties":{"version":{"$ref":"#/components/schemas/LineItemVersionEnum","description":"Optional. Omit this key unless absolutely intended. The standard value is `v2`. If you send `version`, send `v2`.","title":"Version"},"line_item_id":{"description":"Retailer ID of the line item, only the last number part of the whole line item id string","title":"Line Item ID","type":"string"},"product_id":{"description":"Parent product identifier in the retailer's system (shared across variants).","title":"Product ID","type":"string"},"variant_id":{"description":"SKU/variant identifier; prefer for matching when available since parent product IDs are reused across variants.","title":"Variant ID","type":"string"},"sku":{"description":"Stock Keeping Unit of the line item","title":"SKU","type":"string"},"barcode":{"description":"Barcode associated with the line item variant or product","title":"Barcode","type":"string"},"order_item_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Line Item ID in the order, the whole id of the fulfillment line item","title":"Order Line Item ID"},"article_name":{"description":"Name of the article","title":"Article Name","type":"string"},"article_category":{"description":"Category of the article","title":"Article Category","type":"string"},"article_store_url":{"description":"URL to the article in the store","title":"Article Store URL","type":"string"},"article_image_url":{"description":"URL to the image of the article","title":"Article Image URL","type":"string"},"article_brand":{"description":"Brand of the article (reference only)","title":"Article Brand","type":"string"},"size":{"description":"Size of the article (reference only)","title":"Size","type":"string"},"color":{"description":"Color of the article (reference only)","title":"Color","type":"string"},"width":{"description":"Width of the article (in millimeters)","title":"Width","type":"number"},"height":{"description":"Height of the article (in millimeters)","title":"Height","type":"number"},"length":{"description":"Length of the article (in millimeters)","title":"Length","type":"number"},"length_unit":{"const":"cm","default":"cm","title":"Length Unit","type":"string"},"weight":{"description":"Weight of the article (in grams, kg, lbs, or oz)","title":"Weight","type":"number"},"weight_unit":{"allOf":[{"$ref":"#/components/schemas/WeightUnitEnum"}],"default":"g","title":"Weight Unit"},"unit_price":{"description":"Paid unit price of the article (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Unit Price","type":"string"},"unit_price_original":{"description":"Original unit price of the article (pre-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Unit Price","type":"string"},"quantity":{"description":"Unit quantity of the article","title":"Unit Quantity","type":"integer"},"amount_invoiced":{"description":"Paid line total amount for this line item (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Invoiced","type":"string"},"tax_amount":{"description":"Total tax amount for this line item (regardless of taxesIncluded)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Tax Amount","type":"string"},"harmonized_system_code":{"description":"HS/HTS code for customs classification","title":"Harmonized System Code","type":"string"},"origin_country_iso3":{"description":"ISO 3166-1 alpha-3 code of articles country of origin, might be required based on shipment regulations","pattern":"^\\w{3}$","title":"Origin Country ISO3","type":"string"},"is_bulky":{"default":false,"description":"If the article is bulky","title":"Is Bulky","type":"boolean"},"tags":{"description":"Tags for the line item, e.g. 'category:home-apparel', or 'customergroup:vip'","items":{"type":"string"},"title":"Tags","type":"array"},"bundle":{"anyOf":[{"$ref":"#/components/schemas/BundleInfo"},{"type":"null"}],"default":null,"description":"Bundle relationship metadata when the item is part of a bundle.","title":"Bundle Info"},"additional_attributes":{"description":"Additional attributes for this line item","items":{"$ref":"#/components/schemas/AdditionalAttribute"},"title":"Additional Attributes","type":"array"},"unit_price_msrp_current":{"anyOf":[{"pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","type":"string"},{"type":"null"}],"default":null,"description":"Current catalog/MSRP unit price for the same variant.","title":"Current MSRP"},"reference_date_for_return":{"description":"The date, which is used to evaluate the line item return period","format":"date","title":"Reference Date for Return","type":"string"},"reference_date_type":{"allOf":[{"$ref":"#/components/schemas/ReferenceDateTypeEnum"}],"description":"The date type, which is used to evaluate the line item return period","title":"Reference Date Type"},"fulfillment":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Id of the fulfillment that this item belongs to","title":"Fulfillment"},"quantity_returned":{"description":"Quantity of already returned items in this line.","title":"Quantity Returned","type":"integer"},"delivered_date":{"description":"Date when the line item was delivered (same as the fulfillment delivered date)","format":"date","title":"Delivered Date","type":"string"},"return_reason":{"description":"Full return reason path (as configured in the respective return configuration for this object)","title":"Return Reason","type":"string"},"return_reason_pretty":{"description":"Pretty text for the return reason, e.g. 'Doesn't Fit'","title":"Return Reason Pretty","type":"string"},"return_quantity":{"description":"Quantity to be returned","title":"Return Quantity","type":"integer"},"problem_description":{"description":"Description of the problem with this line item","title":"Problem Description","type":"string"},"condition":{"description":"Article condition, if provided","title":"Condition","type":"string"},"article_images":{"items":{"$ref":"#/components/schemas/ReturnImage"},"title":"Article Images","type":"array"},"compensation_method":{"description":"Compensation method for this line item, e.g. exchange, refund, credit","title":"Compensation Method","type":"string"},"accepted_quantity":{"description":"Quantity of the article that was accepted by warehouse","title":"Accepted Quantity","type":"integer"},"rejected_quantity":{"description":"Quantity of the article that was rejected by warehouse","title":"Rejected Quantity","type":"integer"},"status_reason":{"description":"Reason for the rejection / acceptance of the article","title":"Rejection or Acceptance Reason","type":"string"},"status_reason_code":{"description":"Structured reason code, e.g. quality_issue","title":"Status Reason Code","type":"string"},"return_reason_code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Final code of return reason (leaf code)","readOnly":true,"title":"Return Reason Code"}},"required":["line_item_id","return_reason_code"],"title":"Line Item","type":"object"},"ReferenceDateTypeEnum":{"enum":["order_date","shipping_date","delivery_date"],"type":"string"},"ReturnImage":{"properties":{"url":{"title":"Url","type":"string"},"name":{"title":"Name","type":"string"},"mime_type":{"title":"Mime Type","type":"string"}},"required":["url","name","mime_type"],"title":"ReturnImage","type":"object"},"AddLabelMutation":{"properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"add_label","default":"add_label","title":"Type","type":"string"},"request":{"$ref":"#/components/schemas/AddLabelRequest","description":"The labels to be added to this return registration","title":"Label Requests"}},"required":["request"],"title":"AddLabelMutation","type":"object"},"MutationResult":{"description":"The result of a mutation","properties":{"success":{"default":false,"description":"Whether the mutation was successful","title":"Success","type":"boolean"},"message":{"default":"","description":"A message describing the result of the mutation","title":"Message","type":"string"},"errors":{"additionalProperties":{"type":"string"},"description":"A dictionary of errors that occurred during the mutation","title":"Errors","type":"object"},"warnings":{"description":"Non-fatal warnings raised while processing the mutation","items":{"type":"string"},"title":"Warnings","type":"array"}},"title":"MutationResult","type":"object"},"AddLabelRequest":{"description":"Adds a label to a return registration","properties":{"type":{"$ref":"#/components/schemas/ReturnLabelTypeEnum"},"courier":{"description":"The courier for which a label should be created","title":"Courier","type":"string"},"tracking_number":{"description":"Only for custom label: custom tracking number for the label","title":"Tracking Number","type":"string"},"service_level":{"description":"The service level for the label","title":"Service Level","type":"string"},"destination_id":{"description":"The warehouse or other identifier, to which the courier should ship, corresponds to a warehouse code","title":"Identifier / Warehouse","type":"string"},"destination_address":{"$ref":"#/components/schemas/AddressSchema","description":"Defines a destination address for this label, has precedence over default destination addresses setup in courier configuration. If the courier does not support a custom destination address & the destination address object is present, will raise an error ","title":"Destination Address"},"template_id":{"description":"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.","title":"Template ID","type":"string"},"flags":{"description":"A list of special flags that apply to the label or shipment","items":{"$ref":"#/components/schemas/AddLabelFlagsEnum"},"title":"Flags","type":"array"},"label_types":{"description":"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).","items":{"$ref":"#/components/schemas/LabelTypesEnum"},"title":"Label Types","type":"array"},"line_item_ids":{"description":"The line item IDs to which the label should be attached","items":{"type":"string"},"title":"Line Item IDs","type":"array"},"additional_fields":{"additionalProperties":true,"description":"Custom fields to pass through to label generation and returns document.","title":"Additional Fields","type":"object"}},"required":["type","courier"],"title":"AddLabelRequest","type":"object"},"ReturnLabelTypeEnum":{"enum":["shipping","custom"],"title":"ReturnLabelTypeEnum","type":"string"},"AddressSchema":{"properties":{"first_name":{"title":"First Name","type":"string"},"last_name":{"title":"Last Name","type":"string"},"company_name":{"title":"Company Name, if any","type":"string"},"address_line":{"description":"Address line, e.g. street and house number, or PO Box","maxLength":256,"minLength":1,"title":"Address Line","type":"string"},"address_line_extra":{"description":"Additional address line, e.g. apartment number or company name","title":"Additional Address Line","type":"string"},"postal_code":{"maxLength":10,"minLength":2,"title":"Postal Code","type":"string"},"city":{"description":"City name (min-length of 1 due to logographic languages)","maxLength":40,"minLength":1,"title":"City","type":"string"},"country_iso3":{"description":"ISO 3166-1 alpha-3 code of country","pattern":"^\\w{3}$","title":"Country ISO3","type":"string"},"region_code":{"description":"Region code, e.g. state or province code (ISO 3166-2), if available","maxLength":25,"minLength":1,"title":"Region Code","type":"string"},"phone":{"description":"Phone number related to this address, if any","maxLength":30,"title":"Phone","type":"string"}},"required":["address_line","postal_code","city","country_iso3"],"title":"Address","type":"object"},"AddLabelFlagsEnum":{"enum":["has_dangerous_goods","is_pickup"],"type":"string"},"LabelTypesEnum":{"enum":["code","print"],"type":"string"},"UpdateItemMutation":{"description":"Update registered article items","properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"update_items","default":"update_items","title":"Type","type":"string"},"items":{"description":"Items for this return registration after update is a applied","items":{"$ref":"#/components/schemas/LineItemReturn"},"title":"Line Items to return","type":"array"}},"title":"Update Items Mutation","type":"object"},"CloseReturnMutation":{"description":"Close a return registration (finalize return + refund).","properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"close_return","default":"close_return","title":"Type","type":"string"},"status_reason":{"description":"Optional reason for closing the return registration.","title":"Status Reason","type":"string"},"trigger_refund":{"description":"Whether to issue a monetary refund when closing the return.","title":"Trigger Refund","type":"boolean"},"release_exchange_items":{"description":"Whether to release exchange items when closing the return.","title":"Release Exchange Items","type":"boolean"},"refund_shipping_fees":{"description":"Whether to refund the original order shipping cost.","title":"Refund Shipping Fees","type":"boolean"},"tracking_number":{"description":"Optional tracking number used for receive-status synchronization when article status updates are provided.","title":"Tracking Number","type":"string"},"received_by":{"description":"Optional source shown in receive status when article status updates are provided. Defaults to API (close_return mutation).","title":"Received By","type":"string"},"receive_note":{"description":"Optional receive note stored with receive status and synchronized to tracking returnReceive.note when article status updates are provided.","title":"Receive Note","type":"string"},"article_status_updates":{"description":"Optional receive-style article status updates to apply before closing the return registration.","items":{"$ref":"#/components/schemas/ArticleStatusUpdate"},"title":"Article Status Updates","type":"array"}},"title":"CloseReturnMutation","type":"object"},"ArticleStatusUpdate":{"properties":{"identifier":{"description":"Identifier of the article to update the status for","title":"Identifier of article","type":"string"},"identifier_type":{"$ref":"#/components/schemas/ArticleIdentifierType","description":"The type of the identifier","title":"Identifier Type"},"accepted_quantity":{"default":0,"description":"The quantity of the article that was accepted","title":"Accepted Quantity","type":"integer"},"rejected_quantity":{"default":0,"description":"The quantity of the article that was rejected","title":"Rejected Quantity","type":"integer"},"reason":{"default":null,"description":"The reason for the rejection of the article","title":"Reason","type":"string"}},"required":["identifier","identifier_type"],"title":"ArticleStatusUpdate","type":"object"},"ArticleIdentifierType":{"enum":["product_id","line_item_id","sku","variant_id","barcode","order_item_id"],"title":"ArticleIdentifierType","type":"string"},"CancelReturnMutation":{"description":"Cancel a return registration and its tracking.","properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"cancel_return","default":"cancel_return","title":"Type","type":"string"},"status_reason":{"description":"Optional reason for cancelling the return registration.","title":"Status Reason","type":"string"}},"title":"CancelReturnMutation","type":"object"},"ReturnRegistration":{"type":"object","description":"Represents a return registration","properties":{"account":{"type":"integer","description":"Account, that is linked to this registration."},"code":{"type":"string","title":"Configuration Code","description":"Configuration code of the return configuration","maxLength":255},"version":{"type":["string","null"]},"client_key":{"type":"string","readOnly":true,"description":"Name of the client, as configured in account setup."},"reference":{"type":"string","title":"Reference / Order Number","description":"Retailer reference, e.g. the order number, not unique","maxLength":255},"external_id":{"type":"string","format":"uuid","title":"External Identifier","description":"Unique identifier for this return registration, generated by parcelLab"},"external_reference":{"type":"string","description":"Additional identifier (e.g. shop system id) for this return registration, generated by the retailer","maxLength":255},"sequence_number":{"type":"string","readOnly":true},"status":{"$ref":"#/components/schemas/ReturnRegistrationStatusEnum"},"status_reason":{"type":"string","description":"Reason for the current status","maxLength":255},"original_courier":{"type":"string","maxLength":255},"original_order_id":{"type":["string","null"],"maxLength":255},"order_date":{"type":["string","null"],"format":"date-time","description":"Date of the order"},"order_currency":{"type":"string","description":"Currency of the order, e.g. USD, EUR (ISO 4217)","maxLength":3},"order_total_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Total amount of the original order"},"order_shipping_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Total shipping amount of the original order"},"order_tax_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Total tax amount of the original order"},"order_delivery_date":{"type":["string","null"],"format":"date-time","description":"Date of the order delivery"},"order_shipping_date":{"type":["string","null"],"format":"date-time","description":"Date of the order shipment"},"order_payment_method":{"type":"array","items":{"type":"string","maxLength":255},"description":"Payment method used for the order, as setup as reference items in the accounts configuration"},"language_iso2":{"type":"string","description":"ISO 639-1 language code of the recipient, if known, required for localized communication","maxLength":3},"is_gift_returns_portal":{"type":"boolean","readOnly":true},"customer_email":{"anyOf":[{"format":"email","type":"string"},{"const":"_unset","enum":["_unset"],"type":"string"}],"description":"Customers email address, must be provided, in case email is not known or should be unset, use the literal string '_unset' instead."},"customer_phone":{"type":"string","description":"Customer phone number","maxLength":255},"customer_salutation":{"type":"string","maxLength":255},"customer_first_name":{"type":"string","maxLength":255},"customer_last_name":{"type":"string","maxLength":255},"customer_country_iso3":{"type":"string","description":"ISO 3166-1 alpha-3 code of country","maxLength":3},"customer_address":{"anyOf":[{"$ref":"#/components/schemas/ValidatedAddressSchema"},{"$ref":"#/components/schemas/Empty"}]},"articles_order":{"items":{"$ref":"#/components/schemas/LineItem"},"type":"array"},"articles_return":{"items":{"$ref":"#/components/schemas/LineItemReturn"},"type":"array"},"return_labels":{"items":{"$ref":"#/components/schemas/ReturnLabel"},"type":"array","readOnly":true},"refund_method":{"type":"string","description":"Refund method selected by customer","maxLength":255},"tags":{"type":"array","items":{"type":"string","maxLength":255},"description":"Order level tags."},"additional_fields":{"type":"object","additionalProperties":{},"description":"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":{"type":"string","description":"Verification code (e.g. zip/email) used for this return registration","maxLength":255},"created_at":{"type":"string","format":"date-time","readOnly":true},"updated_at":{"type":"string","format":"date-time","readOnly":true},"mutations":{"items":{"anyOf":[{"$ref":"#/components/schemas/AddLabelMutation"},{"$ref":"#/components/schemas/UpdateItemMutation"},{"$ref":"#/components/schemas/CloseReturnMutation"},{"$ref":"#/components/schemas/CancelReturnMutation"}],"title":"Mutations"},"type":"array"}},"required":["account","client_key","code","created_at","customer_address","customer_email","is_gift_returns_portal","reference","return_labels","sequence_number","updated_at"]},"ReturnLabel":{"properties":{"courier":{"description":"Return label courier code or drop-off code, e.g. barcode","title":"Return Label Courier","type":"string"},"service_level":{"description":"Service level of the return label","title":"Service Level","type":"string"},"tracking_number":{"description":"Tracking number of the return label (or in case of Barcode the barcode)","title":"Tracking number","type":"string"},"type":{"$ref":"#/components/schemas/ReturnLabelTypeEnum","default":"shipping","description":"Type of the return label, e.g. 'shipping' for a real courier label, or barcode for a (custom) drop-off code","title":"Label Type"},"flags":{"description":"Flags (extra markers) for the return label, such as 'has_dangerous_goods', or 'is_pickup'","items":{"$ref":"#/components/schemas/ReturnLabelFlagsEnum"},"title":"Label Flags","type":"array"},"documents":{"description":"Documents related to this return label (e.g. print label, barcode, packing slip, wallet-passes)","items":{"$ref":"#/components/schemas/Document"},"title":"Label","type":"array"},"locations_url":{"description":"URL to a courier-specific location finder page.","title":"Locations URL","type":"string"},"destination_id":{"description":"Destination ID for the return label, e.g. warehouse code","title":"Destination ID","type":"string"},"line_item_ids":{"description":"The line item IDs to which the label should be attached","items":{"type":"string"},"title":"Line Item IDs","type":"array"},"is_free_label":{"default":false,"description":"Indicates if the return label is free of charge","title":"Is Free Label","type":"boolean"},"label_cost_amount":{"default":"0.0","description":"Cost of the return label","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Label Cost Amount","type":"string"},"tracking_id":{"description":"Tracking ID of the shipment in the parcelLab system","title":"ParcelLab Tracking ID","type":"string"},"external_reference":{"description":"Unique retailer-provided reference of the shipment, either this tracking number is required","title":"External Reference","type":"string"},"delivery_status":{"$ref":"#/components/schemas/TrackingStageChoices","default":"Pending","description":"Current shipping stage of the return label","title":"Current Shipping Stage"},"pickup_date":{"description":"Scheduled pickup date for the return label. Nullable if not a pickup return.","format":"date","title":"Pickup Date","type":"string"},"earliest_pickup_time":{"description":"Earliest scheduled pickup time for the return label. Nullable if not a pickup return.","format":"time","title":"Earliest Pickup Time","type":"string"},"latest_pickup_time":{"description":"Latest scheduled pickup time for the return label. Nullable if not a pickup return.","format":"time","title":"Latest Pickup Time","type":"string"},"pickup_confirmation_code":{"description":"Confirmation code customer must present on pickup","title":"Pickup Confirmation Code","type":"string"},"is_pickup":{"default":false,"description":"Indicates if the return is a pickup order.","title":"Is Pickup","type":"boolean"},"configuration_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Selected return option mapping ID used to create this label.","title":"Courier Mapping ID"}},"required":["courier","tracking_number"],"title":"Return Label","type":"object"},"ReturnLabelFlagsEnum":{"enum":["is_cancellable","is_pickup","has_dangerous_goods"],"type":"string"},"Document":{"properties":{"url":{"description":"URL to the document, in most cases this is a http URL, but it could also be a data URL (base64)","title":"Document URL","type":"string"},"content_type":{"default":"application/pdf","description":"MIME content type of the document, e.g. 'application/pdf'","title":"Content Type","type":"string"},"type":{"default":[],"description":"Type or types of the document, maybe multiple, if bundled","items":{"$ref":"#/components/schemas/DocumentTypeEnum"},"title":"Document Type","type":"array"},"expires_at":{"description":"Expiry date of the document, after which it might not be retrievable","format":"date-time","title":"Document expiry date","type":"string"}},"required":["url"],"title":"Document","type":"object"},"DocumentTypeEnum":{"enum":["label","packing_slip","barcode","customs_document","wallet_pass_io","wallet_pass_android","commercial_invoice"],"type":"string"},"TrackingStageChoices":{"enum":["Pending","Transit","Customs","LastMile","ReadyToCollect","Delivered","SentBack","Returned","Failed","Cancelled"],"title":"TrackingStageChoices","type":"string"},"Error400Response":{"type":"object","properties":{"type":{"type":"string"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/GenericErrorItem"}}},"required":["errors","type"]},"GenericErrorItem":{"type":"object","properties":{"code":{"type":"string"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["code","detail"]},"ErrorResponse403":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ClientErrorEnum"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error403"}}},"required":["errors","type"]},"ClientErrorEnum":{"enum":["client_error"],"type":"string","description":"* `client_error` - Client Error"},"Error403":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode403Enum"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["attr","code","detail"]},"ErrorCode403Enum":{"enum":["permission_denied"],"type":"string","description":"* `permission_denied` - Permission Denied"},"ErrorResponse404":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ClientErrorEnum"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error404"}}},"required":["errors","type"]},"Error404":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode404Enum"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["attr","code","detail"]},"ErrorCode404Enum":{"enum":["not_found"],"type":"string","description":"* `not_found` - Not Found"}}},"paths":{"/v4/returns/return-registrations/":{"post":{"operationId":"returns_return_registrations_create","description":"Create a new return registration","summary":"Register Return","parameters":[{"in":"query","name":"courier_testing","schema":{"type":"boolean","default":false},"description":"Set to `true` to use the test environment for carrier integration."},{"in":"query","name":"draft","schema":{"type":"boolean","default":false},"description":"Set to `true` to preview behavior using unpublished configuration changes (e.g., article rules or courier options)."}],"tags":["Return Registration"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnRegistrationRequest"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/ReturnRegistrationRequest"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/ReturnRegistrationRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnRegistration"}}},"description":""},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}},"description":""},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse403"}}},"description":""},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"description":""}}}}}} ``` ## Create a Return Registration via Order Information You can generate a new return registration for your account from the order details using the `v4/returns/return-registrations/lookup-order` endpoint. ## Create Return Registration (from order) > 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. ```json {"openapi":"3.1.0","info":{"title":"parcelLab API","version":"v4"},"security":[{"OAuth2 Authentication":[]},{"HeaderToken":[]}],"components":{"securitySchemes":{"OAuth2 Authentication":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"HeaderToken":{"type":"http","scheme":"bearer","bearerFormat":"Parcellab-API-Token base64(account_id:token)","description":"Send `Authorization: Parcellab-API-Token `.\n\n`` = `base64(account_id:token)` as provided in the portal."}},"schemas":{"CreateRegistrationFromOrderRequest":{"properties":{"account":{"description":"The account ID to create this return registration on.","title":"Account ID","type":"integer"},"code":{"description":"Configuration code (unique identifier of the return portal or configuration used for this return","title":"Configuration code","type":"string"},"identifier":{"$ref":"#/components/schemas/SearchIdentity","description":"The identifier information to find the order, e.g. order number and email","title":"Identifier Information"}},"required":["account","code","identifier"],"title":"CreateRegistrationFromOrder","type":"object"},"SearchIdentity":{"properties":{"reference":{"title":"Reference, e.g. order number of the return","type":"string"},"identifier":{"title":"Login, e.g. email address or zip code of the customer","type":"string"}},"required":["reference","identifier"],"title":"SearchIdentity","type":"object"},"ReturnRegistration":{"type":"object","description":"Represents a return registration","properties":{"account":{"type":"integer","description":"Account, that is linked to this registration."},"code":{"type":"string","title":"Configuration Code","description":"Configuration code of the return configuration","maxLength":255},"version":{"type":["string","null"]},"client_key":{"type":"string","readOnly":true,"description":"Name of the client, as configured in account setup."},"reference":{"type":"string","title":"Reference / Order Number","description":"Retailer reference, e.g. the order number, not unique","maxLength":255},"external_id":{"type":"string","format":"uuid","title":"External Identifier","description":"Unique identifier for this return registration, generated by parcelLab"},"external_reference":{"type":"string","description":"Additional identifier (e.g. shop system id) for this return registration, generated by the retailer","maxLength":255},"sequence_number":{"type":"string","readOnly":true},"status":{"$ref":"#/components/schemas/ReturnRegistrationStatusEnum"},"status_reason":{"type":"string","description":"Reason for the current status","maxLength":255},"original_courier":{"type":"string","maxLength":255},"original_order_id":{"type":["string","null"],"maxLength":255},"order_date":{"type":["string","null"],"format":"date-time","description":"Date of the order"},"order_currency":{"type":"string","description":"Currency of the order, e.g. USD, EUR (ISO 4217)","maxLength":3},"order_total_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Total amount of the original order"},"order_shipping_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Total shipping amount of the original order"},"order_tax_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Total tax amount of the original order"},"order_delivery_date":{"type":["string","null"],"format":"date-time","description":"Date of the order delivery"},"order_shipping_date":{"type":["string","null"],"format":"date-time","description":"Date of the order shipment"},"order_payment_method":{"type":"array","items":{"type":"string","maxLength":255},"description":"Payment method used for the order, as setup as reference items in the accounts configuration"},"language_iso2":{"type":"string","description":"ISO 639-1 language code of the recipient, if known, required for localized communication","maxLength":3},"is_gift_returns_portal":{"type":"boolean","readOnly":true},"customer_email":{"anyOf":[{"format":"email","type":"string"},{"const":"_unset","enum":["_unset"],"type":"string"}],"description":"Customers email address, must be provided, in case email is not known or should be unset, use the literal string '_unset' instead."},"customer_phone":{"type":"string","description":"Customer phone number","maxLength":255},"customer_salutation":{"type":"string","maxLength":255},"customer_first_name":{"type":"string","maxLength":255},"customer_last_name":{"type":"string","maxLength":255},"customer_country_iso3":{"type":"string","description":"ISO 3166-1 alpha-3 code of country","maxLength":3},"customer_address":{"anyOf":[{"$ref":"#/components/schemas/ValidatedAddressSchema"},{"$ref":"#/components/schemas/Empty"}]},"articles_order":{"items":{"$ref":"#/components/schemas/LineItem"},"type":"array"},"articles_return":{"items":{"$ref":"#/components/schemas/LineItemReturn"},"type":"array"},"return_labels":{"items":{"$ref":"#/components/schemas/ReturnLabel"},"type":"array","readOnly":true},"refund_method":{"type":"string","description":"Refund method selected by customer","maxLength":255},"tags":{"type":"array","items":{"type":"string","maxLength":255},"description":"Order level tags."},"additional_fields":{"type":"object","additionalProperties":{},"description":"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":{"type":"string","description":"Verification code (e.g. zip/email) used for this return registration","maxLength":255},"created_at":{"type":"string","format":"date-time","readOnly":true},"updated_at":{"type":"string","format":"date-time","readOnly":true},"mutations":{"items":{"anyOf":[{"$ref":"#/components/schemas/AddLabelMutation"},{"$ref":"#/components/schemas/UpdateItemMutation"},{"$ref":"#/components/schemas/CloseReturnMutation"},{"$ref":"#/components/schemas/CancelReturnMutation"}],"title":"Mutations"},"type":"array"}},"required":["account","client_key","code","created_at","customer_address","customer_email","is_gift_returns_portal","reference","return_labels","sequence_number","updated_at"]},"ReturnRegistrationStatusEnum":{"enum":["created","submitted","pending_approval","pending_label","approved","rejected","cancelled","closed","processing_failed","invalid"],"type":"string","description":"* `created` - Created\n* `submitted` - Submitted\n* `pending_approval` - Pending Approval\n* `pending_label` - Pending Label\n* `approved` - Approved\n* `rejected` - Rejected\n* `cancelled` - Cancelled\n* `closed` - Closed\n* `processing_failed` - Processing Failed\n* `invalid` - Invalid"},"ValidatedAddressSchema":{"properties":{"first_name":{"title":"First Name","type":"string"},"last_name":{"title":"Last Name","type":"string"},"company_name":{"title":"Company Name, if any","type":"string"},"address_line":{"description":"Address line, e.g. street and house number, or PO Box","maxLength":256,"minLength":1,"title":"Address Line","type":"string"},"address_line_extra":{"description":"Additional address line, e.g. apartment number or company name","title":"Additional Address Line","type":"string"},"postal_code":{"maxLength":10,"minLength":2,"title":"Postal Code","type":"string"},"city":{"description":"City name (min-length of 1 due to logographic languages)","maxLength":40,"minLength":1,"title":"City","type":"string"},"country_iso3":{"description":"ISO 3166-1 alpha-3 code of country","pattern":"^\\w{3}$","title":"Country ISO3","type":"string"},"region_code":{"description":"Region code, e.g. state or province code (ISO 3166-2), if available","maxLength":25,"minLength":1,"title":"Region Code","type":"string"},"phone":{"description":"Phone number related to this address, if any","maxLength":30,"title":"Phone","type":"string"}},"required":["address_line","postal_code","city","country_iso3"],"title":"Address","type":"object"},"Empty":{"additionalProperties":false,"properties":{},"title":"Empty","type":"object"},"LineItem":{"additionalProperties":true,"properties":{"version":{"$ref":"#/components/schemas/LineItemVersionEnum","description":"Optional. Omit this key unless absolutely intended. The standard value is `v2`. If you send `version`, send `v2`.","title":"Version"},"line_item_id":{"description":"Retailer ID of the line item","title":"Line Item ID","type":"string"},"product_id":{"description":"Parent product identifier in the retailer's system (shared across variants).","title":"Product ID","type":"string"},"variant_id":{"description":"SKU/variant identifier; prefer for matching when available since parent product IDs are reused across variants.","title":"Variant ID","type":"string"},"sku":{"description":"Stock Keeping Unit of the line item","title":"SKU","type":"string"},"barcode":{"description":"Barcode associated with the line item variant or product","title":"Barcode","type":"string"},"order_item_id":{"description":"Line Item ID in the order (preferred when provided)","title":"Order Line Item ID","type":"string"},"article_name":{"description":"Name of the article","title":"Article Name","type":"string"},"article_category":{"description":"Category of the article","title":"Article Category","type":"string"},"article_store_url":{"description":"URL to the article in the store","title":"Article Store URL","type":"string"},"article_image_url":{"description":"URL to the image of the article","title":"Article Image URL","type":"string"},"article_brand":{"description":"Brand of the article (reference only)","title":"Article Brand","type":"string"},"size":{"description":"Size of the article (reference only)","title":"Size","type":"string"},"color":{"description":"Color of the article (reference only)","title":"Color","type":"string"},"width":{"description":"Width of the article (in millimeters)","title":"Width","type":"number"},"height":{"description":"Height of the article (in millimeters)","title":"Height","type":"number"},"length":{"description":"Length of the article (in millimeters)","title":"Length","type":"number"},"length_unit":{"const":"cm","default":"cm","title":"Length Unit","type":"string"},"weight":{"description":"Weight of the article (in grams, kg, lbs, or oz)","title":"Weight","type":"number"},"weight_unit":{"allOf":[{"$ref":"#/components/schemas/WeightUnitEnum"}],"default":"g","title":"Weight Unit"},"unit_price":{"description":"Paid unit price of the article (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Unit Price","type":"string"},"unit_price_original":{"description":"Original unit price of the article (pre-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Unit Price","type":"string"},"quantity":{"description":"Unit quantity of the article","title":"Unit Quantity","type":"integer"},"amount_invoiced":{"description":"Paid line total amount for this line item (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Invoiced","type":"string"},"tax_amount":{"description":"Total tax amount for this line item (regardless of taxesIncluded)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Tax Amount","type":"string"},"harmonized_system_code":{"description":"HS/HTS code for customs classification","title":"Harmonized System Code","type":"string"},"origin_country_iso3":{"description":"ISO 3166-1 alpha-3 code of articles country of origin, might be required based on shipment regulations","pattern":"^\\w{3}$","title":"Origin Country ISO3","type":"string"},"is_bulky":{"default":false,"description":"If the article is bulky","title":"Is Bulky","type":"boolean"},"tags":{"description":"Tags for the line item, e.g. 'category:home-apparel', or 'customergroup:vip'","items":{"type":"string"},"title":"Tags","type":"array"},"bundle":{"anyOf":[{"$ref":"#/components/schemas/BundleInfo"},{"type":"null"}],"default":null,"description":"Bundle relationship metadata when the item is part of a bundle.","title":"Bundle Info"},"additional_attributes":{"description":"Additional attributes for this line item","items":{"$ref":"#/components/schemas/AdditionalAttribute"},"title":"Additional Attributes","type":"array"}},"required":["line_item_id"],"title":"Line Item","type":"object"},"LineItemVersionEnum":{"enum":["v1","v2"],"title":"LineItemVersionEnum","type":"string"},"WeightUnitEnum":{"enum":["kg","g","lbs","oz"],"type":"string"},"BundleInfo":{"additionalProperties":true,"properties":{"group_id":{"description":"Bundle group identifier in the retailer's system.","title":"Bundle Group ID","type":"string"},"role":{"$ref":"#/components/schemas/BundleRoleEnum","description":"Whether this line item represents a bundle parent or a bundle component.","title":"Bundle Role"},"return_policy":{"$ref":"#/components/schemas/BundleReturnPolicyEnum","default":"components_only","description":"Which lines in this bundle group are selectable for return.","title":"Bundle Return Policy"},"parent_product_id":{"description":"Parent bundle product identifier in the retailer's system.","title":"Bundle Parent Product ID","type":"string"},"parent_variant_id":{"description":"Parent bundle variant identifier in the retailer's system.","title":"Bundle Parent Variant ID","type":"string"},"parent_sku":{"description":"Parent bundle SKU, if available.","title":"Bundle Parent SKU","type":"string"},"parent_title":{"description":"Display title for the bundle parent, if available.","title":"Bundle Parent Title","type":"string"},"parent_quantity":{"description":"Quantity of the bundle parent purchased in the order.","title":"Bundle Parent Quantity","type":"integer"},"component_quantity_per_parent":{"description":"Component quantity per single bundle parent (if determinable).","title":"Bundle Component Quantity Per Parent","type":"integer"},"allocation_method":{"$ref":"#/components/schemas/BundleAllocationMethodEnum","default":"none","description":"How pricing was allocated to bundle components.","title":"Bundle Allocation Method"},"allocated_unit_price":{"description":"Snapshot of allocated component unit price (if derived from bundle totals).","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Allocated Unit Price","type":"string"},"allocated_amount_invoiced":{"description":"Snapshot of allocated component invoiced amount (if derived from bundle totals).","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Allocated Amount Invoiced","type":"string"}},"required":["group_id","role"],"title":"Bundle Info","type":"object"},"BundleRoleEnum":{"enum":["parent","component"],"title":"BundleRoleEnum","type":"string"},"BundleReturnPolicyEnum":{"enum":["parent_only","components_only","parent_and_components"],"title":"BundleReturnPolicyEnum","type":"string"},"BundleAllocationMethodEnum":{"enum":["none","component_price","msrp_ratio","equal"],"title":"BundleAllocationMethodEnum","type":"string"},"AdditionalAttribute":{"properties":{"key":{"description":"The key of the additional attribute","title":"Key","type":"string"},"value":{"default":null,"description":"The value of the additional attribute","title":"Value"}},"required":["key"],"title":"AdditionalAttribute","type":"object"},"LineItemReturn":{"additionalProperties":true,"properties":{"version":{"$ref":"#/components/schemas/LineItemVersionEnum","description":"Optional. Omit this key unless absolutely intended. The standard value is `v2`. If you send `version`, send `v2`.","title":"Version"},"line_item_id":{"description":"Retailer ID of the line item, only the last number part of the whole line item id string","title":"Line Item ID","type":"string"},"product_id":{"description":"Parent product identifier in the retailer's system (shared across variants).","title":"Product ID","type":"string"},"variant_id":{"description":"SKU/variant identifier; prefer for matching when available since parent product IDs are reused across variants.","title":"Variant ID","type":"string"},"sku":{"description":"Stock Keeping Unit of the line item","title":"SKU","type":"string"},"barcode":{"description":"Barcode associated with the line item variant or product","title":"Barcode","type":"string"},"order_item_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Line Item ID in the order, the whole id of the fulfillment line item","title":"Order Line Item ID"},"article_name":{"description":"Name of the article","title":"Article Name","type":"string"},"article_category":{"description":"Category of the article","title":"Article Category","type":"string"},"article_store_url":{"description":"URL to the article in the store","title":"Article Store URL","type":"string"},"article_image_url":{"description":"URL to the image of the article","title":"Article Image URL","type":"string"},"article_brand":{"description":"Brand of the article (reference only)","title":"Article Brand","type":"string"},"size":{"description":"Size of the article (reference only)","title":"Size","type":"string"},"color":{"description":"Color of the article (reference only)","title":"Color","type":"string"},"width":{"description":"Width of the article (in millimeters)","title":"Width","type":"number"},"height":{"description":"Height of the article (in millimeters)","title":"Height","type":"number"},"length":{"description":"Length of the article (in millimeters)","title":"Length","type":"number"},"length_unit":{"const":"cm","default":"cm","title":"Length Unit","type":"string"},"weight":{"description":"Weight of the article (in grams, kg, lbs, or oz)","title":"Weight","type":"number"},"weight_unit":{"allOf":[{"$ref":"#/components/schemas/WeightUnitEnum"}],"default":"g","title":"Weight Unit"},"unit_price":{"description":"Paid unit price of the article (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Unit Price","type":"string"},"unit_price_original":{"description":"Original unit price of the article (pre-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Unit Price","type":"string"},"quantity":{"description":"Unit quantity of the article","title":"Unit Quantity","type":"integer"},"amount_invoiced":{"description":"Paid line total amount for this line item (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Invoiced","type":"string"},"tax_amount":{"description":"Total tax amount for this line item (regardless of taxesIncluded)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Tax Amount","type":"string"},"harmonized_system_code":{"description":"HS/HTS code for customs classification","title":"Harmonized System Code","type":"string"},"origin_country_iso3":{"description":"ISO 3166-1 alpha-3 code of articles country of origin, might be required based on shipment regulations","pattern":"^\\w{3}$","title":"Origin Country ISO3","type":"string"},"is_bulky":{"default":false,"description":"If the article is bulky","title":"Is Bulky","type":"boolean"},"tags":{"description":"Tags for the line item, e.g. 'category:home-apparel', or 'customergroup:vip'","items":{"type":"string"},"title":"Tags","type":"array"},"bundle":{"anyOf":[{"$ref":"#/components/schemas/BundleInfo"},{"type":"null"}],"default":null,"description":"Bundle relationship metadata when the item is part of a bundle.","title":"Bundle Info"},"additional_attributes":{"description":"Additional attributes for this line item","items":{"$ref":"#/components/schemas/AdditionalAttribute"},"title":"Additional Attributes","type":"array"},"unit_price_msrp_current":{"anyOf":[{"pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","type":"string"},{"type":"null"}],"default":null,"description":"Current catalog/MSRP unit price for the same variant.","title":"Current MSRP"},"reference_date_for_return":{"description":"The date, which is used to evaluate the line item return period","format":"date","title":"Reference Date for Return","type":"string"},"reference_date_type":{"allOf":[{"$ref":"#/components/schemas/ReferenceDateTypeEnum"}],"description":"The date type, which is used to evaluate the line item return period","title":"Reference Date Type"},"fulfillment":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Id of the fulfillment that this item belongs to","title":"Fulfillment"},"quantity_returned":{"description":"Quantity of already returned items in this line.","title":"Quantity Returned","type":"integer"},"delivered_date":{"description":"Date when the line item was delivered (same as the fulfillment delivered date)","format":"date","title":"Delivered Date","type":"string"},"return_reason":{"description":"Full return reason path (as configured in the respective return configuration for this object)","title":"Return Reason","type":"string"},"return_reason_pretty":{"description":"Pretty text for the return reason, e.g. 'Doesn't Fit'","title":"Return Reason Pretty","type":"string"},"return_quantity":{"description":"Quantity to be returned","title":"Return Quantity","type":"integer"},"problem_description":{"description":"Description of the problem with this line item","title":"Problem Description","type":"string"},"condition":{"description":"Article condition, if provided","title":"Condition","type":"string"},"article_images":{"items":{"$ref":"#/components/schemas/ReturnImage"},"title":"Article Images","type":"array"},"compensation_method":{"description":"Compensation method for this line item, e.g. exchange, refund, credit","title":"Compensation Method","type":"string"},"accepted_quantity":{"description":"Quantity of the article that was accepted by warehouse","title":"Accepted Quantity","type":"integer"},"rejected_quantity":{"description":"Quantity of the article that was rejected by warehouse","title":"Rejected Quantity","type":"integer"},"status_reason":{"description":"Reason for the rejection / acceptance of the article","title":"Rejection or Acceptance Reason","type":"string"},"status_reason_code":{"description":"Structured reason code, e.g. quality_issue","title":"Status Reason Code","type":"string"},"return_reason_code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Final code of return reason (leaf code)","readOnly":true,"title":"Return Reason Code"}},"required":["line_item_id","return_reason_code"],"title":"Line Item","type":"object"},"ReferenceDateTypeEnum":{"enum":["order_date","shipping_date","delivery_date"],"type":"string"},"ReturnImage":{"properties":{"url":{"title":"Url","type":"string"},"name":{"title":"Name","type":"string"},"mime_type":{"title":"Mime Type","type":"string"}},"required":["url","name","mime_type"],"title":"ReturnImage","type":"object"},"ReturnLabel":{"properties":{"courier":{"description":"Return label courier code or drop-off code, e.g. barcode","title":"Return Label Courier","type":"string"},"service_level":{"description":"Service level of the return label","title":"Service Level","type":"string"},"tracking_number":{"description":"Tracking number of the return label (or in case of Barcode the barcode)","title":"Tracking number","type":"string"},"type":{"$ref":"#/components/schemas/ReturnLabelTypeEnum","default":"shipping","description":"Type of the return label, e.g. 'shipping' for a real courier label, or barcode for a (custom) drop-off code","title":"Label Type"},"flags":{"description":"Flags (extra markers) for the return label, such as 'has_dangerous_goods', or 'is_pickup'","items":{"$ref":"#/components/schemas/ReturnLabelFlagsEnum"},"title":"Label Flags","type":"array"},"documents":{"description":"Documents related to this return label (e.g. print label, barcode, packing slip, wallet-passes)","items":{"$ref":"#/components/schemas/Document"},"title":"Label","type":"array"},"locations_url":{"description":"URL to a courier-specific location finder page.","title":"Locations URL","type":"string"},"destination_id":{"description":"Destination ID for the return label, e.g. warehouse code","title":"Destination ID","type":"string"},"line_item_ids":{"description":"The line item IDs to which the label should be attached","items":{"type":"string"},"title":"Line Item IDs","type":"array"},"is_free_label":{"default":false,"description":"Indicates if the return label is free of charge","title":"Is Free Label","type":"boolean"},"label_cost_amount":{"default":"0.0","description":"Cost of the return label","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Label Cost Amount","type":"string"},"tracking_id":{"description":"Tracking ID of the shipment in the parcelLab system","title":"ParcelLab Tracking ID","type":"string"},"external_reference":{"description":"Unique retailer-provided reference of the shipment, either this tracking number is required","title":"External Reference","type":"string"},"delivery_status":{"$ref":"#/components/schemas/TrackingStageChoices","default":"Pending","description":"Current shipping stage of the return label","title":"Current Shipping Stage"},"pickup_date":{"description":"Scheduled pickup date for the return label. Nullable if not a pickup return.","format":"date","title":"Pickup Date","type":"string"},"earliest_pickup_time":{"description":"Earliest scheduled pickup time for the return label. Nullable if not a pickup return.","format":"time","title":"Earliest Pickup Time","type":"string"},"latest_pickup_time":{"description":"Latest scheduled pickup time for the return label. Nullable if not a pickup return.","format":"time","title":"Latest Pickup Time","type":"string"},"pickup_confirmation_code":{"description":"Confirmation code customer must present on pickup","title":"Pickup Confirmation Code","type":"string"},"is_pickup":{"default":false,"description":"Indicates if the return is a pickup order.","title":"Is Pickup","type":"boolean"},"configuration_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Selected return option mapping ID used to create this label.","title":"Courier Mapping ID"}},"required":["courier","tracking_number"],"title":"Return Label","type":"object"},"ReturnLabelTypeEnum":{"enum":["shipping","custom"],"title":"ReturnLabelTypeEnum","type":"string"},"ReturnLabelFlagsEnum":{"enum":["is_cancellable","is_pickup","has_dangerous_goods"],"type":"string"},"Document":{"properties":{"url":{"description":"URL to the document, in most cases this is a http URL, but it could also be a data URL (base64)","title":"Document URL","type":"string"},"content_type":{"default":"application/pdf","description":"MIME content type of the document, e.g. 'application/pdf'","title":"Content Type","type":"string"},"type":{"default":[],"description":"Type or types of the document, maybe multiple, if bundled","items":{"$ref":"#/components/schemas/DocumentTypeEnum"},"title":"Document Type","type":"array"},"expires_at":{"description":"Expiry date of the document, after which it might not be retrievable","format":"date-time","title":"Document expiry date","type":"string"}},"required":["url"],"title":"Document","type":"object"},"DocumentTypeEnum":{"enum":["label","packing_slip","barcode","customs_document","wallet_pass_io","wallet_pass_android","commercial_invoice"],"type":"string"},"TrackingStageChoices":{"enum":["Pending","Transit","Customs","LastMile","ReadyToCollect","Delivered","SentBack","Returned","Failed","Cancelled"],"title":"TrackingStageChoices","type":"string"},"AddLabelMutation":{"properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"add_label","default":"add_label","title":"Type","type":"string"},"request":{"$ref":"#/components/schemas/AddLabelRequest","description":"The labels to be added to this return registration","title":"Label Requests"}},"required":["request"],"title":"AddLabelMutation","type":"object"},"MutationResult":{"description":"The result of a mutation","properties":{"success":{"default":false,"description":"Whether the mutation was successful","title":"Success","type":"boolean"},"message":{"default":"","description":"A message describing the result of the mutation","title":"Message","type":"string"},"errors":{"additionalProperties":{"type":"string"},"description":"A dictionary of errors that occurred during the mutation","title":"Errors","type":"object"},"warnings":{"description":"Non-fatal warnings raised while processing the mutation","items":{"type":"string"},"title":"Warnings","type":"array"}},"title":"MutationResult","type":"object"},"AddLabelRequest":{"description":"Adds a label to a return registration","properties":{"type":{"$ref":"#/components/schemas/ReturnLabelTypeEnum"},"courier":{"description":"The courier for which a label should be created","title":"Courier","type":"string"},"tracking_number":{"description":"Only for custom label: custom tracking number for the label","title":"Tracking Number","type":"string"},"service_level":{"description":"The service level for the label","title":"Service Level","type":"string"},"destination_id":{"description":"The warehouse or other identifier, to which the courier should ship, corresponds to a warehouse code","title":"Identifier / Warehouse","type":"string"},"destination_address":{"$ref":"#/components/schemas/AddressSchema","description":"Defines a destination address for this label, has precedence over default destination addresses setup in courier configuration. If the courier does not support a custom destination address & the destination address object is present, will raise an error ","title":"Destination Address"},"template_id":{"description":"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.","title":"Template ID","type":"string"},"flags":{"description":"A list of special flags that apply to the label or shipment","items":{"$ref":"#/components/schemas/AddLabelFlagsEnum"},"title":"Flags","type":"array"},"label_types":{"description":"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).","items":{"$ref":"#/components/schemas/LabelTypesEnum"},"title":"Label Types","type":"array"},"line_item_ids":{"description":"The line item IDs to which the label should be attached","items":{"type":"string"},"title":"Line Item IDs","type":"array"},"additional_fields":{"additionalProperties":true,"description":"Custom fields to pass through to label generation and returns document.","title":"Additional Fields","type":"object"}},"required":["type","courier"],"title":"AddLabelRequest","type":"object"},"AddressSchema":{"properties":{"first_name":{"title":"First Name","type":"string"},"last_name":{"title":"Last Name","type":"string"},"company_name":{"title":"Company Name, if any","type":"string"},"address_line":{"description":"Address line, e.g. street and house number, or PO Box","maxLength":256,"minLength":1,"title":"Address Line","type":"string"},"address_line_extra":{"description":"Additional address line, e.g. apartment number or company name","title":"Additional Address Line","type":"string"},"postal_code":{"maxLength":10,"minLength":2,"title":"Postal Code","type":"string"},"city":{"description":"City name (min-length of 1 due to logographic languages)","maxLength":40,"minLength":1,"title":"City","type":"string"},"country_iso3":{"description":"ISO 3166-1 alpha-3 code of country","pattern":"^\\w{3}$","title":"Country ISO3","type":"string"},"region_code":{"description":"Region code, e.g. state or province code (ISO 3166-2), if available","maxLength":25,"minLength":1,"title":"Region Code","type":"string"},"phone":{"description":"Phone number related to this address, if any","maxLength":30,"title":"Phone","type":"string"}},"required":["address_line","postal_code","city","country_iso3"],"title":"Address","type":"object"},"AddLabelFlagsEnum":{"enum":["has_dangerous_goods","is_pickup"],"type":"string"},"LabelTypesEnum":{"enum":["code","print"],"type":"string"},"UpdateItemMutation":{"description":"Update registered article items","properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"update_items","default":"update_items","title":"Type","type":"string"},"items":{"description":"Items for this return registration after update is a applied","items":{"$ref":"#/components/schemas/LineItemReturn"},"title":"Line Items to return","type":"array"}},"title":"Update Items Mutation","type":"object"},"CloseReturnMutation":{"description":"Close a return registration (finalize return + refund).","properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"close_return","default":"close_return","title":"Type","type":"string"},"status_reason":{"description":"Optional reason for closing the return registration.","title":"Status Reason","type":"string"},"trigger_refund":{"description":"Whether to issue a monetary refund when closing the return.","title":"Trigger Refund","type":"boolean"},"release_exchange_items":{"description":"Whether to release exchange items when closing the return.","title":"Release Exchange Items","type":"boolean"},"refund_shipping_fees":{"description":"Whether to refund the original order shipping cost.","title":"Refund Shipping Fees","type":"boolean"},"tracking_number":{"description":"Optional tracking number used for receive-status synchronization when article status updates are provided.","title":"Tracking Number","type":"string"},"received_by":{"description":"Optional source shown in receive status when article status updates are provided. Defaults to API (close_return mutation).","title":"Received By","type":"string"},"receive_note":{"description":"Optional receive note stored with receive status and synchronized to tracking returnReceive.note when article status updates are provided.","title":"Receive Note","type":"string"},"article_status_updates":{"description":"Optional receive-style article status updates to apply before closing the return registration.","items":{"$ref":"#/components/schemas/ArticleStatusUpdate"},"title":"Article Status Updates","type":"array"}},"title":"CloseReturnMutation","type":"object"},"ArticleStatusUpdate":{"properties":{"identifier":{"description":"Identifier of the article to update the status for","title":"Identifier of article","type":"string"},"identifier_type":{"$ref":"#/components/schemas/ArticleIdentifierType","description":"The type of the identifier","title":"Identifier Type"},"accepted_quantity":{"default":0,"description":"The quantity of the article that was accepted","title":"Accepted Quantity","type":"integer"},"rejected_quantity":{"default":0,"description":"The quantity of the article that was rejected","title":"Rejected Quantity","type":"integer"},"reason":{"default":null,"description":"The reason for the rejection of the article","title":"Reason","type":"string"}},"required":["identifier","identifier_type"],"title":"ArticleStatusUpdate","type":"object"},"ArticleIdentifierType":{"enum":["product_id","line_item_id","sku","variant_id","barcode","order_item_id"],"title":"ArticleIdentifierType","type":"string"},"CancelReturnMutation":{"description":"Cancel a return registration and its tracking.","properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"cancel_return","default":"cancel_return","title":"Type","type":"string"},"status_reason":{"description":"Optional reason for cancelling the return registration.","title":"Status Reason","type":"string"}},"title":"CancelReturnMutation","type":"object"},"Error400Response":{"type":"object","properties":{"type":{"type":"string"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/GenericErrorItem"}}},"required":["errors","type"]},"GenericErrorItem":{"type":"object","properties":{"code":{"type":"string"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["code","detail"]},"ErrorResponse404":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ClientErrorEnum"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error404"}}},"required":["errors","type"]},"ClientErrorEnum":{"enum":["client_error"],"type":"string","description":"* `client_error` - Client Error"},"Error404":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode404Enum"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["attr","code","detail"]},"ErrorCode404Enum":{"enum":["not_found"],"type":"string","description":"* `not_found` - Not Found"},"ErrorResponse429":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ClientErrorEnum"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error429"}}},"required":["errors","type"]},"Error429":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode429Enum"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["attr","code","detail"]},"ErrorCode429Enum":{"enum":["throttled"],"type":"string","description":"* `throttled` - Throttled"}}},"paths":{"/v4/returns/return-registrations/lookup-order/":{"post":{"operationId":"returns_return_registrations_lookup_order_create","description":"Return Registrations represent a return request from a customer. There might be multiple\nreturn registrations for a single order. There might also be multiple labels for one return\nregistration, if requested by the customer.\n\n A return registration is linked to a configuration bundle (field 'code'), multiple configurations\n might be available on one account (e.g. country-specific courier configurations).\n\n Return registrations are created by the parcelLab return portal, or by the retailer via the parcelLab API.\n\nCertain fields of the return registration are not mutable via requests on the registration resource, but require\n'action' payloads to be submitted (e.g. 'AddLabel') to the 'mutate' action.","summary":"Create Return Registration (from order)","tags":["Return Registration"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRegistrationFromOrderRequest"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/CreateRegistrationFromOrderRequest"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/CreateRegistrationFromOrderRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnRegistration"}}},"description":""},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}},"description":""},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"description":""},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse429"}}},"description":""}}}}}} ``` ## Update a Return Registration You can update a specific return registration using the `v4/returns/return-registrations/{external_id}` endpoint. ## Update Return Registration > 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. ```json {"openapi":"3.1.0","info":{"title":"parcelLab API","version":"v4"},"security":[{"OAuth2 Authentication":[]},{"HeaderToken":[]}],"components":{"securitySchemes":{"OAuth2 Authentication":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"HeaderToken":{"type":"http","scheme":"bearer","bearerFormat":"Parcellab-API-Token base64(account_id:token)","description":"Send `Authorization: Parcellab-API-Token `.\n\n`` = `base64(account_id:token)` as provided in the portal."}},"schemas":{"ReturnRegistrationRequest":{"type":"object","description":"Represents a return registration","properties":{"account":{"type":"integer","description":"Account, that is linked to this registration."},"code":{"type":"string","minLength":1,"title":"Configuration Code","description":"Configuration code of the return configuration","maxLength":255},"version":{"type":["string","null"]},"reference":{"type":"string","minLength":1,"title":"Reference / Order Number","description":"Retailer reference, e.g. the order number, not unique","maxLength":255},"external_id":{"type":"string","format":"uuid","title":"External Identifier","description":"Unique identifier for this return registration, generated by parcelLab"},"external_reference":{"type":"string","description":"Additional identifier (e.g. shop system id) for this return registration, generated by the retailer","maxLength":255},"status":{"$ref":"#/components/schemas/ReturnRegistrationStatusEnum"},"status_reason":{"type":"string","description":"Reason for the current status","maxLength":255},"original_courier":{"type":"string","maxLength":255},"original_order_id":{"type":["string","null"],"maxLength":255},"order_date":{"type":["string","null"],"format":"date-time","description":"Date of the order"},"order_currency":{"type":"string","description":"Currency of the order, e.g. USD, EUR (ISO 4217)","maxLength":3},"order_total_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Total amount of the original order"},"order_shipping_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Total shipping amount of the original order"},"order_tax_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Total tax amount of the original order"},"order_delivery_date":{"type":["string","null"],"format":"date-time","description":"Date of the order delivery"},"order_shipping_date":{"type":["string","null"],"format":"date-time","description":"Date of the order shipment"},"order_payment_method":{"type":"array","items":{"type":"string","minLength":1,"maxLength":255},"description":"Payment method used for the order, as setup as reference items in the accounts configuration"},"language_iso2":{"type":"string","description":"ISO 639-1 language code of the recipient, if known, required for localized communication","maxLength":3},"customer_email":{"anyOf":[{"format":"email","type":"string"},{"const":"_unset","enum":["_unset"],"type":"string"}],"minLength":1,"description":"Customers email address, must be provided, in case email is not known or should be unset, use the literal string '_unset' instead."},"customer_phone":{"type":"string","description":"Customer phone number","maxLength":255},"customer_salutation":{"type":"string","maxLength":255},"customer_first_name":{"type":"string","maxLength":255},"customer_last_name":{"type":"string","maxLength":255},"customer_country_iso3":{"type":"string","description":"ISO 3166-1 alpha-3 code of country","maxLength":3},"customer_address":{"anyOf":[{"$ref":"#/components/schemas/ValidatedAddressSchema"},{"$ref":"#/components/schemas/Empty"}]},"articles_order":{"items":{"$ref":"#/components/schemas/LineItem"},"type":"array"},"articles_return":{"items":{"$ref":"#/components/schemas/LineItemReturn"},"type":"array"},"refund_method":{"type":"string","description":"Refund method selected by customer","maxLength":255},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":255},"description":"Order level tags."},"additional_fields":{"type":"object","additionalProperties":{},"description":"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":{"type":"string","description":"Verification code (e.g. zip/email) used for this return registration","maxLength":255},"mutations":{"items":{"anyOf":[{"$ref":"#/components/schemas/AddLabelMutation"},{"$ref":"#/components/schemas/UpdateItemMutation"},{"$ref":"#/components/schemas/CloseReturnMutation"},{"$ref":"#/components/schemas/CancelReturnMutation"}],"title":"Mutations"},"type":"array"}},"required":["account","code","customer_address","customer_email","reference"]},"ReturnRegistrationStatusEnum":{"enum":["created","submitted","pending_approval","pending_label","approved","rejected","cancelled","closed","processing_failed","invalid"],"type":"string","description":"* `created` - Created\n* `submitted` - Submitted\n* `pending_approval` - Pending Approval\n* `pending_label` - Pending Label\n* `approved` - Approved\n* `rejected` - Rejected\n* `cancelled` - Cancelled\n* `closed` - Closed\n* `processing_failed` - Processing Failed\n* `invalid` - Invalid"},"ValidatedAddressSchema":{"properties":{"first_name":{"title":"First Name","type":"string"},"last_name":{"title":"Last Name","type":"string"},"company_name":{"title":"Company Name, if any","type":"string"},"address_line":{"description":"Address line, e.g. street and house number, or PO Box","maxLength":256,"minLength":1,"title":"Address Line","type":"string"},"address_line_extra":{"description":"Additional address line, e.g. apartment number or company name","title":"Additional Address Line","type":"string"},"postal_code":{"maxLength":10,"minLength":2,"title":"Postal Code","type":"string"},"city":{"description":"City name (min-length of 1 due to logographic languages)","maxLength":40,"minLength":1,"title":"City","type":"string"},"country_iso3":{"description":"ISO 3166-1 alpha-3 code of country","pattern":"^\\w{3}$","title":"Country ISO3","type":"string"},"region_code":{"description":"Region code, e.g. state or province code (ISO 3166-2), if available","maxLength":25,"minLength":1,"title":"Region Code","type":"string"},"phone":{"description":"Phone number related to this address, if any","maxLength":30,"title":"Phone","type":"string"}},"required":["address_line","postal_code","city","country_iso3"],"title":"Address","type":"object"},"Empty":{"additionalProperties":false,"properties":{},"title":"Empty","type":"object"},"LineItem":{"additionalProperties":true,"properties":{"version":{"$ref":"#/components/schemas/LineItemVersionEnum","description":"Optional. Omit this key unless absolutely intended. The standard value is `v2`. If you send `version`, send `v2`.","title":"Version"},"line_item_id":{"description":"Retailer ID of the line item","title":"Line Item ID","type":"string"},"product_id":{"description":"Parent product identifier in the retailer's system (shared across variants).","title":"Product ID","type":"string"},"variant_id":{"description":"SKU/variant identifier; prefer for matching when available since parent product IDs are reused across variants.","title":"Variant ID","type":"string"},"sku":{"description":"Stock Keeping Unit of the line item","title":"SKU","type":"string"},"barcode":{"description":"Barcode associated with the line item variant or product","title":"Barcode","type":"string"},"order_item_id":{"description":"Line Item ID in the order (preferred when provided)","title":"Order Line Item ID","type":"string"},"article_name":{"description":"Name of the article","title":"Article Name","type":"string"},"article_category":{"description":"Category of the article","title":"Article Category","type":"string"},"article_store_url":{"description":"URL to the article in the store","title":"Article Store URL","type":"string"},"article_image_url":{"description":"URL to the image of the article","title":"Article Image URL","type":"string"},"article_brand":{"description":"Brand of the article (reference only)","title":"Article Brand","type":"string"},"size":{"description":"Size of the article (reference only)","title":"Size","type":"string"},"color":{"description":"Color of the article (reference only)","title":"Color","type":"string"},"width":{"description":"Width of the article (in millimeters)","title":"Width","type":"number"},"height":{"description":"Height of the article (in millimeters)","title":"Height","type":"number"},"length":{"description":"Length of the article (in millimeters)","title":"Length","type":"number"},"length_unit":{"const":"cm","default":"cm","title":"Length Unit","type":"string"},"weight":{"description":"Weight of the article (in grams, kg, lbs, or oz)","title":"Weight","type":"number"},"weight_unit":{"allOf":[{"$ref":"#/components/schemas/WeightUnitEnum"}],"default":"g","title":"Weight Unit"},"unit_price":{"description":"Paid unit price of the article (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Unit Price","type":"string"},"unit_price_original":{"description":"Original unit price of the article (pre-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Unit Price","type":"string"},"quantity":{"description":"Unit quantity of the article","title":"Unit Quantity","type":"integer"},"amount_invoiced":{"description":"Paid line total amount for this line item (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Invoiced","type":"string"},"tax_amount":{"description":"Total tax amount for this line item (regardless of taxesIncluded)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Tax Amount","type":"string"},"harmonized_system_code":{"description":"HS/HTS code for customs classification","title":"Harmonized System Code","type":"string"},"origin_country_iso3":{"description":"ISO 3166-1 alpha-3 code of articles country of origin, might be required based on shipment regulations","pattern":"^\\w{3}$","title":"Origin Country ISO3","type":"string"},"is_bulky":{"default":false,"description":"If the article is bulky","title":"Is Bulky","type":"boolean"},"tags":{"description":"Tags for the line item, e.g. 'category:home-apparel', or 'customergroup:vip'","items":{"type":"string"},"title":"Tags","type":"array"},"bundle":{"anyOf":[{"$ref":"#/components/schemas/BundleInfo"},{"type":"null"}],"default":null,"description":"Bundle relationship metadata when the item is part of a bundle.","title":"Bundle Info"},"additional_attributes":{"description":"Additional attributes for this line item","items":{"$ref":"#/components/schemas/AdditionalAttribute"},"title":"Additional Attributes","type":"array"}},"required":["line_item_id"],"title":"Line Item","type":"object"},"LineItemVersionEnum":{"enum":["v1","v2"],"title":"LineItemVersionEnum","type":"string"},"WeightUnitEnum":{"enum":["kg","g","lbs","oz"],"type":"string"},"BundleInfo":{"additionalProperties":true,"properties":{"group_id":{"description":"Bundle group identifier in the retailer's system.","title":"Bundle Group ID","type":"string"},"role":{"$ref":"#/components/schemas/BundleRoleEnum","description":"Whether this line item represents a bundle parent or a bundle component.","title":"Bundle Role"},"return_policy":{"$ref":"#/components/schemas/BundleReturnPolicyEnum","default":"components_only","description":"Which lines in this bundle group are selectable for return.","title":"Bundle Return Policy"},"parent_product_id":{"description":"Parent bundle product identifier in the retailer's system.","title":"Bundle Parent Product ID","type":"string"},"parent_variant_id":{"description":"Parent bundle variant identifier in the retailer's system.","title":"Bundle Parent Variant ID","type":"string"},"parent_sku":{"description":"Parent bundle SKU, if available.","title":"Bundle Parent SKU","type":"string"},"parent_title":{"description":"Display title for the bundle parent, if available.","title":"Bundle Parent Title","type":"string"},"parent_quantity":{"description":"Quantity of the bundle parent purchased in the order.","title":"Bundle Parent Quantity","type":"integer"},"component_quantity_per_parent":{"description":"Component quantity per single bundle parent (if determinable).","title":"Bundle Component Quantity Per Parent","type":"integer"},"allocation_method":{"$ref":"#/components/schemas/BundleAllocationMethodEnum","default":"none","description":"How pricing was allocated to bundle components.","title":"Bundle Allocation Method"},"allocated_unit_price":{"description":"Snapshot of allocated component unit price (if derived from bundle totals).","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Allocated Unit Price","type":"string"},"allocated_amount_invoiced":{"description":"Snapshot of allocated component invoiced amount (if derived from bundle totals).","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Allocated Amount Invoiced","type":"string"}},"required":["group_id","role"],"title":"Bundle Info","type":"object"},"BundleRoleEnum":{"enum":["parent","component"],"title":"BundleRoleEnum","type":"string"},"BundleReturnPolicyEnum":{"enum":["parent_only","components_only","parent_and_components"],"title":"BundleReturnPolicyEnum","type":"string"},"BundleAllocationMethodEnum":{"enum":["none","component_price","msrp_ratio","equal"],"title":"BundleAllocationMethodEnum","type":"string"},"AdditionalAttribute":{"properties":{"key":{"description":"The key of the additional attribute","title":"Key","type":"string"},"value":{"default":null,"description":"The value of the additional attribute","title":"Value"}},"required":["key"],"title":"AdditionalAttribute","type":"object"},"LineItemReturn":{"additionalProperties":true,"properties":{"version":{"$ref":"#/components/schemas/LineItemVersionEnum","description":"Optional. Omit this key unless absolutely intended. The standard value is `v2`. If you send `version`, send `v2`.","title":"Version"},"line_item_id":{"description":"Retailer ID of the line item, only the last number part of the whole line item id string","title":"Line Item ID","type":"string"},"product_id":{"description":"Parent product identifier in the retailer's system (shared across variants).","title":"Product ID","type":"string"},"variant_id":{"description":"SKU/variant identifier; prefer for matching when available since parent product IDs are reused across variants.","title":"Variant ID","type":"string"},"sku":{"description":"Stock Keeping Unit of the line item","title":"SKU","type":"string"},"barcode":{"description":"Barcode associated with the line item variant or product","title":"Barcode","type":"string"},"order_item_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Line Item ID in the order, the whole id of the fulfillment line item","title":"Order Line Item ID"},"article_name":{"description":"Name of the article","title":"Article Name","type":"string"},"article_category":{"description":"Category of the article","title":"Article Category","type":"string"},"article_store_url":{"description":"URL to the article in the store","title":"Article Store URL","type":"string"},"article_image_url":{"description":"URL to the image of the article","title":"Article Image URL","type":"string"},"article_brand":{"description":"Brand of the article (reference only)","title":"Article Brand","type":"string"},"size":{"description":"Size of the article (reference only)","title":"Size","type":"string"},"color":{"description":"Color of the article (reference only)","title":"Color","type":"string"},"width":{"description":"Width of the article (in millimeters)","title":"Width","type":"number"},"height":{"description":"Height of the article (in millimeters)","title":"Height","type":"number"},"length":{"description":"Length of the article (in millimeters)","title":"Length","type":"number"},"length_unit":{"const":"cm","default":"cm","title":"Length Unit","type":"string"},"weight":{"description":"Weight of the article (in grams, kg, lbs, or oz)","title":"Weight","type":"number"},"weight_unit":{"allOf":[{"$ref":"#/components/schemas/WeightUnitEnum"}],"default":"g","title":"Weight Unit"},"unit_price":{"description":"Paid unit price of the article (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Unit Price","type":"string"},"unit_price_original":{"description":"Original unit price of the article (pre-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Unit Price","type":"string"},"quantity":{"description":"Unit quantity of the article","title":"Unit Quantity","type":"integer"},"amount_invoiced":{"description":"Paid line total amount for this line item (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Invoiced","type":"string"},"tax_amount":{"description":"Total tax amount for this line item (regardless of taxesIncluded)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Tax Amount","type":"string"},"harmonized_system_code":{"description":"HS/HTS code for customs classification","title":"Harmonized System Code","type":"string"},"origin_country_iso3":{"description":"ISO 3166-1 alpha-3 code of articles country of origin, might be required based on shipment regulations","pattern":"^\\w{3}$","title":"Origin Country ISO3","type":"string"},"is_bulky":{"default":false,"description":"If the article is bulky","title":"Is Bulky","type":"boolean"},"tags":{"description":"Tags for the line item, e.g. 'category:home-apparel', or 'customergroup:vip'","items":{"type":"string"},"title":"Tags","type":"array"},"bundle":{"anyOf":[{"$ref":"#/components/schemas/BundleInfo"},{"type":"null"}],"default":null,"description":"Bundle relationship metadata when the item is part of a bundle.","title":"Bundle Info"},"additional_attributes":{"description":"Additional attributes for this line item","items":{"$ref":"#/components/schemas/AdditionalAttribute"},"title":"Additional Attributes","type":"array"},"unit_price_msrp_current":{"anyOf":[{"pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","type":"string"},{"type":"null"}],"default":null,"description":"Current catalog/MSRP unit price for the same variant.","title":"Current MSRP"},"reference_date_for_return":{"description":"The date, which is used to evaluate the line item return period","format":"date","title":"Reference Date for Return","type":"string"},"reference_date_type":{"allOf":[{"$ref":"#/components/schemas/ReferenceDateTypeEnum"}],"description":"The date type, which is used to evaluate the line item return period","title":"Reference Date Type"},"fulfillment":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Id of the fulfillment that this item belongs to","title":"Fulfillment"},"quantity_returned":{"description":"Quantity of already returned items in this line.","title":"Quantity Returned","type":"integer"},"delivered_date":{"description":"Date when the line item was delivered (same as the fulfillment delivered date)","format":"date","title":"Delivered Date","type":"string"},"return_reason":{"description":"Full return reason path (as configured in the respective return configuration for this object)","title":"Return Reason","type":"string"},"return_reason_pretty":{"description":"Pretty text for the return reason, e.g. 'Doesn't Fit'","title":"Return Reason Pretty","type":"string"},"return_quantity":{"description":"Quantity to be returned","title":"Return Quantity","type":"integer"},"problem_description":{"description":"Description of the problem with this line item","title":"Problem Description","type":"string"},"condition":{"description":"Article condition, if provided","title":"Condition","type":"string"},"article_images":{"items":{"$ref":"#/components/schemas/ReturnImage"},"title":"Article Images","type":"array"},"compensation_method":{"description":"Compensation method for this line item, e.g. exchange, refund, credit","title":"Compensation Method","type":"string"},"accepted_quantity":{"description":"Quantity of the article that was accepted by warehouse","title":"Accepted Quantity","type":"integer"},"rejected_quantity":{"description":"Quantity of the article that was rejected by warehouse","title":"Rejected Quantity","type":"integer"},"status_reason":{"description":"Reason for the rejection / acceptance of the article","title":"Rejection or Acceptance Reason","type":"string"},"status_reason_code":{"description":"Structured reason code, e.g. quality_issue","title":"Status Reason Code","type":"string"},"return_reason_code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Final code of return reason (leaf code)","readOnly":true,"title":"Return Reason Code"}},"required":["line_item_id","return_reason_code"],"title":"Line Item","type":"object"},"ReferenceDateTypeEnum":{"enum":["order_date","shipping_date","delivery_date"],"type":"string"},"ReturnImage":{"properties":{"url":{"title":"Url","type":"string"},"name":{"title":"Name","type":"string"},"mime_type":{"title":"Mime Type","type":"string"}},"required":["url","name","mime_type"],"title":"ReturnImage","type":"object"},"AddLabelMutation":{"properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"add_label","default":"add_label","title":"Type","type":"string"},"request":{"$ref":"#/components/schemas/AddLabelRequest","description":"The labels to be added to this return registration","title":"Label Requests"}},"required":["request"],"title":"AddLabelMutation","type":"object"},"MutationResult":{"description":"The result of a mutation","properties":{"success":{"default":false,"description":"Whether the mutation was successful","title":"Success","type":"boolean"},"message":{"default":"","description":"A message describing the result of the mutation","title":"Message","type":"string"},"errors":{"additionalProperties":{"type":"string"},"description":"A dictionary of errors that occurred during the mutation","title":"Errors","type":"object"},"warnings":{"description":"Non-fatal warnings raised while processing the mutation","items":{"type":"string"},"title":"Warnings","type":"array"}},"title":"MutationResult","type":"object"},"AddLabelRequest":{"description":"Adds a label to a return registration","properties":{"type":{"$ref":"#/components/schemas/ReturnLabelTypeEnum"},"courier":{"description":"The courier for which a label should be created","title":"Courier","type":"string"},"tracking_number":{"description":"Only for custom label: custom tracking number for the label","title":"Tracking Number","type":"string"},"service_level":{"description":"The service level for the label","title":"Service Level","type":"string"},"destination_id":{"description":"The warehouse or other identifier, to which the courier should ship, corresponds to a warehouse code","title":"Identifier / Warehouse","type":"string"},"destination_address":{"$ref":"#/components/schemas/AddressSchema","description":"Defines a destination address for this label, has precedence over default destination addresses setup in courier configuration. If the courier does not support a custom destination address & the destination address object is present, will raise an error ","title":"Destination Address"},"template_id":{"description":"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.","title":"Template ID","type":"string"},"flags":{"description":"A list of special flags that apply to the label or shipment","items":{"$ref":"#/components/schemas/AddLabelFlagsEnum"},"title":"Flags","type":"array"},"label_types":{"description":"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).","items":{"$ref":"#/components/schemas/LabelTypesEnum"},"title":"Label Types","type":"array"},"line_item_ids":{"description":"The line item IDs to which the label should be attached","items":{"type":"string"},"title":"Line Item IDs","type":"array"},"additional_fields":{"additionalProperties":true,"description":"Custom fields to pass through to label generation and returns document.","title":"Additional Fields","type":"object"}},"required":["type","courier"],"title":"AddLabelRequest","type":"object"},"ReturnLabelTypeEnum":{"enum":["shipping","custom"],"title":"ReturnLabelTypeEnum","type":"string"},"AddressSchema":{"properties":{"first_name":{"title":"First Name","type":"string"},"last_name":{"title":"Last Name","type":"string"},"company_name":{"title":"Company Name, if any","type":"string"},"address_line":{"description":"Address line, e.g. street and house number, or PO Box","maxLength":256,"minLength":1,"title":"Address Line","type":"string"},"address_line_extra":{"description":"Additional address line, e.g. apartment number or company name","title":"Additional Address Line","type":"string"},"postal_code":{"maxLength":10,"minLength":2,"title":"Postal Code","type":"string"},"city":{"description":"City name (min-length of 1 due to logographic languages)","maxLength":40,"minLength":1,"title":"City","type":"string"},"country_iso3":{"description":"ISO 3166-1 alpha-3 code of country","pattern":"^\\w{3}$","title":"Country ISO3","type":"string"},"region_code":{"description":"Region code, e.g. state or province code (ISO 3166-2), if available","maxLength":25,"minLength":1,"title":"Region Code","type":"string"},"phone":{"description":"Phone number related to this address, if any","maxLength":30,"title":"Phone","type":"string"}},"required":["address_line","postal_code","city","country_iso3"],"title":"Address","type":"object"},"AddLabelFlagsEnum":{"enum":["has_dangerous_goods","is_pickup"],"type":"string"},"LabelTypesEnum":{"enum":["code","print"],"type":"string"},"UpdateItemMutation":{"description":"Update registered article items","properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"update_items","default":"update_items","title":"Type","type":"string"},"items":{"description":"Items for this return registration after update is a applied","items":{"$ref":"#/components/schemas/LineItemReturn"},"title":"Line Items to return","type":"array"}},"title":"Update Items Mutation","type":"object"},"CloseReturnMutation":{"description":"Close a return registration (finalize return + refund).","properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"close_return","default":"close_return","title":"Type","type":"string"},"status_reason":{"description":"Optional reason for closing the return registration.","title":"Status Reason","type":"string"},"trigger_refund":{"description":"Whether to issue a monetary refund when closing the return.","title":"Trigger Refund","type":"boolean"},"release_exchange_items":{"description":"Whether to release exchange items when closing the return.","title":"Release Exchange Items","type":"boolean"},"refund_shipping_fees":{"description":"Whether to refund the original order shipping cost.","title":"Refund Shipping Fees","type":"boolean"},"tracking_number":{"description":"Optional tracking number used for receive-status synchronization when article status updates are provided.","title":"Tracking Number","type":"string"},"received_by":{"description":"Optional source shown in receive status when article status updates are provided. Defaults to API (close_return mutation).","title":"Received By","type":"string"},"receive_note":{"description":"Optional receive note stored with receive status and synchronized to tracking returnReceive.note when article status updates are provided.","title":"Receive Note","type":"string"},"article_status_updates":{"description":"Optional receive-style article status updates to apply before closing the return registration.","items":{"$ref":"#/components/schemas/ArticleStatusUpdate"},"title":"Article Status Updates","type":"array"}},"title":"CloseReturnMutation","type":"object"},"ArticleStatusUpdate":{"properties":{"identifier":{"description":"Identifier of the article to update the status for","title":"Identifier of article","type":"string"},"identifier_type":{"$ref":"#/components/schemas/ArticleIdentifierType","description":"The type of the identifier","title":"Identifier Type"},"accepted_quantity":{"default":0,"description":"The quantity of the article that was accepted","title":"Accepted Quantity","type":"integer"},"rejected_quantity":{"default":0,"description":"The quantity of the article that was rejected","title":"Rejected Quantity","type":"integer"},"reason":{"default":null,"description":"The reason for the rejection of the article","title":"Reason","type":"string"}},"required":["identifier","identifier_type"],"title":"ArticleStatusUpdate","type":"object"},"ArticleIdentifierType":{"enum":["product_id","line_item_id","sku","variant_id","barcode","order_item_id"],"title":"ArticleIdentifierType","type":"string"},"CancelReturnMutation":{"description":"Cancel a return registration and its tracking.","properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"cancel_return","default":"cancel_return","title":"Type","type":"string"},"status_reason":{"description":"Optional reason for cancelling the return registration.","title":"Status Reason","type":"string"}},"title":"CancelReturnMutation","type":"object"},"ReturnRegistration":{"type":"object","description":"Represents a return registration","properties":{"account":{"type":"integer","description":"Account, that is linked to this registration."},"code":{"type":"string","title":"Configuration Code","description":"Configuration code of the return configuration","maxLength":255},"version":{"type":["string","null"]},"client_key":{"type":"string","readOnly":true,"description":"Name of the client, as configured in account setup."},"reference":{"type":"string","title":"Reference / Order Number","description":"Retailer reference, e.g. the order number, not unique","maxLength":255},"external_id":{"type":"string","format":"uuid","title":"External Identifier","description":"Unique identifier for this return registration, generated by parcelLab"},"external_reference":{"type":"string","description":"Additional identifier (e.g. shop system id) for this return registration, generated by the retailer","maxLength":255},"sequence_number":{"type":"string","readOnly":true},"status":{"$ref":"#/components/schemas/ReturnRegistrationStatusEnum"},"status_reason":{"type":"string","description":"Reason for the current status","maxLength":255},"original_courier":{"type":"string","maxLength":255},"original_order_id":{"type":["string","null"],"maxLength":255},"order_date":{"type":["string","null"],"format":"date-time","description":"Date of the order"},"order_currency":{"type":"string","description":"Currency of the order, e.g. USD, EUR (ISO 4217)","maxLength":3},"order_total_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Total amount of the original order"},"order_shipping_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Total shipping amount of the original order"},"order_tax_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Total tax amount of the original order"},"order_delivery_date":{"type":["string","null"],"format":"date-time","description":"Date of the order delivery"},"order_shipping_date":{"type":["string","null"],"format":"date-time","description":"Date of the order shipment"},"order_payment_method":{"type":"array","items":{"type":"string","maxLength":255},"description":"Payment method used for the order, as setup as reference items in the accounts configuration"},"language_iso2":{"type":"string","description":"ISO 639-1 language code of the recipient, if known, required for localized communication","maxLength":3},"is_gift_returns_portal":{"type":"boolean","readOnly":true},"customer_email":{"anyOf":[{"format":"email","type":"string"},{"const":"_unset","enum":["_unset"],"type":"string"}],"description":"Customers email address, must be provided, in case email is not known or should be unset, use the literal string '_unset' instead."},"customer_phone":{"type":"string","description":"Customer phone number","maxLength":255},"customer_salutation":{"type":"string","maxLength":255},"customer_first_name":{"type":"string","maxLength":255},"customer_last_name":{"type":"string","maxLength":255},"customer_country_iso3":{"type":"string","description":"ISO 3166-1 alpha-3 code of country","maxLength":3},"customer_address":{"anyOf":[{"$ref":"#/components/schemas/ValidatedAddressSchema"},{"$ref":"#/components/schemas/Empty"}]},"articles_order":{"items":{"$ref":"#/components/schemas/LineItem"},"type":"array"},"articles_return":{"items":{"$ref":"#/components/schemas/LineItemReturn"},"type":"array"},"return_labels":{"items":{"$ref":"#/components/schemas/ReturnLabel"},"type":"array","readOnly":true},"refund_method":{"type":"string","description":"Refund method selected by customer","maxLength":255},"tags":{"type":"array","items":{"type":"string","maxLength":255},"description":"Order level tags."},"additional_fields":{"type":"object","additionalProperties":{},"description":"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":{"type":"string","description":"Verification code (e.g. zip/email) used for this return registration","maxLength":255},"created_at":{"type":"string","format":"date-time","readOnly":true},"updated_at":{"type":"string","format":"date-time","readOnly":true},"mutations":{"items":{"anyOf":[{"$ref":"#/components/schemas/AddLabelMutation"},{"$ref":"#/components/schemas/UpdateItemMutation"},{"$ref":"#/components/schemas/CloseReturnMutation"},{"$ref":"#/components/schemas/CancelReturnMutation"}],"title":"Mutations"},"type":"array"}},"required":["account","client_key","code","created_at","customer_address","customer_email","is_gift_returns_portal","reference","return_labels","sequence_number","updated_at"]},"ReturnLabel":{"properties":{"courier":{"description":"Return label courier code or drop-off code, e.g. barcode","title":"Return Label Courier","type":"string"},"service_level":{"description":"Service level of the return label","title":"Service Level","type":"string"},"tracking_number":{"description":"Tracking number of the return label (or in case of Barcode the barcode)","title":"Tracking number","type":"string"},"type":{"$ref":"#/components/schemas/ReturnLabelTypeEnum","default":"shipping","description":"Type of the return label, e.g. 'shipping' for a real courier label, or barcode for a (custom) drop-off code","title":"Label Type"},"flags":{"description":"Flags (extra markers) for the return label, such as 'has_dangerous_goods', or 'is_pickup'","items":{"$ref":"#/components/schemas/ReturnLabelFlagsEnum"},"title":"Label Flags","type":"array"},"documents":{"description":"Documents related to this return label (e.g. print label, barcode, packing slip, wallet-passes)","items":{"$ref":"#/components/schemas/Document"},"title":"Label","type":"array"},"locations_url":{"description":"URL to a courier-specific location finder page.","title":"Locations URL","type":"string"},"destination_id":{"description":"Destination ID for the return label, e.g. warehouse code","title":"Destination ID","type":"string"},"line_item_ids":{"description":"The line item IDs to which the label should be attached","items":{"type":"string"},"title":"Line Item IDs","type":"array"},"is_free_label":{"default":false,"description":"Indicates if the return label is free of charge","title":"Is Free Label","type":"boolean"},"label_cost_amount":{"default":"0.0","description":"Cost of the return label","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Label Cost Amount","type":"string"},"tracking_id":{"description":"Tracking ID of the shipment in the parcelLab system","title":"ParcelLab Tracking ID","type":"string"},"external_reference":{"description":"Unique retailer-provided reference of the shipment, either this tracking number is required","title":"External Reference","type":"string"},"delivery_status":{"$ref":"#/components/schemas/TrackingStageChoices","default":"Pending","description":"Current shipping stage of the return label","title":"Current Shipping Stage"},"pickup_date":{"description":"Scheduled pickup date for the return label. Nullable if not a pickup return.","format":"date","title":"Pickup Date","type":"string"},"earliest_pickup_time":{"description":"Earliest scheduled pickup time for the return label. Nullable if not a pickup return.","format":"time","title":"Earliest Pickup Time","type":"string"},"latest_pickup_time":{"description":"Latest scheduled pickup time for the return label. Nullable if not a pickup return.","format":"time","title":"Latest Pickup Time","type":"string"},"pickup_confirmation_code":{"description":"Confirmation code customer must present on pickup","title":"Pickup Confirmation Code","type":"string"},"is_pickup":{"default":false,"description":"Indicates if the return is a pickup order.","title":"Is Pickup","type":"boolean"},"configuration_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Selected return option mapping ID used to create this label.","title":"Courier Mapping ID"}},"required":["courier","tracking_number"],"title":"Return Label","type":"object"},"ReturnLabelFlagsEnum":{"enum":["is_cancellable","is_pickup","has_dangerous_goods"],"type":"string"},"Document":{"properties":{"url":{"description":"URL to the document, in most cases this is a http URL, but it could also be a data URL (base64)","title":"Document URL","type":"string"},"content_type":{"default":"application/pdf","description":"MIME content type of the document, e.g. 'application/pdf'","title":"Content Type","type":"string"},"type":{"default":[],"description":"Type or types of the document, maybe multiple, if bundled","items":{"$ref":"#/components/schemas/DocumentTypeEnum"},"title":"Document Type","type":"array"},"expires_at":{"description":"Expiry date of the document, after which it might not be retrievable","format":"date-time","title":"Document expiry date","type":"string"}},"required":["url"],"title":"Document","type":"object"},"DocumentTypeEnum":{"enum":["label","packing_slip","barcode","customs_document","wallet_pass_io","wallet_pass_android","commercial_invoice"],"type":"string"},"TrackingStageChoices":{"enum":["Pending","Transit","Customs","LastMile","ReadyToCollect","Delivered","SentBack","Returned","Failed","Cancelled"],"title":"TrackingStageChoices","type":"string"},"Error400Response":{"type":"object","properties":{"type":{"type":"string"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/GenericErrorItem"}}},"required":["errors","type"]},"GenericErrorItem":{"type":"object","properties":{"code":{"type":"string"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["code","detail"]},"ErrorResponse403":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ClientErrorEnum"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error403"}}},"required":["errors","type"]},"ClientErrorEnum":{"enum":["client_error"],"type":"string","description":"* `client_error` - Client Error"},"Error403":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode403Enum"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["attr","code","detail"]},"ErrorCode403Enum":{"enum":["permission_denied"],"type":"string","description":"* `permission_denied` - Permission Denied"},"ErrorResponse404":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ClientErrorEnum"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error404"}}},"required":["errors","type"]},"Error404":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode404Enum"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["attr","code","detail"]},"ErrorCode404Enum":{"enum":["not_found"],"type":"string","description":"* `not_found` - Not Found"}}},"paths":{"/v4/returns/return-registrations/{external_id}/":{"put":{"operationId":"returns_return_registrations_update","description":"Return Registrations represent a return request from a customer. There might be multiple\nreturn registrations for a single order. There might also be multiple labels for one return\nregistration, if requested by the customer.\n\n A return registration is linked to a configuration bundle (field 'code'), multiple configurations\n might be available on one account (e.g. country-specific courier configurations).\n\n Return registrations are created by the parcelLab return portal, or by the retailer via the parcelLab API.\n\nCertain fields of the return registration are not mutable via requests on the registration resource, but require\n'action' payloads to be submitted (e.g. 'AddLabel') to the 'mutate' action.","summary":"Update Return Registration","parameters":[{"in":"path","name":"external_id","schema":{"type":"string","format":"uuid","title":"External Identifier","description":"Unique identifier for this return registration, generated by parcelLab"},"required":true}],"tags":["Return Registration"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnRegistrationRequest"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/ReturnRegistrationRequest"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/ReturnRegistrationRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnRegistration"}}},"description":""},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}},"description":""},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse403"}}},"description":""},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"description":""}}}}}} ``` ## Partially Update a Return Registration You can partially update a specific return registration using the `v4/returns/return-registrations/{external_id}` endpoint. ## Partially Update Return Registration > 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. ```json {"openapi":"3.1.0","info":{"title":"parcelLab API","version":"v4"},"security":[{"OAuth2 Authentication":[]},{"HeaderToken":[]}],"components":{"securitySchemes":{"OAuth2 Authentication":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"HeaderToken":{"type":"http","scheme":"bearer","bearerFormat":"Parcellab-API-Token base64(account_id:token)","description":"Send `Authorization: Parcellab-API-Token `.\n\n`` = `base64(account_id:token)` as provided in the portal."}},"schemas":{"PatchedReturnRegistrationRequest":{"type":"object","description":"Represents a return registration","properties":{"account":{"type":"integer","description":"Account, that is linked to this registration."},"code":{"type":"string","minLength":1,"title":"Configuration Code","description":"Configuration code of the return configuration","maxLength":255},"version":{"type":["string","null"]},"reference":{"type":"string","minLength":1,"title":"Reference / Order Number","description":"Retailer reference, e.g. the order number, not unique","maxLength":255},"external_id":{"type":"string","format":"uuid","title":"External Identifier","description":"Unique identifier for this return registration, generated by parcelLab"},"external_reference":{"type":"string","description":"Additional identifier (e.g. shop system id) for this return registration, generated by the retailer","maxLength":255},"status":{"$ref":"#/components/schemas/ReturnRegistrationStatusEnum"},"status_reason":{"type":"string","description":"Reason for the current status","maxLength":255},"original_courier":{"type":"string","maxLength":255},"original_order_id":{"type":["string","null"],"maxLength":255},"order_date":{"type":["string","null"],"format":"date-time","description":"Date of the order"},"order_currency":{"type":"string","description":"Currency of the order, e.g. USD, EUR (ISO 4217)","maxLength":3},"order_total_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Total amount of the original order"},"order_shipping_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Total shipping amount of the original order"},"order_tax_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Total tax amount of the original order"},"order_delivery_date":{"type":["string","null"],"format":"date-time","description":"Date of the order delivery"},"order_shipping_date":{"type":["string","null"],"format":"date-time","description":"Date of the order shipment"},"order_payment_method":{"type":"array","items":{"type":"string","minLength":1,"maxLength":255},"description":"Payment method used for the order, as setup as reference items in the accounts configuration"},"language_iso2":{"type":"string","description":"ISO 639-1 language code of the recipient, if known, required for localized communication","maxLength":3},"customer_email":{"anyOf":[{"format":"email","type":"string"},{"const":"_unset","enum":["_unset"],"type":"string"}],"minLength":1,"description":"Customers email address, must be provided, in case email is not known or should be unset, use the literal string '_unset' instead."},"customer_phone":{"type":"string","description":"Customer phone number","maxLength":255},"customer_salutation":{"type":"string","maxLength":255},"customer_first_name":{"type":"string","maxLength":255},"customer_last_name":{"type":"string","maxLength":255},"customer_country_iso3":{"type":"string","description":"ISO 3166-1 alpha-3 code of country","maxLength":3},"customer_address":{"anyOf":[{"$ref":"#/components/schemas/ValidatedAddressSchema"},{"$ref":"#/components/schemas/Empty"}]},"articles_order":{"items":{"$ref":"#/components/schemas/LineItem"},"type":"array"},"articles_return":{"items":{"$ref":"#/components/schemas/LineItemReturn"},"type":"array"},"refund_method":{"type":"string","description":"Refund method selected by customer","maxLength":255},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":255},"description":"Order level tags."},"additional_fields":{"type":"object","additionalProperties":{},"description":"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":{"type":"string","description":"Verification code (e.g. zip/email) used for this return registration","maxLength":255},"mutations":{"items":{"anyOf":[{"$ref":"#/components/schemas/AddLabelMutation"},{"$ref":"#/components/schemas/UpdateItemMutation"},{"$ref":"#/components/schemas/CloseReturnMutation"},{"$ref":"#/components/schemas/CancelReturnMutation"}],"title":"Mutations"},"type":"array"}}},"ReturnRegistrationStatusEnum":{"enum":["created","submitted","pending_approval","pending_label","approved","rejected","cancelled","closed","processing_failed","invalid"],"type":"string","description":"* `created` - Created\n* `submitted` - Submitted\n* `pending_approval` - Pending Approval\n* `pending_label` - Pending Label\n* `approved` - Approved\n* `rejected` - Rejected\n* `cancelled` - Cancelled\n* `closed` - Closed\n* `processing_failed` - Processing Failed\n* `invalid` - Invalid"},"ValidatedAddressSchema":{"properties":{"first_name":{"title":"First Name","type":"string"},"last_name":{"title":"Last Name","type":"string"},"company_name":{"title":"Company Name, if any","type":"string"},"address_line":{"description":"Address line, e.g. street and house number, or PO Box","maxLength":256,"minLength":1,"title":"Address Line","type":"string"},"address_line_extra":{"description":"Additional address line, e.g. apartment number or company name","title":"Additional Address Line","type":"string"},"postal_code":{"maxLength":10,"minLength":2,"title":"Postal Code","type":"string"},"city":{"description":"City name (min-length of 1 due to logographic languages)","maxLength":40,"minLength":1,"title":"City","type":"string"},"country_iso3":{"description":"ISO 3166-1 alpha-3 code of country","pattern":"^\\w{3}$","title":"Country ISO3","type":"string"},"region_code":{"description":"Region code, e.g. state or province code (ISO 3166-2), if available","maxLength":25,"minLength":1,"title":"Region Code","type":"string"},"phone":{"description":"Phone number related to this address, if any","maxLength":30,"title":"Phone","type":"string"}},"required":["address_line","postal_code","city","country_iso3"],"title":"Address","type":"object"},"Empty":{"additionalProperties":false,"properties":{},"title":"Empty","type":"object"},"LineItem":{"additionalProperties":true,"properties":{"version":{"$ref":"#/components/schemas/LineItemVersionEnum","description":"Optional. Omit this key unless absolutely intended. The standard value is `v2`. If you send `version`, send `v2`.","title":"Version"},"line_item_id":{"description":"Retailer ID of the line item","title":"Line Item ID","type":"string"},"product_id":{"description":"Parent product identifier in the retailer's system (shared across variants).","title":"Product ID","type":"string"},"variant_id":{"description":"SKU/variant identifier; prefer for matching when available since parent product IDs are reused across variants.","title":"Variant ID","type":"string"},"sku":{"description":"Stock Keeping Unit of the line item","title":"SKU","type":"string"},"barcode":{"description":"Barcode associated with the line item variant or product","title":"Barcode","type":"string"},"order_item_id":{"description":"Line Item ID in the order (preferred when provided)","title":"Order Line Item ID","type":"string"},"article_name":{"description":"Name of the article","title":"Article Name","type":"string"},"article_category":{"description":"Category of the article","title":"Article Category","type":"string"},"article_store_url":{"description":"URL to the article in the store","title":"Article Store URL","type":"string"},"article_image_url":{"description":"URL to the image of the article","title":"Article Image URL","type":"string"},"article_brand":{"description":"Brand of the article (reference only)","title":"Article Brand","type":"string"},"size":{"description":"Size of the article (reference only)","title":"Size","type":"string"},"color":{"description":"Color of the article (reference only)","title":"Color","type":"string"},"width":{"description":"Width of the article (in millimeters)","title":"Width","type":"number"},"height":{"description":"Height of the article (in millimeters)","title":"Height","type":"number"},"length":{"description":"Length of the article (in millimeters)","title":"Length","type":"number"},"length_unit":{"const":"cm","default":"cm","title":"Length Unit","type":"string"},"weight":{"description":"Weight of the article (in grams, kg, lbs, or oz)","title":"Weight","type":"number"},"weight_unit":{"allOf":[{"$ref":"#/components/schemas/WeightUnitEnum"}],"default":"g","title":"Weight Unit"},"unit_price":{"description":"Paid unit price of the article (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Unit Price","type":"string"},"unit_price_original":{"description":"Original unit price of the article (pre-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Unit Price","type":"string"},"quantity":{"description":"Unit quantity of the article","title":"Unit Quantity","type":"integer"},"amount_invoiced":{"description":"Paid line total amount for this line item (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Invoiced","type":"string"},"tax_amount":{"description":"Total tax amount for this line item (regardless of taxesIncluded)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Tax Amount","type":"string"},"harmonized_system_code":{"description":"HS/HTS code for customs classification","title":"Harmonized System Code","type":"string"},"origin_country_iso3":{"description":"ISO 3166-1 alpha-3 code of articles country of origin, might be required based on shipment regulations","pattern":"^\\w{3}$","title":"Origin Country ISO3","type":"string"},"is_bulky":{"default":false,"description":"If the article is bulky","title":"Is Bulky","type":"boolean"},"tags":{"description":"Tags for the line item, e.g. 'category:home-apparel', or 'customergroup:vip'","items":{"type":"string"},"title":"Tags","type":"array"},"bundle":{"anyOf":[{"$ref":"#/components/schemas/BundleInfo"},{"type":"null"}],"default":null,"description":"Bundle relationship metadata when the item is part of a bundle.","title":"Bundle Info"},"additional_attributes":{"description":"Additional attributes for this line item","items":{"$ref":"#/components/schemas/AdditionalAttribute"},"title":"Additional Attributes","type":"array"}},"required":["line_item_id"],"title":"Line Item","type":"object"},"LineItemVersionEnum":{"enum":["v1","v2"],"title":"LineItemVersionEnum","type":"string"},"WeightUnitEnum":{"enum":["kg","g","lbs","oz"],"type":"string"},"BundleInfo":{"additionalProperties":true,"properties":{"group_id":{"description":"Bundle group identifier in the retailer's system.","title":"Bundle Group ID","type":"string"},"role":{"$ref":"#/components/schemas/BundleRoleEnum","description":"Whether this line item represents a bundle parent or a bundle component.","title":"Bundle Role"},"return_policy":{"$ref":"#/components/schemas/BundleReturnPolicyEnum","default":"components_only","description":"Which lines in this bundle group are selectable for return.","title":"Bundle Return Policy"},"parent_product_id":{"description":"Parent bundle product identifier in the retailer's system.","title":"Bundle Parent Product ID","type":"string"},"parent_variant_id":{"description":"Parent bundle variant identifier in the retailer's system.","title":"Bundle Parent Variant ID","type":"string"},"parent_sku":{"description":"Parent bundle SKU, if available.","title":"Bundle Parent SKU","type":"string"},"parent_title":{"description":"Display title for the bundle parent, if available.","title":"Bundle Parent Title","type":"string"},"parent_quantity":{"description":"Quantity of the bundle parent purchased in the order.","title":"Bundle Parent Quantity","type":"integer"},"component_quantity_per_parent":{"description":"Component quantity per single bundle parent (if determinable).","title":"Bundle Component Quantity Per Parent","type":"integer"},"allocation_method":{"$ref":"#/components/schemas/BundleAllocationMethodEnum","default":"none","description":"How pricing was allocated to bundle components.","title":"Bundle Allocation Method"},"allocated_unit_price":{"description":"Snapshot of allocated component unit price (if derived from bundle totals).","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Allocated Unit Price","type":"string"},"allocated_amount_invoiced":{"description":"Snapshot of allocated component invoiced amount (if derived from bundle totals).","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Allocated Amount Invoiced","type":"string"}},"required":["group_id","role"],"title":"Bundle Info","type":"object"},"BundleRoleEnum":{"enum":["parent","component"],"title":"BundleRoleEnum","type":"string"},"BundleReturnPolicyEnum":{"enum":["parent_only","components_only","parent_and_components"],"title":"BundleReturnPolicyEnum","type":"string"},"BundleAllocationMethodEnum":{"enum":["none","component_price","msrp_ratio","equal"],"title":"BundleAllocationMethodEnum","type":"string"},"AdditionalAttribute":{"properties":{"key":{"description":"The key of the additional attribute","title":"Key","type":"string"},"value":{"default":null,"description":"The value of the additional attribute","title":"Value"}},"required":["key"],"title":"AdditionalAttribute","type":"object"},"LineItemReturn":{"additionalProperties":true,"properties":{"version":{"$ref":"#/components/schemas/LineItemVersionEnum","description":"Optional. Omit this key unless absolutely intended. The standard value is `v2`. If you send `version`, send `v2`.","title":"Version"},"line_item_id":{"description":"Retailer ID of the line item, only the last number part of the whole line item id string","title":"Line Item ID","type":"string"},"product_id":{"description":"Parent product identifier in the retailer's system (shared across variants).","title":"Product ID","type":"string"},"variant_id":{"description":"SKU/variant identifier; prefer for matching when available since parent product IDs are reused across variants.","title":"Variant ID","type":"string"},"sku":{"description":"Stock Keeping Unit of the line item","title":"SKU","type":"string"},"barcode":{"description":"Barcode associated with the line item variant or product","title":"Barcode","type":"string"},"order_item_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Line Item ID in the order, the whole id of the fulfillment line item","title":"Order Line Item ID"},"article_name":{"description":"Name of the article","title":"Article Name","type":"string"},"article_category":{"description":"Category of the article","title":"Article Category","type":"string"},"article_store_url":{"description":"URL to the article in the store","title":"Article Store URL","type":"string"},"article_image_url":{"description":"URL to the image of the article","title":"Article Image URL","type":"string"},"article_brand":{"description":"Brand of the article (reference only)","title":"Article Brand","type":"string"},"size":{"description":"Size of the article (reference only)","title":"Size","type":"string"},"color":{"description":"Color of the article (reference only)","title":"Color","type":"string"},"width":{"description":"Width of the article (in millimeters)","title":"Width","type":"number"},"height":{"description":"Height of the article (in millimeters)","title":"Height","type":"number"},"length":{"description":"Length of the article (in millimeters)","title":"Length","type":"number"},"length_unit":{"const":"cm","default":"cm","title":"Length Unit","type":"string"},"weight":{"description":"Weight of the article (in grams, kg, lbs, or oz)","title":"Weight","type":"number"},"weight_unit":{"allOf":[{"$ref":"#/components/schemas/WeightUnitEnum"}],"default":"g","title":"Weight Unit"},"unit_price":{"description":"Paid unit price of the article (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Unit Price","type":"string"},"unit_price_original":{"description":"Original unit price of the article (pre-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Unit Price","type":"string"},"quantity":{"description":"Unit quantity of the article","title":"Unit Quantity","type":"integer"},"amount_invoiced":{"description":"Paid line total amount for this line item (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Invoiced","type":"string"},"tax_amount":{"description":"Total tax amount for this line item (regardless of taxesIncluded)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Tax Amount","type":"string"},"harmonized_system_code":{"description":"HS/HTS code for customs classification","title":"Harmonized System Code","type":"string"},"origin_country_iso3":{"description":"ISO 3166-1 alpha-3 code of articles country of origin, might be required based on shipment regulations","pattern":"^\\w{3}$","title":"Origin Country ISO3","type":"string"},"is_bulky":{"default":false,"description":"If the article is bulky","title":"Is Bulky","type":"boolean"},"tags":{"description":"Tags for the line item, e.g. 'category:home-apparel', or 'customergroup:vip'","items":{"type":"string"},"title":"Tags","type":"array"},"bundle":{"anyOf":[{"$ref":"#/components/schemas/BundleInfo"},{"type":"null"}],"default":null,"description":"Bundle relationship metadata when the item is part of a bundle.","title":"Bundle Info"},"additional_attributes":{"description":"Additional attributes for this line item","items":{"$ref":"#/components/schemas/AdditionalAttribute"},"title":"Additional Attributes","type":"array"},"unit_price_msrp_current":{"anyOf":[{"pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","type":"string"},{"type":"null"}],"default":null,"description":"Current catalog/MSRP unit price for the same variant.","title":"Current MSRP"},"reference_date_for_return":{"description":"The date, which is used to evaluate the line item return period","format":"date","title":"Reference Date for Return","type":"string"},"reference_date_type":{"allOf":[{"$ref":"#/components/schemas/ReferenceDateTypeEnum"}],"description":"The date type, which is used to evaluate the line item return period","title":"Reference Date Type"},"fulfillment":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Id of the fulfillment that this item belongs to","title":"Fulfillment"},"quantity_returned":{"description":"Quantity of already returned items in this line.","title":"Quantity Returned","type":"integer"},"delivered_date":{"description":"Date when the line item was delivered (same as the fulfillment delivered date)","format":"date","title":"Delivered Date","type":"string"},"return_reason":{"description":"Full return reason path (as configured in the respective return configuration for this object)","title":"Return Reason","type":"string"},"return_reason_pretty":{"description":"Pretty text for the return reason, e.g. 'Doesn't Fit'","title":"Return Reason Pretty","type":"string"},"return_quantity":{"description":"Quantity to be returned","title":"Return Quantity","type":"integer"},"problem_description":{"description":"Description of the problem with this line item","title":"Problem Description","type":"string"},"condition":{"description":"Article condition, if provided","title":"Condition","type":"string"},"article_images":{"items":{"$ref":"#/components/schemas/ReturnImage"},"title":"Article Images","type":"array"},"compensation_method":{"description":"Compensation method for this line item, e.g. exchange, refund, credit","title":"Compensation Method","type":"string"},"accepted_quantity":{"description":"Quantity of the article that was accepted by warehouse","title":"Accepted Quantity","type":"integer"},"rejected_quantity":{"description":"Quantity of the article that was rejected by warehouse","title":"Rejected Quantity","type":"integer"},"status_reason":{"description":"Reason for the rejection / acceptance of the article","title":"Rejection or Acceptance Reason","type":"string"},"status_reason_code":{"description":"Structured reason code, e.g. quality_issue","title":"Status Reason Code","type":"string"},"return_reason_code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Final code of return reason (leaf code)","readOnly":true,"title":"Return Reason Code"}},"required":["line_item_id","return_reason_code"],"title":"Line Item","type":"object"},"ReferenceDateTypeEnum":{"enum":["order_date","shipping_date","delivery_date"],"type":"string"},"ReturnImage":{"properties":{"url":{"title":"Url","type":"string"},"name":{"title":"Name","type":"string"},"mime_type":{"title":"Mime Type","type":"string"}},"required":["url","name","mime_type"],"title":"ReturnImage","type":"object"},"AddLabelMutation":{"properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"add_label","default":"add_label","title":"Type","type":"string"},"request":{"$ref":"#/components/schemas/AddLabelRequest","description":"The labels to be added to this return registration","title":"Label Requests"}},"required":["request"],"title":"AddLabelMutation","type":"object"},"MutationResult":{"description":"The result of a mutation","properties":{"success":{"default":false,"description":"Whether the mutation was successful","title":"Success","type":"boolean"},"message":{"default":"","description":"A message describing the result of the mutation","title":"Message","type":"string"},"errors":{"additionalProperties":{"type":"string"},"description":"A dictionary of errors that occurred during the mutation","title":"Errors","type":"object"},"warnings":{"description":"Non-fatal warnings raised while processing the mutation","items":{"type":"string"},"title":"Warnings","type":"array"}},"title":"MutationResult","type":"object"},"AddLabelRequest":{"description":"Adds a label to a return registration","properties":{"type":{"$ref":"#/components/schemas/ReturnLabelTypeEnum"},"courier":{"description":"The courier for which a label should be created","title":"Courier","type":"string"},"tracking_number":{"description":"Only for custom label: custom tracking number for the label","title":"Tracking Number","type":"string"},"service_level":{"description":"The service level for the label","title":"Service Level","type":"string"},"destination_id":{"description":"The warehouse or other identifier, to which the courier should ship, corresponds to a warehouse code","title":"Identifier / Warehouse","type":"string"},"destination_address":{"$ref":"#/components/schemas/AddressSchema","description":"Defines a destination address for this label, has precedence over default destination addresses setup in courier configuration. If the courier does not support a custom destination address & the destination address object is present, will raise an error ","title":"Destination Address"},"template_id":{"description":"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.","title":"Template ID","type":"string"},"flags":{"description":"A list of special flags that apply to the label or shipment","items":{"$ref":"#/components/schemas/AddLabelFlagsEnum"},"title":"Flags","type":"array"},"label_types":{"description":"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).","items":{"$ref":"#/components/schemas/LabelTypesEnum"},"title":"Label Types","type":"array"},"line_item_ids":{"description":"The line item IDs to which the label should be attached","items":{"type":"string"},"title":"Line Item IDs","type":"array"},"additional_fields":{"additionalProperties":true,"description":"Custom fields to pass through to label generation and returns document.","title":"Additional Fields","type":"object"}},"required":["type","courier"],"title":"AddLabelRequest","type":"object"},"ReturnLabelTypeEnum":{"enum":["shipping","custom"],"title":"ReturnLabelTypeEnum","type":"string"},"AddressSchema":{"properties":{"first_name":{"title":"First Name","type":"string"},"last_name":{"title":"Last Name","type":"string"},"company_name":{"title":"Company Name, if any","type":"string"},"address_line":{"description":"Address line, e.g. street and house number, or PO Box","maxLength":256,"minLength":1,"title":"Address Line","type":"string"},"address_line_extra":{"description":"Additional address line, e.g. apartment number or company name","title":"Additional Address Line","type":"string"},"postal_code":{"maxLength":10,"minLength":2,"title":"Postal Code","type":"string"},"city":{"description":"City name (min-length of 1 due to logographic languages)","maxLength":40,"minLength":1,"title":"City","type":"string"},"country_iso3":{"description":"ISO 3166-1 alpha-3 code of country","pattern":"^\\w{3}$","title":"Country ISO3","type":"string"},"region_code":{"description":"Region code, e.g. state or province code (ISO 3166-2), if available","maxLength":25,"minLength":1,"title":"Region Code","type":"string"},"phone":{"description":"Phone number related to this address, if any","maxLength":30,"title":"Phone","type":"string"}},"required":["address_line","postal_code","city","country_iso3"],"title":"Address","type":"object"},"AddLabelFlagsEnum":{"enum":["has_dangerous_goods","is_pickup"],"type":"string"},"LabelTypesEnum":{"enum":["code","print"],"type":"string"},"UpdateItemMutation":{"description":"Update registered article items","properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"update_items","default":"update_items","title":"Type","type":"string"},"items":{"description":"Items for this return registration after update is a applied","items":{"$ref":"#/components/schemas/LineItemReturn"},"title":"Line Items to return","type":"array"}},"title":"Update Items Mutation","type":"object"},"CloseReturnMutation":{"description":"Close a return registration (finalize return + refund).","properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"close_return","default":"close_return","title":"Type","type":"string"},"status_reason":{"description":"Optional reason for closing the return registration.","title":"Status Reason","type":"string"},"trigger_refund":{"description":"Whether to issue a monetary refund when closing the return.","title":"Trigger Refund","type":"boolean"},"release_exchange_items":{"description":"Whether to release exchange items when closing the return.","title":"Release Exchange Items","type":"boolean"},"refund_shipping_fees":{"description":"Whether to refund the original order shipping cost.","title":"Refund Shipping Fees","type":"boolean"},"tracking_number":{"description":"Optional tracking number used for receive-status synchronization when article status updates are provided.","title":"Tracking Number","type":"string"},"received_by":{"description":"Optional source shown in receive status when article status updates are provided. Defaults to API (close_return mutation).","title":"Received By","type":"string"},"receive_note":{"description":"Optional receive note stored with receive status and synchronized to tracking returnReceive.note when article status updates are provided.","title":"Receive Note","type":"string"},"article_status_updates":{"description":"Optional receive-style article status updates to apply before closing the return registration.","items":{"$ref":"#/components/schemas/ArticleStatusUpdate"},"title":"Article Status Updates","type":"array"}},"title":"CloseReturnMutation","type":"object"},"ArticleStatusUpdate":{"properties":{"identifier":{"description":"Identifier of the article to update the status for","title":"Identifier of article","type":"string"},"identifier_type":{"$ref":"#/components/schemas/ArticleIdentifierType","description":"The type of the identifier","title":"Identifier Type"},"accepted_quantity":{"default":0,"description":"The quantity of the article that was accepted","title":"Accepted Quantity","type":"integer"},"rejected_quantity":{"default":0,"description":"The quantity of the article that was rejected","title":"Rejected Quantity","type":"integer"},"reason":{"default":null,"description":"The reason for the rejection of the article","title":"Reason","type":"string"}},"required":["identifier","identifier_type"],"title":"ArticleStatusUpdate","type":"object"},"ArticleIdentifierType":{"enum":["product_id","line_item_id","sku","variant_id","barcode","order_item_id"],"title":"ArticleIdentifierType","type":"string"},"CancelReturnMutation":{"description":"Cancel a return registration and its tracking.","properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"cancel_return","default":"cancel_return","title":"Type","type":"string"},"status_reason":{"description":"Optional reason for cancelling the return registration.","title":"Status Reason","type":"string"}},"title":"CancelReturnMutation","type":"object"},"ReturnRegistration":{"type":"object","description":"Represents a return registration","properties":{"account":{"type":"integer","description":"Account, that is linked to this registration."},"code":{"type":"string","title":"Configuration Code","description":"Configuration code of the return configuration","maxLength":255},"version":{"type":["string","null"]},"client_key":{"type":"string","readOnly":true,"description":"Name of the client, as configured in account setup."},"reference":{"type":"string","title":"Reference / Order Number","description":"Retailer reference, e.g. the order number, not unique","maxLength":255},"external_id":{"type":"string","format":"uuid","title":"External Identifier","description":"Unique identifier for this return registration, generated by parcelLab"},"external_reference":{"type":"string","description":"Additional identifier (e.g. shop system id) for this return registration, generated by the retailer","maxLength":255},"sequence_number":{"type":"string","readOnly":true},"status":{"$ref":"#/components/schemas/ReturnRegistrationStatusEnum"},"status_reason":{"type":"string","description":"Reason for the current status","maxLength":255},"original_courier":{"type":"string","maxLength":255},"original_order_id":{"type":["string","null"],"maxLength":255},"order_date":{"type":["string","null"],"format":"date-time","description":"Date of the order"},"order_currency":{"type":"string","description":"Currency of the order, e.g. USD, EUR (ISO 4217)","maxLength":3},"order_total_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Total amount of the original order"},"order_shipping_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Total shipping amount of the original order"},"order_tax_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Total tax amount of the original order"},"order_delivery_date":{"type":["string","null"],"format":"date-time","description":"Date of the order delivery"},"order_shipping_date":{"type":["string","null"],"format":"date-time","description":"Date of the order shipment"},"order_payment_method":{"type":"array","items":{"type":"string","maxLength":255},"description":"Payment method used for the order, as setup as reference items in the accounts configuration"},"language_iso2":{"type":"string","description":"ISO 639-1 language code of the recipient, if known, required for localized communication","maxLength":3},"is_gift_returns_portal":{"type":"boolean","readOnly":true},"customer_email":{"anyOf":[{"format":"email","type":"string"},{"const":"_unset","enum":["_unset"],"type":"string"}],"description":"Customers email address, must be provided, in case email is not known or should be unset, use the literal string '_unset' instead."},"customer_phone":{"type":"string","description":"Customer phone number","maxLength":255},"customer_salutation":{"type":"string","maxLength":255},"customer_first_name":{"type":"string","maxLength":255},"customer_last_name":{"type":"string","maxLength":255},"customer_country_iso3":{"type":"string","description":"ISO 3166-1 alpha-3 code of country","maxLength":3},"customer_address":{"anyOf":[{"$ref":"#/components/schemas/ValidatedAddressSchema"},{"$ref":"#/components/schemas/Empty"}]},"articles_order":{"items":{"$ref":"#/components/schemas/LineItem"},"type":"array"},"articles_return":{"items":{"$ref":"#/components/schemas/LineItemReturn"},"type":"array"},"return_labels":{"items":{"$ref":"#/components/schemas/ReturnLabel"},"type":"array","readOnly":true},"refund_method":{"type":"string","description":"Refund method selected by customer","maxLength":255},"tags":{"type":"array","items":{"type":"string","maxLength":255},"description":"Order level tags."},"additional_fields":{"type":"object","additionalProperties":{},"description":"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":{"type":"string","description":"Verification code (e.g. zip/email) used for this return registration","maxLength":255},"created_at":{"type":"string","format":"date-time","readOnly":true},"updated_at":{"type":"string","format":"date-time","readOnly":true},"mutations":{"items":{"anyOf":[{"$ref":"#/components/schemas/AddLabelMutation"},{"$ref":"#/components/schemas/UpdateItemMutation"},{"$ref":"#/components/schemas/CloseReturnMutation"},{"$ref":"#/components/schemas/CancelReturnMutation"}],"title":"Mutations"},"type":"array"}},"required":["account","client_key","code","created_at","customer_address","customer_email","is_gift_returns_portal","reference","return_labels","sequence_number","updated_at"]},"ReturnLabel":{"properties":{"courier":{"description":"Return label courier code or drop-off code, e.g. barcode","title":"Return Label Courier","type":"string"},"service_level":{"description":"Service level of the return label","title":"Service Level","type":"string"},"tracking_number":{"description":"Tracking number of the return label (or in case of Barcode the barcode)","title":"Tracking number","type":"string"},"type":{"$ref":"#/components/schemas/ReturnLabelTypeEnum","default":"shipping","description":"Type of the return label, e.g. 'shipping' for a real courier label, or barcode for a (custom) drop-off code","title":"Label Type"},"flags":{"description":"Flags (extra markers) for the return label, such as 'has_dangerous_goods', or 'is_pickup'","items":{"$ref":"#/components/schemas/ReturnLabelFlagsEnum"},"title":"Label Flags","type":"array"},"documents":{"description":"Documents related to this return label (e.g. print label, barcode, packing slip, wallet-passes)","items":{"$ref":"#/components/schemas/Document"},"title":"Label","type":"array"},"locations_url":{"description":"URL to a courier-specific location finder page.","title":"Locations URL","type":"string"},"destination_id":{"description":"Destination ID for the return label, e.g. warehouse code","title":"Destination ID","type":"string"},"line_item_ids":{"description":"The line item IDs to which the label should be attached","items":{"type":"string"},"title":"Line Item IDs","type":"array"},"is_free_label":{"default":false,"description":"Indicates if the return label is free of charge","title":"Is Free Label","type":"boolean"},"label_cost_amount":{"default":"0.0","description":"Cost of the return label","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Label Cost Amount","type":"string"},"tracking_id":{"description":"Tracking ID of the shipment in the parcelLab system","title":"ParcelLab Tracking ID","type":"string"},"external_reference":{"description":"Unique retailer-provided reference of the shipment, either this tracking number is required","title":"External Reference","type":"string"},"delivery_status":{"$ref":"#/components/schemas/TrackingStageChoices","default":"Pending","description":"Current shipping stage of the return label","title":"Current Shipping Stage"},"pickup_date":{"description":"Scheduled pickup date for the return label. Nullable if not a pickup return.","format":"date","title":"Pickup Date","type":"string"},"earliest_pickup_time":{"description":"Earliest scheduled pickup time for the return label. Nullable if not a pickup return.","format":"time","title":"Earliest Pickup Time","type":"string"},"latest_pickup_time":{"description":"Latest scheduled pickup time for the return label. Nullable if not a pickup return.","format":"time","title":"Latest Pickup Time","type":"string"},"pickup_confirmation_code":{"description":"Confirmation code customer must present on pickup","title":"Pickup Confirmation Code","type":"string"},"is_pickup":{"default":false,"description":"Indicates if the return is a pickup order.","title":"Is Pickup","type":"boolean"},"configuration_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Selected return option mapping ID used to create this label.","title":"Courier Mapping ID"}},"required":["courier","tracking_number"],"title":"Return Label","type":"object"},"ReturnLabelFlagsEnum":{"enum":["is_cancellable","is_pickup","has_dangerous_goods"],"type":"string"},"Document":{"properties":{"url":{"description":"URL to the document, in most cases this is a http URL, but it could also be a data URL (base64)","title":"Document URL","type":"string"},"content_type":{"default":"application/pdf","description":"MIME content type of the document, e.g. 'application/pdf'","title":"Content Type","type":"string"},"type":{"default":[],"description":"Type or types of the document, maybe multiple, if bundled","items":{"$ref":"#/components/schemas/DocumentTypeEnum"},"title":"Document Type","type":"array"},"expires_at":{"description":"Expiry date of the document, after which it might not be retrievable","format":"date-time","title":"Document expiry date","type":"string"}},"required":["url"],"title":"Document","type":"object"},"DocumentTypeEnum":{"enum":["label","packing_slip","barcode","customs_document","wallet_pass_io","wallet_pass_android","commercial_invoice"],"type":"string"},"TrackingStageChoices":{"enum":["Pending","Transit","Customs","LastMile","ReadyToCollect","Delivered","SentBack","Returned","Failed","Cancelled"],"title":"TrackingStageChoices","type":"string"},"Error400Response":{"type":"object","properties":{"type":{"type":"string"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/GenericErrorItem"}}},"required":["errors","type"]},"GenericErrorItem":{"type":"object","properties":{"code":{"type":"string"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["code","detail"]},"ErrorResponse403":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ClientErrorEnum"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error403"}}},"required":["errors","type"]},"ClientErrorEnum":{"enum":["client_error"],"type":"string","description":"* `client_error` - Client Error"},"Error403":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode403Enum"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["attr","code","detail"]},"ErrorCode403Enum":{"enum":["permission_denied"],"type":"string","description":"* `permission_denied` - Permission Denied"},"ErrorResponse404":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ClientErrorEnum"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error404"}}},"required":["errors","type"]},"Error404":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode404Enum"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["attr","code","detail"]},"ErrorCode404Enum":{"enum":["not_found"],"type":"string","description":"* `not_found` - Not Found"}}},"paths":{"/v4/returns/return-registrations/{external_id}/":{"patch":{"operationId":"returns_return_registrations_partial_update","description":"Return Registrations represent a return request from a customer. There might be multiple\nreturn registrations for a single order. There might also be multiple labels for one return\nregistration, if requested by the customer.\n\n A return registration is linked to a configuration bundle (field 'code'), multiple configurations\n might be available on one account (e.g. country-specific courier configurations).\n\n Return registrations are created by the parcelLab return portal, or by the retailer via the parcelLab API.\n\nCertain fields of the return registration are not mutable via requests on the registration resource, but require\n'action' payloads to be submitted (e.g. 'AddLabel') to the 'mutate' action.","summary":"Partially Update Return Registration","parameters":[{"in":"path","name":"external_id","schema":{"type":"string","format":"uuid","title":"External Identifier","description":"Unique identifier for this return registration, generated by parcelLab"},"required":true}],"tags":["Return Registration"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchedReturnRegistrationRequest"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/PatchedReturnRegistrationRequest"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/PatchedReturnRegistrationRequest"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnRegistration"}}},"description":""},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}},"description":""},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse403"}}},"description":""},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"description":""}}}}}} ``` ## Modify a Return Registration You can use the available mutations (for example: generate a label) to update a specific return registration using the `v4/returns/return-registrations/{external_id}/mutate` endpoint. ## Mutate Return Registration > Mutate this return registration with one of the available mutations ```json {"openapi":"3.1.0","info":{"title":"parcelLab API","version":"v4"},"security":[{"OAuth2 Authentication":[]},{"HeaderToken":[]}],"components":{"securitySchemes":{"OAuth2 Authentication":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"HeaderToken":{"type":"http","scheme":"bearer","bearerFormat":"Parcellab-API-Token base64(account_id:token)","description":"Send `Authorization: Parcellab-API-Token `.\n\n`` = `base64(account_id:token)` as provided in the portal."}},"schemas":{"MutateReturnRegistrationRequest":{"type":"object","description":"Update (mutate) a return registration","properties":{"mutations":{"items":{"anyOf":[{"$ref":"#/components/schemas/AddLabelMutation"},{"$ref":"#/components/schemas/UpdateItemMutation"},{"$ref":"#/components/schemas/CloseReturnMutation"},{"$ref":"#/components/schemas/CancelReturnMutation"}],"title":"Mutations"},"type":"array","writeOnly":true}}},"AddLabelMutation":{"properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"add_label","default":"add_label","title":"Type","type":"string"},"request":{"$ref":"#/components/schemas/AddLabelRequest","description":"The labels to be added to this return registration","title":"Label Requests"}},"required":["request"],"title":"AddLabelMutation","type":"object"},"MutationResult":{"description":"The result of a mutation","properties":{"success":{"default":false,"description":"Whether the mutation was successful","title":"Success","type":"boolean"},"message":{"default":"","description":"A message describing the result of the mutation","title":"Message","type":"string"},"errors":{"additionalProperties":{"type":"string"},"description":"A dictionary of errors that occurred during the mutation","title":"Errors","type":"object"},"warnings":{"description":"Non-fatal warnings raised while processing the mutation","items":{"type":"string"},"title":"Warnings","type":"array"}},"title":"MutationResult","type":"object"},"AddLabelRequest":{"description":"Adds a label to a return registration","properties":{"type":{"$ref":"#/components/schemas/ReturnLabelTypeEnum"},"courier":{"description":"The courier for which a label should be created","title":"Courier","type":"string"},"tracking_number":{"description":"Only for custom label: custom tracking number for the label","title":"Tracking Number","type":"string"},"service_level":{"description":"The service level for the label","title":"Service Level","type":"string"},"destination_id":{"description":"The warehouse or other identifier, to which the courier should ship, corresponds to a warehouse code","title":"Identifier / Warehouse","type":"string"},"destination_address":{"$ref":"#/components/schemas/AddressSchema","description":"Defines a destination address for this label, has precedence over default destination addresses setup in courier configuration. If the courier does not support a custom destination address & the destination address object is present, will raise an error ","title":"Destination Address"},"template_id":{"description":"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.","title":"Template ID","type":"string"},"flags":{"description":"A list of special flags that apply to the label or shipment","items":{"$ref":"#/components/schemas/AddLabelFlagsEnum"},"title":"Flags","type":"array"},"label_types":{"description":"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).","items":{"$ref":"#/components/schemas/LabelTypesEnum"},"title":"Label Types","type":"array"},"line_item_ids":{"description":"The line item IDs to which the label should be attached","items":{"type":"string"},"title":"Line Item IDs","type":"array"},"additional_fields":{"additionalProperties":true,"description":"Custom fields to pass through to label generation and returns document.","title":"Additional Fields","type":"object"}},"required":["type","courier"],"title":"AddLabelRequest","type":"object"},"ReturnLabelTypeEnum":{"enum":["shipping","custom"],"title":"ReturnLabelTypeEnum","type":"string"},"AddressSchema":{"properties":{"first_name":{"title":"First Name","type":"string"},"last_name":{"title":"Last Name","type":"string"},"company_name":{"title":"Company Name, if any","type":"string"},"address_line":{"description":"Address line, e.g. street and house number, or PO Box","maxLength":256,"minLength":1,"title":"Address Line","type":"string"},"address_line_extra":{"description":"Additional address line, e.g. apartment number or company name","title":"Additional Address Line","type":"string"},"postal_code":{"maxLength":10,"minLength":2,"title":"Postal Code","type":"string"},"city":{"description":"City name (min-length of 1 due to logographic languages)","maxLength":40,"minLength":1,"title":"City","type":"string"},"country_iso3":{"description":"ISO 3166-1 alpha-3 code of country","pattern":"^\\w{3}$","title":"Country ISO3","type":"string"},"region_code":{"description":"Region code, e.g. state or province code (ISO 3166-2), if available","maxLength":25,"minLength":1,"title":"Region Code","type":"string"},"phone":{"description":"Phone number related to this address, if any","maxLength":30,"title":"Phone","type":"string"}},"required":["address_line","postal_code","city","country_iso3"],"title":"Address","type":"object"},"AddLabelFlagsEnum":{"enum":["has_dangerous_goods","is_pickup"],"type":"string"},"LabelTypesEnum":{"enum":["code","print"],"type":"string"},"UpdateItemMutation":{"description":"Update registered article items","properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"update_items","default":"update_items","title":"Type","type":"string"},"items":{"description":"Items for this return registration after update is a applied","items":{"$ref":"#/components/schemas/LineItemReturn"},"title":"Line Items to return","type":"array"}},"title":"Update Items Mutation","type":"object"},"LineItemReturn":{"additionalProperties":true,"properties":{"version":{"$ref":"#/components/schemas/LineItemVersionEnum","description":"Optional. Omit this key unless absolutely intended. The standard value is `v2`. If you send `version`, send `v2`.","title":"Version"},"line_item_id":{"description":"Retailer ID of the line item, only the last number part of the whole line item id string","title":"Line Item ID","type":"string"},"product_id":{"description":"Parent product identifier in the retailer's system (shared across variants).","title":"Product ID","type":"string"},"variant_id":{"description":"SKU/variant identifier; prefer for matching when available since parent product IDs are reused across variants.","title":"Variant ID","type":"string"},"sku":{"description":"Stock Keeping Unit of the line item","title":"SKU","type":"string"},"barcode":{"description":"Barcode associated with the line item variant or product","title":"Barcode","type":"string"},"order_item_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Line Item ID in the order, the whole id of the fulfillment line item","title":"Order Line Item ID"},"article_name":{"description":"Name of the article","title":"Article Name","type":"string"},"article_category":{"description":"Category of the article","title":"Article Category","type":"string"},"article_store_url":{"description":"URL to the article in the store","title":"Article Store URL","type":"string"},"article_image_url":{"description":"URL to the image of the article","title":"Article Image URL","type":"string"},"article_brand":{"description":"Brand of the article (reference only)","title":"Article Brand","type":"string"},"size":{"description":"Size of the article (reference only)","title":"Size","type":"string"},"color":{"description":"Color of the article (reference only)","title":"Color","type":"string"},"width":{"description":"Width of the article (in millimeters)","title":"Width","type":"number"},"height":{"description":"Height of the article (in millimeters)","title":"Height","type":"number"},"length":{"description":"Length of the article (in millimeters)","title":"Length","type":"number"},"length_unit":{"const":"cm","default":"cm","title":"Length Unit","type":"string"},"weight":{"description":"Weight of the article (in grams, kg, lbs, or oz)","title":"Weight","type":"number"},"weight_unit":{"allOf":[{"$ref":"#/components/schemas/WeightUnitEnum"}],"default":"g","title":"Weight Unit"},"unit_price":{"description":"Paid unit price of the article (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Unit Price","type":"string"},"unit_price_original":{"description":"Original unit price of the article (pre-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Unit Price","type":"string"},"quantity":{"description":"Unit quantity of the article","title":"Unit Quantity","type":"integer"},"amount_invoiced":{"description":"Paid line total amount for this line item (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Invoiced","type":"string"},"tax_amount":{"description":"Total tax amount for this line item (regardless of taxesIncluded)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Tax Amount","type":"string"},"harmonized_system_code":{"description":"HS/HTS code for customs classification","title":"Harmonized System Code","type":"string"},"origin_country_iso3":{"description":"ISO 3166-1 alpha-3 code of articles country of origin, might be required based on shipment regulations","pattern":"^\\w{3}$","title":"Origin Country ISO3","type":"string"},"is_bulky":{"default":false,"description":"If the article is bulky","title":"Is Bulky","type":"boolean"},"tags":{"description":"Tags for the line item, e.g. 'category:home-apparel', or 'customergroup:vip'","items":{"type":"string"},"title":"Tags","type":"array"},"bundle":{"anyOf":[{"$ref":"#/components/schemas/BundleInfo"},{"type":"null"}],"default":null,"description":"Bundle relationship metadata when the item is part of a bundle.","title":"Bundle Info"},"additional_attributes":{"description":"Additional attributes for this line item","items":{"$ref":"#/components/schemas/AdditionalAttribute"},"title":"Additional Attributes","type":"array"},"unit_price_msrp_current":{"anyOf":[{"pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","type":"string"},{"type":"null"}],"default":null,"description":"Current catalog/MSRP unit price for the same variant.","title":"Current MSRP"},"reference_date_for_return":{"description":"The date, which is used to evaluate the line item return period","format":"date","title":"Reference Date for Return","type":"string"},"reference_date_type":{"allOf":[{"$ref":"#/components/schemas/ReferenceDateTypeEnum"}],"description":"The date type, which is used to evaluate the line item return period","title":"Reference Date Type"},"fulfillment":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Id of the fulfillment that this item belongs to","title":"Fulfillment"},"quantity_returned":{"description":"Quantity of already returned items in this line.","title":"Quantity Returned","type":"integer"},"delivered_date":{"description":"Date when the line item was delivered (same as the fulfillment delivered date)","format":"date","title":"Delivered Date","type":"string"},"return_reason":{"description":"Full return reason path (as configured in the respective return configuration for this object)","title":"Return Reason","type":"string"},"return_reason_pretty":{"description":"Pretty text for the return reason, e.g. 'Doesn't Fit'","title":"Return Reason Pretty","type":"string"},"return_quantity":{"description":"Quantity to be returned","title":"Return Quantity","type":"integer"},"problem_description":{"description":"Description of the problem with this line item","title":"Problem Description","type":"string"},"condition":{"description":"Article condition, if provided","title":"Condition","type":"string"},"article_images":{"items":{"$ref":"#/components/schemas/ReturnImage"},"title":"Article Images","type":"array"},"compensation_method":{"description":"Compensation method for this line item, e.g. exchange, refund, credit","title":"Compensation Method","type":"string"},"accepted_quantity":{"description":"Quantity of the article that was accepted by warehouse","title":"Accepted Quantity","type":"integer"},"rejected_quantity":{"description":"Quantity of the article that was rejected by warehouse","title":"Rejected Quantity","type":"integer"},"status_reason":{"description":"Reason for the rejection / acceptance of the article","title":"Rejection or Acceptance Reason","type":"string"},"status_reason_code":{"description":"Structured reason code, e.g. quality_issue","title":"Status Reason Code","type":"string"},"return_reason_code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Final code of return reason (leaf code)","readOnly":true,"title":"Return Reason Code"}},"required":["line_item_id","return_reason_code"],"title":"Line Item","type":"object"},"LineItemVersionEnum":{"enum":["v1","v2"],"title":"LineItemVersionEnum","type":"string"},"WeightUnitEnum":{"enum":["kg","g","lbs","oz"],"type":"string"},"BundleInfo":{"additionalProperties":true,"properties":{"group_id":{"description":"Bundle group identifier in the retailer's system.","title":"Bundle Group ID","type":"string"},"role":{"$ref":"#/components/schemas/BundleRoleEnum","description":"Whether this line item represents a bundle parent or a bundle component.","title":"Bundle Role"},"return_policy":{"$ref":"#/components/schemas/BundleReturnPolicyEnum","default":"components_only","description":"Which lines in this bundle group are selectable for return.","title":"Bundle Return Policy"},"parent_product_id":{"description":"Parent bundle product identifier in the retailer's system.","title":"Bundle Parent Product ID","type":"string"},"parent_variant_id":{"description":"Parent bundle variant identifier in the retailer's system.","title":"Bundle Parent Variant ID","type":"string"},"parent_sku":{"description":"Parent bundle SKU, if available.","title":"Bundle Parent SKU","type":"string"},"parent_title":{"description":"Display title for the bundle parent, if available.","title":"Bundle Parent Title","type":"string"},"parent_quantity":{"description":"Quantity of the bundle parent purchased in the order.","title":"Bundle Parent Quantity","type":"integer"},"component_quantity_per_parent":{"description":"Component quantity per single bundle parent (if determinable).","title":"Bundle Component Quantity Per Parent","type":"integer"},"allocation_method":{"$ref":"#/components/schemas/BundleAllocationMethodEnum","default":"none","description":"How pricing was allocated to bundle components.","title":"Bundle Allocation Method"},"allocated_unit_price":{"description":"Snapshot of allocated component unit price (if derived from bundle totals).","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Allocated Unit Price","type":"string"},"allocated_amount_invoiced":{"description":"Snapshot of allocated component invoiced amount (if derived from bundle totals).","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Allocated Amount Invoiced","type":"string"}},"required":["group_id","role"],"title":"Bundle Info","type":"object"},"BundleRoleEnum":{"enum":["parent","component"],"title":"BundleRoleEnum","type":"string"},"BundleReturnPolicyEnum":{"enum":["parent_only","components_only","parent_and_components"],"title":"BundleReturnPolicyEnum","type":"string"},"BundleAllocationMethodEnum":{"enum":["none","component_price","msrp_ratio","equal"],"title":"BundleAllocationMethodEnum","type":"string"},"AdditionalAttribute":{"properties":{"key":{"description":"The key of the additional attribute","title":"Key","type":"string"},"value":{"default":null,"description":"The value of the additional attribute","title":"Value"}},"required":["key"],"title":"AdditionalAttribute","type":"object"},"ReferenceDateTypeEnum":{"enum":["order_date","shipping_date","delivery_date"],"type":"string"},"ReturnImage":{"properties":{"url":{"title":"Url","type":"string"},"name":{"title":"Name","type":"string"},"mime_type":{"title":"Mime Type","type":"string"}},"required":["url","name","mime_type"],"title":"ReturnImage","type":"object"},"CloseReturnMutation":{"description":"Close a return registration (finalize return + refund).","properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"close_return","default":"close_return","title":"Type","type":"string"},"status_reason":{"description":"Optional reason for closing the return registration.","title":"Status Reason","type":"string"},"trigger_refund":{"description":"Whether to issue a monetary refund when closing the return.","title":"Trigger Refund","type":"boolean"},"release_exchange_items":{"description":"Whether to release exchange items when closing the return.","title":"Release Exchange Items","type":"boolean"},"refund_shipping_fees":{"description":"Whether to refund the original order shipping cost.","title":"Refund Shipping Fees","type":"boolean"},"tracking_number":{"description":"Optional tracking number used for receive-status synchronization when article status updates are provided.","title":"Tracking Number","type":"string"},"received_by":{"description":"Optional source shown in receive status when article status updates are provided. Defaults to API (close_return mutation).","title":"Received By","type":"string"},"receive_note":{"description":"Optional receive note stored with receive status and synchronized to tracking returnReceive.note when article status updates are provided.","title":"Receive Note","type":"string"},"article_status_updates":{"description":"Optional receive-style article status updates to apply before closing the return registration.","items":{"$ref":"#/components/schemas/ArticleStatusUpdate"},"title":"Article Status Updates","type":"array"}},"title":"CloseReturnMutation","type":"object"},"ArticleStatusUpdate":{"properties":{"identifier":{"description":"Identifier of the article to update the status for","title":"Identifier of article","type":"string"},"identifier_type":{"$ref":"#/components/schemas/ArticleIdentifierType","description":"The type of the identifier","title":"Identifier Type"},"accepted_quantity":{"default":0,"description":"The quantity of the article that was accepted","title":"Accepted Quantity","type":"integer"},"rejected_quantity":{"default":0,"description":"The quantity of the article that was rejected","title":"Rejected Quantity","type":"integer"},"reason":{"default":null,"description":"The reason for the rejection of the article","title":"Reason","type":"string"}},"required":["identifier","identifier_type"],"title":"ArticleStatusUpdate","type":"object"},"ArticleIdentifierType":{"enum":["product_id","line_item_id","sku","variant_id","barcode","order_item_id"],"title":"ArticleIdentifierType","type":"string"},"CancelReturnMutation":{"description":"Cancel a return registration and its tracking.","properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"cancel_return","default":"cancel_return","title":"Type","type":"string"},"status_reason":{"description":"Optional reason for cancelling the return registration.","title":"Status Reason","type":"string"}},"title":"CancelReturnMutation","type":"object"},"ReturnRegistration":{"type":"object","description":"Represents a return registration","properties":{"account":{"type":"integer","description":"Account, that is linked to this registration."},"code":{"type":"string","title":"Configuration Code","description":"Configuration code of the return configuration","maxLength":255},"version":{"type":["string","null"]},"client_key":{"type":"string","readOnly":true,"description":"Name of the client, as configured in account setup."},"reference":{"type":"string","title":"Reference / Order Number","description":"Retailer reference, e.g. the order number, not unique","maxLength":255},"external_id":{"type":"string","format":"uuid","title":"External Identifier","description":"Unique identifier for this return registration, generated by parcelLab"},"external_reference":{"type":"string","description":"Additional identifier (e.g. shop system id) for this return registration, generated by the retailer","maxLength":255},"sequence_number":{"type":"string","readOnly":true},"status":{"$ref":"#/components/schemas/ReturnRegistrationStatusEnum"},"status_reason":{"type":"string","description":"Reason for the current status","maxLength":255},"original_courier":{"type":"string","maxLength":255},"original_order_id":{"type":["string","null"],"maxLength":255},"order_date":{"type":["string","null"],"format":"date-time","description":"Date of the order"},"order_currency":{"type":"string","description":"Currency of the order, e.g. USD, EUR (ISO 4217)","maxLength":3},"order_total_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Total amount of the original order"},"order_shipping_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Total shipping amount of the original order"},"order_tax_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Total tax amount of the original order"},"order_delivery_date":{"type":["string","null"],"format":"date-time","description":"Date of the order delivery"},"order_shipping_date":{"type":["string","null"],"format":"date-time","description":"Date of the order shipment"},"order_payment_method":{"type":"array","items":{"type":"string","maxLength":255},"description":"Payment method used for the order, as setup as reference items in the accounts configuration"},"language_iso2":{"type":"string","description":"ISO 639-1 language code of the recipient, if known, required for localized communication","maxLength":3},"is_gift_returns_portal":{"type":"boolean","readOnly":true},"customer_email":{"anyOf":[{"format":"email","type":"string"},{"const":"_unset","enum":["_unset"],"type":"string"}],"description":"Customers email address, must be provided, in case email is not known or should be unset, use the literal string '_unset' instead."},"customer_phone":{"type":"string","description":"Customer phone number","maxLength":255},"customer_salutation":{"type":"string","maxLength":255},"customer_first_name":{"type":"string","maxLength":255},"customer_last_name":{"type":"string","maxLength":255},"customer_country_iso3":{"type":"string","description":"ISO 3166-1 alpha-3 code of country","maxLength":3},"customer_address":{"anyOf":[{"$ref":"#/components/schemas/ValidatedAddressSchema"},{"$ref":"#/components/schemas/Empty"}]},"articles_order":{"items":{"$ref":"#/components/schemas/LineItem"},"type":"array"},"articles_return":{"items":{"$ref":"#/components/schemas/LineItemReturn"},"type":"array"},"return_labels":{"items":{"$ref":"#/components/schemas/ReturnLabel"},"type":"array","readOnly":true},"refund_method":{"type":"string","description":"Refund method selected by customer","maxLength":255},"tags":{"type":"array","items":{"type":"string","maxLength":255},"description":"Order level tags."},"additional_fields":{"type":"object","additionalProperties":{},"description":"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":{"type":"string","description":"Verification code (e.g. zip/email) used for this return registration","maxLength":255},"created_at":{"type":"string","format":"date-time","readOnly":true},"updated_at":{"type":"string","format":"date-time","readOnly":true},"mutations":{"items":{"anyOf":[{"$ref":"#/components/schemas/AddLabelMutation"},{"$ref":"#/components/schemas/UpdateItemMutation"},{"$ref":"#/components/schemas/CloseReturnMutation"},{"$ref":"#/components/schemas/CancelReturnMutation"}],"title":"Mutations"},"type":"array"}},"required":["account","client_key","code","created_at","customer_address","customer_email","is_gift_returns_portal","reference","return_labels","sequence_number","updated_at"]},"ReturnRegistrationStatusEnum":{"enum":["created","submitted","pending_approval","pending_label","approved","rejected","cancelled","closed","processing_failed","invalid"],"type":"string","description":"* `created` - Created\n* `submitted` - Submitted\n* `pending_approval` - Pending Approval\n* `pending_label` - Pending Label\n* `approved` - Approved\n* `rejected` - Rejected\n* `cancelled` - Cancelled\n* `closed` - Closed\n* `processing_failed` - Processing Failed\n* `invalid` - Invalid"},"ValidatedAddressSchema":{"properties":{"first_name":{"title":"First Name","type":"string"},"last_name":{"title":"Last Name","type":"string"},"company_name":{"title":"Company Name, if any","type":"string"},"address_line":{"description":"Address line, e.g. street and house number, or PO Box","maxLength":256,"minLength":1,"title":"Address Line","type":"string"},"address_line_extra":{"description":"Additional address line, e.g. apartment number or company name","title":"Additional Address Line","type":"string"},"postal_code":{"maxLength":10,"minLength":2,"title":"Postal Code","type":"string"},"city":{"description":"City name (min-length of 1 due to logographic languages)","maxLength":40,"minLength":1,"title":"City","type":"string"},"country_iso3":{"description":"ISO 3166-1 alpha-3 code of country","pattern":"^\\w{3}$","title":"Country ISO3","type":"string"},"region_code":{"description":"Region code, e.g. state or province code (ISO 3166-2), if available","maxLength":25,"minLength":1,"title":"Region Code","type":"string"},"phone":{"description":"Phone number related to this address, if any","maxLength":30,"title":"Phone","type":"string"}},"required":["address_line","postal_code","city","country_iso3"],"title":"Address","type":"object"},"Empty":{"additionalProperties":false,"properties":{},"title":"Empty","type":"object"},"LineItem":{"additionalProperties":true,"properties":{"version":{"$ref":"#/components/schemas/LineItemVersionEnum","description":"Optional. Omit this key unless absolutely intended. The standard value is `v2`. If you send `version`, send `v2`.","title":"Version"},"line_item_id":{"description":"Retailer ID of the line item","title":"Line Item ID","type":"string"},"product_id":{"description":"Parent product identifier in the retailer's system (shared across variants).","title":"Product ID","type":"string"},"variant_id":{"description":"SKU/variant identifier; prefer for matching when available since parent product IDs are reused across variants.","title":"Variant ID","type":"string"},"sku":{"description":"Stock Keeping Unit of the line item","title":"SKU","type":"string"},"barcode":{"description":"Barcode associated with the line item variant or product","title":"Barcode","type":"string"},"order_item_id":{"description":"Line Item ID in the order (preferred when provided)","title":"Order Line Item ID","type":"string"},"article_name":{"description":"Name of the article","title":"Article Name","type":"string"},"article_category":{"description":"Category of the article","title":"Article Category","type":"string"},"article_store_url":{"description":"URL to the article in the store","title":"Article Store URL","type":"string"},"article_image_url":{"description":"URL to the image of the article","title":"Article Image URL","type":"string"},"article_brand":{"description":"Brand of the article (reference only)","title":"Article Brand","type":"string"},"size":{"description":"Size of the article (reference only)","title":"Size","type":"string"},"color":{"description":"Color of the article (reference only)","title":"Color","type":"string"},"width":{"description":"Width of the article (in millimeters)","title":"Width","type":"number"},"height":{"description":"Height of the article (in millimeters)","title":"Height","type":"number"},"length":{"description":"Length of the article (in millimeters)","title":"Length","type":"number"},"length_unit":{"const":"cm","default":"cm","title":"Length Unit","type":"string"},"weight":{"description":"Weight of the article (in grams, kg, lbs, or oz)","title":"Weight","type":"number"},"weight_unit":{"allOf":[{"$ref":"#/components/schemas/WeightUnitEnum"}],"default":"g","title":"Weight Unit"},"unit_price":{"description":"Paid unit price of the article (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Unit Price","type":"string"},"unit_price_original":{"description":"Original unit price of the article (pre-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Unit Price","type":"string"},"quantity":{"description":"Unit quantity of the article","title":"Unit Quantity","type":"integer"},"amount_invoiced":{"description":"Paid line total amount for this line item (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Invoiced","type":"string"},"tax_amount":{"description":"Total tax amount for this line item (regardless of taxesIncluded)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Tax Amount","type":"string"},"harmonized_system_code":{"description":"HS/HTS code for customs classification","title":"Harmonized System Code","type":"string"},"origin_country_iso3":{"description":"ISO 3166-1 alpha-3 code of articles country of origin, might be required based on shipment regulations","pattern":"^\\w{3}$","title":"Origin Country ISO3","type":"string"},"is_bulky":{"default":false,"description":"If the article is bulky","title":"Is Bulky","type":"boolean"},"tags":{"description":"Tags for the line item, e.g. 'category:home-apparel', or 'customergroup:vip'","items":{"type":"string"},"title":"Tags","type":"array"},"bundle":{"anyOf":[{"$ref":"#/components/schemas/BundleInfo"},{"type":"null"}],"default":null,"description":"Bundle relationship metadata when the item is part of a bundle.","title":"Bundle Info"},"additional_attributes":{"description":"Additional attributes for this line item","items":{"$ref":"#/components/schemas/AdditionalAttribute"},"title":"Additional Attributes","type":"array"}},"required":["line_item_id"],"title":"Line Item","type":"object"},"ReturnLabel":{"properties":{"courier":{"description":"Return label courier code or drop-off code, e.g. barcode","title":"Return Label Courier","type":"string"},"service_level":{"description":"Service level of the return label","title":"Service Level","type":"string"},"tracking_number":{"description":"Tracking number of the return label (or in case of Barcode the barcode)","title":"Tracking number","type":"string"},"type":{"$ref":"#/components/schemas/ReturnLabelTypeEnum","default":"shipping","description":"Type of the return label, e.g. 'shipping' for a real courier label, or barcode for a (custom) drop-off code","title":"Label Type"},"flags":{"description":"Flags (extra markers) for the return label, such as 'has_dangerous_goods', or 'is_pickup'","items":{"$ref":"#/components/schemas/ReturnLabelFlagsEnum"},"title":"Label Flags","type":"array"},"documents":{"description":"Documents related to this return label (e.g. print label, barcode, packing slip, wallet-passes)","items":{"$ref":"#/components/schemas/Document"},"title":"Label","type":"array"},"locations_url":{"description":"URL to a courier-specific location finder page.","title":"Locations URL","type":"string"},"destination_id":{"description":"Destination ID for the return label, e.g. warehouse code","title":"Destination ID","type":"string"},"line_item_ids":{"description":"The line item IDs to which the label should be attached","items":{"type":"string"},"title":"Line Item IDs","type":"array"},"is_free_label":{"default":false,"description":"Indicates if the return label is free of charge","title":"Is Free Label","type":"boolean"},"label_cost_amount":{"default":"0.0","description":"Cost of the return label","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Label Cost Amount","type":"string"},"tracking_id":{"description":"Tracking ID of the shipment in the parcelLab system","title":"ParcelLab Tracking ID","type":"string"},"external_reference":{"description":"Unique retailer-provided reference of the shipment, either this tracking number is required","title":"External Reference","type":"string"},"delivery_status":{"$ref":"#/components/schemas/TrackingStageChoices","default":"Pending","description":"Current shipping stage of the return label","title":"Current Shipping Stage"},"pickup_date":{"description":"Scheduled pickup date for the return label. Nullable if not a pickup return.","format":"date","title":"Pickup Date","type":"string"},"earliest_pickup_time":{"description":"Earliest scheduled pickup time for the return label. Nullable if not a pickup return.","format":"time","title":"Earliest Pickup Time","type":"string"},"latest_pickup_time":{"description":"Latest scheduled pickup time for the return label. Nullable if not a pickup return.","format":"time","title":"Latest Pickup Time","type":"string"},"pickup_confirmation_code":{"description":"Confirmation code customer must present on pickup","title":"Pickup Confirmation Code","type":"string"},"is_pickup":{"default":false,"description":"Indicates if the return is a pickup order.","title":"Is Pickup","type":"boolean"},"configuration_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Selected return option mapping ID used to create this label.","title":"Courier Mapping ID"}},"required":["courier","tracking_number"],"title":"Return Label","type":"object"},"ReturnLabelFlagsEnum":{"enum":["is_cancellable","is_pickup","has_dangerous_goods"],"type":"string"},"Document":{"properties":{"url":{"description":"URL to the document, in most cases this is a http URL, but it could also be a data URL (base64)","title":"Document URL","type":"string"},"content_type":{"default":"application/pdf","description":"MIME content type of the document, e.g. 'application/pdf'","title":"Content Type","type":"string"},"type":{"default":[],"description":"Type or types of the document, maybe multiple, if bundled","items":{"$ref":"#/components/schemas/DocumentTypeEnum"},"title":"Document Type","type":"array"},"expires_at":{"description":"Expiry date of the document, after which it might not be retrievable","format":"date-time","title":"Document expiry date","type":"string"}},"required":["url"],"title":"Document","type":"object"},"DocumentTypeEnum":{"enum":["label","packing_slip","barcode","customs_document","wallet_pass_io","wallet_pass_android","commercial_invoice"],"type":"string"},"TrackingStageChoices":{"enum":["Pending","Transit","Customs","LastMile","ReadyToCollect","Delivered","SentBack","Returned","Failed","Cancelled"],"title":"TrackingStageChoices","type":"string"},"Error400Response":{"type":"object","properties":{"type":{"type":"string"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/GenericErrorItem"}}},"required":["errors","type"]},"GenericErrorItem":{"type":"object","properties":{"code":{"type":"string"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["code","detail"]},"ErrorResponse403":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ClientErrorEnum"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error403"}}},"required":["errors","type"]},"ClientErrorEnum":{"enum":["client_error"],"type":"string","description":"* `client_error` - Client Error"},"Error403":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode403Enum"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["attr","code","detail"]},"ErrorCode403Enum":{"enum":["permission_denied"],"type":"string","description":"* `permission_denied` - Permission Denied"},"ErrorResponse404":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ClientErrorEnum"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error404"}}},"required":["errors","type"]},"Error404":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode404Enum"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["attr","code","detail"]},"ErrorCode404Enum":{"enum":["not_found"],"type":"string","description":"* `not_found` - Not Found"}}},"paths":{"/v4/returns/return-registrations/{external_id}/mutate/":{"post":{"operationId":"returns_return_registrations_mutate_create","description":"Mutate this return registration with one of the available mutations","summary":"Mutate Return Registration","parameters":[{"in":"path","name":"external_id","schema":{"type":"string","format":"uuid","title":"External Identifier","description":"Unique identifier for this return registration, generated by parcelLab"},"required":true}],"tags":["Return Registration"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MutateReturnRegistrationRequest"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/MutateReturnRegistrationRequest"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/MutateReturnRegistrationRequest"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnRegistration"}}},"description":""},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}},"description":""},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse403"}}},"description":""},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"description":""}}}}}} ``` ## Modify Return Registrations You can use the available mutations (for example: generate a label) to update return registrations using the `v4/returns/return-registrations/mutate` endpoint. ## Mutate Return Registration (Batch) > 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. ```json {"openapi":"3.1.0","info":{"title":"parcelLab API","version":"v4"},"security":[{"OAuth2 Authentication":[]},{"HeaderToken":[]}],"components":{"securitySchemes":{"OAuth2 Authentication":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"HeaderToken":{"type":"http","scheme":"bearer","bearerFormat":"Parcellab-API-Token base64(account_id:token)","description":"Send `Authorization: Parcellab-API-Token `.\n\n`` = `base64(account_id:token)` as provided in the portal."}},"schemas":{"MutateReturnRegistrationCollectionRequest":{"type":"object","description":"Update (mutate) a return registration","properties":{"mutations":{"items":{"$ref":"#/components/schemas/UpdateArticleStatusMutation","title":"Mutations"},"type":"array","writeOnly":true}}},"UpdateArticleStatusMutation":{"properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"update_article_status","default":"update_article_status","title":"Type","type":"string"},"account":{"description":"The account ID to create this return registration on.","title":"Account ID","type":"integer"},"request":{"$ref":"#/components/schemas/UpdateArticleStatusRequest","description":"Container for article receive status updates to a single return / tracking.","title":"Update status request"}},"required":["account","request"],"title":"UpdateArticleStatusMutation","type":"object"},"MutationResult":{"description":"The result of a mutation","properties":{"success":{"default":false,"description":"Whether the mutation was successful","title":"Success","type":"boolean"},"message":{"default":"","description":"A message describing the result of the mutation","title":"Message","type":"string"},"errors":{"additionalProperties":{"type":"string"},"description":"A dictionary of errors that occurred during the mutation","title":"Errors","type":"object"},"warnings":{"description":"Non-fatal warnings raised while processing the mutation","items":{"type":"string"},"title":"Warnings","type":"array"}},"title":"MutationResult","type":"object"},"UpdateArticleStatusRequest":{"properties":{"identifier":{"description":"Identifier of the return registration to update the status for","title":"Identifier of RMA (return registration), e.g. reference_number","type":"string"},"identifier_type":{"$ref":"#/components/schemas/RegistrationIdentifierType","description":"The type of the identifier","title":"Identifier Type"},"tracking_number":{"description":"The tracking number to update the status for","title":"Tracking Number","type":"string"},"article_status_updates":{"description":"The status updates for the articles","items":{"$ref":"#/components/schemas/ArticleStatusUpdate"},"title":"Article Status Updates","type":"array"},"receive_status":{"$ref":"#/components/schemas/ReceiveStatus","description":"Structured receive status fields used for downstream tracking updates.","title":"Receive Status"}},"required":["identifier","identifier_type","tracking_number","receive_status"],"title":"UpdateArticleStatusRequest","type":"object"},"RegistrationIdentifierType":{"enum":["reference","external_id","external_reference"],"title":"RegistrationIdentifierType","type":"string"},"ArticleStatusUpdate":{"properties":{"identifier":{"description":"Identifier of the article to update the status for","title":"Identifier of article","type":"string"},"identifier_type":{"$ref":"#/components/schemas/ArticleIdentifierType","description":"The type of the identifier","title":"Identifier Type"},"accepted_quantity":{"default":0,"description":"The quantity of the article that was accepted","title":"Accepted Quantity","type":"integer"},"rejected_quantity":{"default":0,"description":"The quantity of the article that was rejected","title":"Rejected Quantity","type":"integer"},"reason":{"default":null,"description":"The reason for the rejection of the article","title":"Reason","type":"string"}},"required":["identifier","identifier_type"],"title":"ArticleStatusUpdate","type":"object"},"ArticleIdentifierType":{"enum":["product_id","line_item_id","sku","variant_id","barcode","order_item_id"],"title":"ArticleIdentifierType","type":"string"},"ReceiveStatus":{"description":"Receive status data stored when a return is processed via the staff receive flow.","properties":{"received_by":{"default":"","description":"Identifier of the operator or station that received the return.","title":"Received By","type":"string"},"received_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"description":"Timestamp when the return was fully received.","title":"Received At"},"status":{"$ref":"#/components/schemas/ReceiveOverallStatus","default":"partially_received","description":"Overall receive status for the return.","title":"Receive Status"},"receive_note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Optional note recorded during receive.","title":"Receive Note"},"receive_images":{"description":"URLs of captured evidence images.","items":{"$ref":"#/components/schemas/ReturnImage"},"title":"Receive Images","type":"array"},"is_fully_received":{"default":true,"description":"Whether the return is fully processed in receive flow.","title":"Is Fully Received","type":"boolean"},"label_notes":{"additionalProperties":{"type":"string"},"description":"Internal notes keyed by tracking number.","title":"Label Notes","type":"object"}},"title":"ReceiveStatus","type":"object"},"ReceiveOverallStatus":{"enum":["completely_rejected","completely_accepted","partially_accepted","partially_received"],"title":"ReceiveOverallStatus","type":"string"},"ReturnImage":{"properties":{"url":{"title":"Url","type":"string"},"name":{"title":"Name","type":"string"},"mime_type":{"title":"Mime Type","type":"string"}},"required":["url","name","mime_type"],"title":"ReturnImage","type":"object"},"ReturnRegistration":{"type":"object","description":"Represents a return registration","properties":{"account":{"type":"integer","description":"Account, that is linked to this registration."},"code":{"type":"string","title":"Configuration Code","description":"Configuration code of the return configuration","maxLength":255},"version":{"type":["string","null"]},"client_key":{"type":"string","readOnly":true,"description":"Name of the client, as configured in account setup."},"reference":{"type":"string","title":"Reference / Order Number","description":"Retailer reference, e.g. the order number, not unique","maxLength":255},"external_id":{"type":"string","format":"uuid","title":"External Identifier","description":"Unique identifier for this return registration, generated by parcelLab"},"external_reference":{"type":"string","description":"Additional identifier (e.g. shop system id) for this return registration, generated by the retailer","maxLength":255},"sequence_number":{"type":"string","readOnly":true},"status":{"$ref":"#/components/schemas/ReturnRegistrationStatusEnum"},"status_reason":{"type":"string","description":"Reason for the current status","maxLength":255},"original_courier":{"type":"string","maxLength":255},"original_order_id":{"type":["string","null"],"maxLength":255},"order_date":{"type":["string","null"],"format":"date-time","description":"Date of the order"},"order_currency":{"type":"string","description":"Currency of the order, e.g. USD, EUR (ISO 4217)","maxLength":3},"order_total_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Total amount of the original order"},"order_shipping_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Total shipping amount of the original order"},"order_tax_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d{0,8}(?:\\.\\d{0,2})?$","description":"Total tax amount of the original order"},"order_delivery_date":{"type":["string","null"],"format":"date-time","description":"Date of the order delivery"},"order_shipping_date":{"type":["string","null"],"format":"date-time","description":"Date of the order shipment"},"order_payment_method":{"type":"array","items":{"type":"string","maxLength":255},"description":"Payment method used for the order, as setup as reference items in the accounts configuration"},"language_iso2":{"type":"string","description":"ISO 639-1 language code of the recipient, if known, required for localized communication","maxLength":3},"is_gift_returns_portal":{"type":"boolean","readOnly":true},"customer_email":{"anyOf":[{"format":"email","type":"string"},{"const":"_unset","enum":["_unset"],"type":"string"}],"description":"Customers email address, must be provided, in case email is not known or should be unset, use the literal string '_unset' instead."},"customer_phone":{"type":"string","description":"Customer phone number","maxLength":255},"customer_salutation":{"type":"string","maxLength":255},"customer_first_name":{"type":"string","maxLength":255},"customer_last_name":{"type":"string","maxLength":255},"customer_country_iso3":{"type":"string","description":"ISO 3166-1 alpha-3 code of country","maxLength":3},"customer_address":{"anyOf":[{"$ref":"#/components/schemas/ValidatedAddressSchema"},{"$ref":"#/components/schemas/Empty"}]},"articles_order":{"items":{"$ref":"#/components/schemas/LineItem"},"type":"array"},"articles_return":{"items":{"$ref":"#/components/schemas/LineItemReturn"},"type":"array"},"return_labels":{"items":{"$ref":"#/components/schemas/ReturnLabel"},"type":"array","readOnly":true},"refund_method":{"type":"string","description":"Refund method selected by customer","maxLength":255},"tags":{"type":"array","items":{"type":"string","maxLength":255},"description":"Order level tags."},"additional_fields":{"type":"object","additionalProperties":{},"description":"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":{"type":"string","description":"Verification code (e.g. zip/email) used for this return registration","maxLength":255},"created_at":{"type":"string","format":"date-time","readOnly":true},"updated_at":{"type":"string","format":"date-time","readOnly":true},"mutations":{"items":{"anyOf":[{"$ref":"#/components/schemas/AddLabelMutation"},{"$ref":"#/components/schemas/UpdateItemMutation"},{"$ref":"#/components/schemas/CloseReturnMutation"},{"$ref":"#/components/schemas/CancelReturnMutation"}],"title":"Mutations"},"type":"array"}},"required":["account","client_key","code","created_at","customer_address","customer_email","is_gift_returns_portal","reference","return_labels","sequence_number","updated_at"]},"ReturnRegistrationStatusEnum":{"enum":["created","submitted","pending_approval","pending_label","approved","rejected","cancelled","closed","processing_failed","invalid"],"type":"string","description":"* `created` - Created\n* `submitted` - Submitted\n* `pending_approval` - Pending Approval\n* `pending_label` - Pending Label\n* `approved` - Approved\n* `rejected` - Rejected\n* `cancelled` - Cancelled\n* `closed` - Closed\n* `processing_failed` - Processing Failed\n* `invalid` - Invalid"},"ValidatedAddressSchema":{"properties":{"first_name":{"title":"First Name","type":"string"},"last_name":{"title":"Last Name","type":"string"},"company_name":{"title":"Company Name, if any","type":"string"},"address_line":{"description":"Address line, e.g. street and house number, or PO Box","maxLength":256,"minLength":1,"title":"Address Line","type":"string"},"address_line_extra":{"description":"Additional address line, e.g. apartment number or company name","title":"Additional Address Line","type":"string"},"postal_code":{"maxLength":10,"minLength":2,"title":"Postal Code","type":"string"},"city":{"description":"City name (min-length of 1 due to logographic languages)","maxLength":40,"minLength":1,"title":"City","type":"string"},"country_iso3":{"description":"ISO 3166-1 alpha-3 code of country","pattern":"^\\w{3}$","title":"Country ISO3","type":"string"},"region_code":{"description":"Region code, e.g. state or province code (ISO 3166-2), if available","maxLength":25,"minLength":1,"title":"Region Code","type":"string"},"phone":{"description":"Phone number related to this address, if any","maxLength":30,"title":"Phone","type":"string"}},"required":["address_line","postal_code","city","country_iso3"],"title":"Address","type":"object"},"Empty":{"additionalProperties":false,"properties":{},"title":"Empty","type":"object"},"LineItem":{"additionalProperties":true,"properties":{"version":{"$ref":"#/components/schemas/LineItemVersionEnum","description":"Optional. Omit this key unless absolutely intended. The standard value is `v2`. If you send `version`, send `v2`.","title":"Version"},"line_item_id":{"description":"Retailer ID of the line item","title":"Line Item ID","type":"string"},"product_id":{"description":"Parent product identifier in the retailer's system (shared across variants).","title":"Product ID","type":"string"},"variant_id":{"description":"SKU/variant identifier; prefer for matching when available since parent product IDs are reused across variants.","title":"Variant ID","type":"string"},"sku":{"description":"Stock Keeping Unit of the line item","title":"SKU","type":"string"},"barcode":{"description":"Barcode associated with the line item variant or product","title":"Barcode","type":"string"},"order_item_id":{"description":"Line Item ID in the order (preferred when provided)","title":"Order Line Item ID","type":"string"},"article_name":{"description":"Name of the article","title":"Article Name","type":"string"},"article_category":{"description":"Category of the article","title":"Article Category","type":"string"},"article_store_url":{"description":"URL to the article in the store","title":"Article Store URL","type":"string"},"article_image_url":{"description":"URL to the image of the article","title":"Article Image URL","type":"string"},"article_brand":{"description":"Brand of the article (reference only)","title":"Article Brand","type":"string"},"size":{"description":"Size of the article (reference only)","title":"Size","type":"string"},"color":{"description":"Color of the article (reference only)","title":"Color","type":"string"},"width":{"description":"Width of the article (in millimeters)","title":"Width","type":"number"},"height":{"description":"Height of the article (in millimeters)","title":"Height","type":"number"},"length":{"description":"Length of the article (in millimeters)","title":"Length","type":"number"},"length_unit":{"const":"cm","default":"cm","title":"Length Unit","type":"string"},"weight":{"description":"Weight of the article (in grams, kg, lbs, or oz)","title":"Weight","type":"number"},"weight_unit":{"allOf":[{"$ref":"#/components/schemas/WeightUnitEnum"}],"default":"g","title":"Weight Unit"},"unit_price":{"description":"Paid unit price of the article (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Unit Price","type":"string"},"unit_price_original":{"description":"Original unit price of the article (pre-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Unit Price","type":"string"},"quantity":{"description":"Unit quantity of the article","title":"Unit Quantity","type":"integer"},"amount_invoiced":{"description":"Paid line total amount for this line item (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Invoiced","type":"string"},"tax_amount":{"description":"Total tax amount for this line item (regardless of taxesIncluded)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Tax Amount","type":"string"},"harmonized_system_code":{"description":"HS/HTS code for customs classification","title":"Harmonized System Code","type":"string"},"origin_country_iso3":{"description":"ISO 3166-1 alpha-3 code of articles country of origin, might be required based on shipment regulations","pattern":"^\\w{3}$","title":"Origin Country ISO3","type":"string"},"is_bulky":{"default":false,"description":"If the article is bulky","title":"Is Bulky","type":"boolean"},"tags":{"description":"Tags for the line item, e.g. 'category:home-apparel', or 'customergroup:vip'","items":{"type":"string"},"title":"Tags","type":"array"},"bundle":{"anyOf":[{"$ref":"#/components/schemas/BundleInfo"},{"type":"null"}],"default":null,"description":"Bundle relationship metadata when the item is part of a bundle.","title":"Bundle Info"},"additional_attributes":{"description":"Additional attributes for this line item","items":{"$ref":"#/components/schemas/AdditionalAttribute"},"title":"Additional Attributes","type":"array"}},"required":["line_item_id"],"title":"Line Item","type":"object"},"LineItemVersionEnum":{"enum":["v1","v2"],"title":"LineItemVersionEnum","type":"string"},"WeightUnitEnum":{"enum":["kg","g","lbs","oz"],"type":"string"},"BundleInfo":{"additionalProperties":true,"properties":{"group_id":{"description":"Bundle group identifier in the retailer's system.","title":"Bundle Group ID","type":"string"},"role":{"$ref":"#/components/schemas/BundleRoleEnum","description":"Whether this line item represents a bundle parent or a bundle component.","title":"Bundle Role"},"return_policy":{"$ref":"#/components/schemas/BundleReturnPolicyEnum","default":"components_only","description":"Which lines in this bundle group are selectable for return.","title":"Bundle Return Policy"},"parent_product_id":{"description":"Parent bundle product identifier in the retailer's system.","title":"Bundle Parent Product ID","type":"string"},"parent_variant_id":{"description":"Parent bundle variant identifier in the retailer's system.","title":"Bundle Parent Variant ID","type":"string"},"parent_sku":{"description":"Parent bundle SKU, if available.","title":"Bundle Parent SKU","type":"string"},"parent_title":{"description":"Display title for the bundle parent, if available.","title":"Bundle Parent Title","type":"string"},"parent_quantity":{"description":"Quantity of the bundle parent purchased in the order.","title":"Bundle Parent Quantity","type":"integer"},"component_quantity_per_parent":{"description":"Component quantity per single bundle parent (if determinable).","title":"Bundle Component Quantity Per Parent","type":"integer"},"allocation_method":{"$ref":"#/components/schemas/BundleAllocationMethodEnum","default":"none","description":"How pricing was allocated to bundle components.","title":"Bundle Allocation Method"},"allocated_unit_price":{"description":"Snapshot of allocated component unit price (if derived from bundle totals).","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Allocated Unit Price","type":"string"},"allocated_amount_invoiced":{"description":"Snapshot of allocated component invoiced amount (if derived from bundle totals).","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Allocated Amount Invoiced","type":"string"}},"required":["group_id","role"],"title":"Bundle Info","type":"object"},"BundleRoleEnum":{"enum":["parent","component"],"title":"BundleRoleEnum","type":"string"},"BundleReturnPolicyEnum":{"enum":["parent_only","components_only","parent_and_components"],"title":"BundleReturnPolicyEnum","type":"string"},"BundleAllocationMethodEnum":{"enum":["none","component_price","msrp_ratio","equal"],"title":"BundleAllocationMethodEnum","type":"string"},"AdditionalAttribute":{"properties":{"key":{"description":"The key of the additional attribute","title":"Key","type":"string"},"value":{"default":null,"description":"The value of the additional attribute","title":"Value"}},"required":["key"],"title":"AdditionalAttribute","type":"object"},"LineItemReturn":{"additionalProperties":true,"properties":{"version":{"$ref":"#/components/schemas/LineItemVersionEnum","description":"Optional. Omit this key unless absolutely intended. The standard value is `v2`. If you send `version`, send `v2`.","title":"Version"},"line_item_id":{"description":"Retailer ID of the line item, only the last number part of the whole line item id string","title":"Line Item ID","type":"string"},"product_id":{"description":"Parent product identifier in the retailer's system (shared across variants).","title":"Product ID","type":"string"},"variant_id":{"description":"SKU/variant identifier; prefer for matching when available since parent product IDs are reused across variants.","title":"Variant ID","type":"string"},"sku":{"description":"Stock Keeping Unit of the line item","title":"SKU","type":"string"},"barcode":{"description":"Barcode associated with the line item variant or product","title":"Barcode","type":"string"},"order_item_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Line Item ID in the order, the whole id of the fulfillment line item","title":"Order Line Item ID"},"article_name":{"description":"Name of the article","title":"Article Name","type":"string"},"article_category":{"description":"Category of the article","title":"Article Category","type":"string"},"article_store_url":{"description":"URL to the article in the store","title":"Article Store URL","type":"string"},"article_image_url":{"description":"URL to the image of the article","title":"Article Image URL","type":"string"},"article_brand":{"description":"Brand of the article (reference only)","title":"Article Brand","type":"string"},"size":{"description":"Size of the article (reference only)","title":"Size","type":"string"},"color":{"description":"Color of the article (reference only)","title":"Color","type":"string"},"width":{"description":"Width of the article (in millimeters)","title":"Width","type":"number"},"height":{"description":"Height of the article (in millimeters)","title":"Height","type":"number"},"length":{"description":"Length of the article (in millimeters)","title":"Length","type":"number"},"length_unit":{"const":"cm","default":"cm","title":"Length Unit","type":"string"},"weight":{"description":"Weight of the article (in grams, kg, lbs, or oz)","title":"Weight","type":"number"},"weight_unit":{"allOf":[{"$ref":"#/components/schemas/WeightUnitEnum"}],"default":"g","title":"Weight Unit"},"unit_price":{"description":"Paid unit price of the article (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Unit Price","type":"string"},"unit_price_original":{"description":"Original unit price of the article (pre-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Unit Price","type":"string"},"quantity":{"description":"Unit quantity of the article","title":"Unit Quantity","type":"integer"},"amount_invoiced":{"description":"Paid line total amount for this line item (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Invoiced","type":"string"},"tax_amount":{"description":"Total tax amount for this line item (regardless of taxesIncluded)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Tax Amount","type":"string"},"harmonized_system_code":{"description":"HS/HTS code for customs classification","title":"Harmonized System Code","type":"string"},"origin_country_iso3":{"description":"ISO 3166-1 alpha-3 code of articles country of origin, might be required based on shipment regulations","pattern":"^\\w{3}$","title":"Origin Country ISO3","type":"string"},"is_bulky":{"default":false,"description":"If the article is bulky","title":"Is Bulky","type":"boolean"},"tags":{"description":"Tags for the line item, e.g. 'category:home-apparel', or 'customergroup:vip'","items":{"type":"string"},"title":"Tags","type":"array"},"bundle":{"anyOf":[{"$ref":"#/components/schemas/BundleInfo"},{"type":"null"}],"default":null,"description":"Bundle relationship metadata when the item is part of a bundle.","title":"Bundle Info"},"additional_attributes":{"description":"Additional attributes for this line item","items":{"$ref":"#/components/schemas/AdditionalAttribute"},"title":"Additional Attributes","type":"array"},"unit_price_msrp_current":{"anyOf":[{"pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","type":"string"},{"type":"null"}],"default":null,"description":"Current catalog/MSRP unit price for the same variant.","title":"Current MSRP"},"reference_date_for_return":{"description":"The date, which is used to evaluate the line item return period","format":"date","title":"Reference Date for Return","type":"string"},"reference_date_type":{"allOf":[{"$ref":"#/components/schemas/ReferenceDateTypeEnum"}],"description":"The date type, which is used to evaluate the line item return period","title":"Reference Date Type"},"fulfillment":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Id of the fulfillment that this item belongs to","title":"Fulfillment"},"quantity_returned":{"description":"Quantity of already returned items in this line.","title":"Quantity Returned","type":"integer"},"delivered_date":{"description":"Date when the line item was delivered (same as the fulfillment delivered date)","format":"date","title":"Delivered Date","type":"string"},"return_reason":{"description":"Full return reason path (as configured in the respective return configuration for this object)","title":"Return Reason","type":"string"},"return_reason_pretty":{"description":"Pretty text for the return reason, e.g. 'Doesn't Fit'","title":"Return Reason Pretty","type":"string"},"return_quantity":{"description":"Quantity to be returned","title":"Return Quantity","type":"integer"},"problem_description":{"description":"Description of the problem with this line item","title":"Problem Description","type":"string"},"condition":{"description":"Article condition, if provided","title":"Condition","type":"string"},"article_images":{"items":{"$ref":"#/components/schemas/ReturnImage"},"title":"Article Images","type":"array"},"compensation_method":{"description":"Compensation method for this line item, e.g. exchange, refund, credit","title":"Compensation Method","type":"string"},"accepted_quantity":{"description":"Quantity of the article that was accepted by warehouse","title":"Accepted Quantity","type":"integer"},"rejected_quantity":{"description":"Quantity of the article that was rejected by warehouse","title":"Rejected Quantity","type":"integer"},"status_reason":{"description":"Reason for the rejection / acceptance of the article","title":"Rejection or Acceptance Reason","type":"string"},"status_reason_code":{"description":"Structured reason code, e.g. quality_issue","title":"Status Reason Code","type":"string"},"return_reason_code":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Final code of return reason (leaf code)","readOnly":true,"title":"Return Reason Code"}},"required":["line_item_id","return_reason_code"],"title":"Line Item","type":"object"},"ReferenceDateTypeEnum":{"enum":["order_date","shipping_date","delivery_date"],"type":"string"},"ReturnLabel":{"properties":{"courier":{"description":"Return label courier code or drop-off code, e.g. barcode","title":"Return Label Courier","type":"string"},"service_level":{"description":"Service level of the return label","title":"Service Level","type":"string"},"tracking_number":{"description":"Tracking number of the return label (or in case of Barcode the barcode)","title":"Tracking number","type":"string"},"type":{"$ref":"#/components/schemas/ReturnLabelTypeEnum","default":"shipping","description":"Type of the return label, e.g. 'shipping' for a real courier label, or barcode for a (custom) drop-off code","title":"Label Type"},"flags":{"description":"Flags (extra markers) for the return label, such as 'has_dangerous_goods', or 'is_pickup'","items":{"$ref":"#/components/schemas/ReturnLabelFlagsEnum"},"title":"Label Flags","type":"array"},"documents":{"description":"Documents related to this return label (e.g. print label, barcode, packing slip, wallet-passes)","items":{"$ref":"#/components/schemas/Document"},"title":"Label","type":"array"},"locations_url":{"description":"URL to a courier-specific location finder page.","title":"Locations URL","type":"string"},"destination_id":{"description":"Destination ID for the return label, e.g. warehouse code","title":"Destination ID","type":"string"},"line_item_ids":{"description":"The line item IDs to which the label should be attached","items":{"type":"string"},"title":"Line Item IDs","type":"array"},"is_free_label":{"default":false,"description":"Indicates if the return label is free of charge","title":"Is Free Label","type":"boolean"},"label_cost_amount":{"default":"0.0","description":"Cost of the return label","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Label Cost Amount","type":"string"},"tracking_id":{"description":"Tracking ID of the shipment in the parcelLab system","title":"ParcelLab Tracking ID","type":"string"},"external_reference":{"description":"Unique retailer-provided reference of the shipment, either this tracking number is required","title":"External Reference","type":"string"},"delivery_status":{"$ref":"#/components/schemas/TrackingStageChoices","default":"Pending","description":"Current shipping stage of the return label","title":"Current Shipping Stage"},"pickup_date":{"description":"Scheduled pickup date for the return label. Nullable if not a pickup return.","format":"date","title":"Pickup Date","type":"string"},"earliest_pickup_time":{"description":"Earliest scheduled pickup time for the return label. Nullable if not a pickup return.","format":"time","title":"Earliest Pickup Time","type":"string"},"latest_pickup_time":{"description":"Latest scheduled pickup time for the return label. Nullable if not a pickup return.","format":"time","title":"Latest Pickup Time","type":"string"},"pickup_confirmation_code":{"description":"Confirmation code customer must present on pickup","title":"Pickup Confirmation Code","type":"string"},"is_pickup":{"default":false,"description":"Indicates if the return is a pickup order.","title":"Is Pickup","type":"boolean"},"configuration_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Selected return option mapping ID used to create this label.","title":"Courier Mapping ID"}},"required":["courier","tracking_number"],"title":"Return Label","type":"object"},"ReturnLabelTypeEnum":{"enum":["shipping","custom"],"title":"ReturnLabelTypeEnum","type":"string"},"ReturnLabelFlagsEnum":{"enum":["is_cancellable","is_pickup","has_dangerous_goods"],"type":"string"},"Document":{"properties":{"url":{"description":"URL to the document, in most cases this is a http URL, but it could also be a data URL (base64)","title":"Document URL","type":"string"},"content_type":{"default":"application/pdf","description":"MIME content type of the document, e.g. 'application/pdf'","title":"Content Type","type":"string"},"type":{"default":[],"description":"Type or types of the document, maybe multiple, if bundled","items":{"$ref":"#/components/schemas/DocumentTypeEnum"},"title":"Document Type","type":"array"},"expires_at":{"description":"Expiry date of the document, after which it might not be retrievable","format":"date-time","title":"Document expiry date","type":"string"}},"required":["url"],"title":"Document","type":"object"},"DocumentTypeEnum":{"enum":["label","packing_slip","barcode","customs_document","wallet_pass_io","wallet_pass_android","commercial_invoice"],"type":"string"},"TrackingStageChoices":{"enum":["Pending","Transit","Customs","LastMile","ReadyToCollect","Delivered","SentBack","Returned","Failed","Cancelled"],"title":"TrackingStageChoices","type":"string"},"AddLabelMutation":{"properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"add_label","default":"add_label","title":"Type","type":"string"},"request":{"$ref":"#/components/schemas/AddLabelRequest","description":"The labels to be added to this return registration","title":"Label Requests"}},"required":["request"],"title":"AddLabelMutation","type":"object"},"AddLabelRequest":{"description":"Adds a label to a return registration","properties":{"type":{"$ref":"#/components/schemas/ReturnLabelTypeEnum"},"courier":{"description":"The courier for which a label should be created","title":"Courier","type":"string"},"tracking_number":{"description":"Only for custom label: custom tracking number for the label","title":"Tracking Number","type":"string"},"service_level":{"description":"The service level for the label","title":"Service Level","type":"string"},"destination_id":{"description":"The warehouse or other identifier, to which the courier should ship, corresponds to a warehouse code","title":"Identifier / Warehouse","type":"string"},"destination_address":{"$ref":"#/components/schemas/AddressSchema","description":"Defines a destination address for this label, has precedence over default destination addresses setup in courier configuration. If the courier does not support a custom destination address & the destination address object is present, will raise an error ","title":"Destination Address"},"template_id":{"description":"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.","title":"Template ID","type":"string"},"flags":{"description":"A list of special flags that apply to the label or shipment","items":{"$ref":"#/components/schemas/AddLabelFlagsEnum"},"title":"Flags","type":"array"},"label_types":{"description":"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).","items":{"$ref":"#/components/schemas/LabelTypesEnum"},"title":"Label Types","type":"array"},"line_item_ids":{"description":"The line item IDs to which the label should be attached","items":{"type":"string"},"title":"Line Item IDs","type":"array"},"additional_fields":{"additionalProperties":true,"description":"Custom fields to pass through to label generation and returns document.","title":"Additional Fields","type":"object"}},"required":["type","courier"],"title":"AddLabelRequest","type":"object"},"AddressSchema":{"properties":{"first_name":{"title":"First Name","type":"string"},"last_name":{"title":"Last Name","type":"string"},"company_name":{"title":"Company Name, if any","type":"string"},"address_line":{"description":"Address line, e.g. street and house number, or PO Box","maxLength":256,"minLength":1,"title":"Address Line","type":"string"},"address_line_extra":{"description":"Additional address line, e.g. apartment number or company name","title":"Additional Address Line","type":"string"},"postal_code":{"maxLength":10,"minLength":2,"title":"Postal Code","type":"string"},"city":{"description":"City name (min-length of 1 due to logographic languages)","maxLength":40,"minLength":1,"title":"City","type":"string"},"country_iso3":{"description":"ISO 3166-1 alpha-3 code of country","pattern":"^\\w{3}$","title":"Country ISO3","type":"string"},"region_code":{"description":"Region code, e.g. state or province code (ISO 3166-2), if available","maxLength":25,"minLength":1,"title":"Region Code","type":"string"},"phone":{"description":"Phone number related to this address, if any","maxLength":30,"title":"Phone","type":"string"}},"required":["address_line","postal_code","city","country_iso3"],"title":"Address","type":"object"},"AddLabelFlagsEnum":{"enum":["has_dangerous_goods","is_pickup"],"type":"string"},"LabelTypesEnum":{"enum":["code","print"],"type":"string"},"UpdateItemMutation":{"description":"Update registered article items","properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"update_items","default":"update_items","title":"Type","type":"string"},"items":{"description":"Items for this return registration after update is a applied","items":{"$ref":"#/components/schemas/LineItemReturn"},"title":"Line Items to return","type":"array"}},"title":"Update Items Mutation","type":"object"},"CloseReturnMutation":{"description":"Close a return registration (finalize return + refund).","properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"close_return","default":"close_return","title":"Type","type":"string"},"status_reason":{"description":"Optional reason for closing the return registration.","title":"Status Reason","type":"string"},"trigger_refund":{"description":"Whether to issue a monetary refund when closing the return.","title":"Trigger Refund","type":"boolean"},"release_exchange_items":{"description":"Whether to release exchange items when closing the return.","title":"Release Exchange Items","type":"boolean"},"refund_shipping_fees":{"description":"Whether to refund the original order shipping cost.","title":"Refund Shipping Fees","type":"boolean"},"tracking_number":{"description":"Optional tracking number used for receive-status synchronization when article status updates are provided.","title":"Tracking Number","type":"string"},"received_by":{"description":"Optional source shown in receive status when article status updates are provided. Defaults to API (close_return mutation).","title":"Received By","type":"string"},"receive_note":{"description":"Optional receive note stored with receive status and synchronized to tracking returnReceive.note when article status updates are provided.","title":"Receive Note","type":"string"},"article_status_updates":{"description":"Optional receive-style article status updates to apply before closing the return registration.","items":{"$ref":"#/components/schemas/ArticleStatusUpdate"},"title":"Article Status Updates","type":"array"}},"title":"CloseReturnMutation","type":"object"},"CancelReturnMutation":{"description":"Cancel a return registration and its tracking.","properties":{"operation_id":{"description":"The unique ID of the operation, generated by parcelLab, if not provided","format":"uuid","title":"Operation ID (uuid)","type":"string"},"result":{"$ref":"#/components/schemas/MutationResult","description":"The result of the mutation","title":"Result"},"type":{"const":"cancel_return","default":"cancel_return","title":"Type","type":"string"},"status_reason":{"description":"Optional reason for cancelling the return registration.","title":"Status Reason","type":"string"}},"title":"CancelReturnMutation","type":"object"},"Error400Response":{"type":"object","properties":{"type":{"type":"string"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/GenericErrorItem"}}},"required":["errors","type"]},"GenericErrorItem":{"type":"object","properties":{"code":{"type":"string"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["code","detail"]},"ErrorResponse403":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ClientErrorEnum"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error403"}}},"required":["errors","type"]},"ClientErrorEnum":{"enum":["client_error"],"type":"string","description":"* `client_error` - Client Error"},"Error403":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode403Enum"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["attr","code","detail"]},"ErrorCode403Enum":{"enum":["permission_denied"],"type":"string","description":"* `permission_denied` - Permission Denied"},"ErrorResponse404":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ClientErrorEnum"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error404"}}},"required":["errors","type"]},"Error404":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode404Enum"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["attr","code","detail"]},"ErrorCode404Enum":{"enum":["not_found"],"type":"string","description":"* `not_found` - Not Found"}}},"paths":{"/v4/returns/return-registrations/mutate/":{"post":{"operationId":"mutate_batch","description":"Return Registrations represent a return request from a customer. There might be multiple\nreturn registrations for a single order. There might also be multiple labels for one return\nregistration, if requested by the customer.\n\n A return registration is linked to a configuration bundle (field 'code'), multiple configurations\n might be available on one account (e.g. country-specific courier configurations).\n\n Return registrations are created by the parcelLab return portal, or by the retailer via the parcelLab API.\n\nCertain fields of the return registration are not mutable via requests on the registration resource, but require\n'action' payloads to be submitted (e.g. 'AddLabel') to the 'mutate' action.","summary":"Mutate Return Registration (Batch)","tags":["Return Registration"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MutateReturnRegistrationCollectionRequest"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/MutateReturnRegistrationCollectionRequest"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/MutateReturnRegistrationCollectionRequest"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnRegistration"}}},"description":""},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}},"description":""},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse403"}}},"description":""},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"description":""}}}}}} ``` ## Get Returns Article Information You can retrieve the article information for a specific return registration using the `v4/returns/return-registrations/{external_id}/article-info` endpoint. ## Retrieve Article Info > Retrieve all article rules for the return registration ```json {"openapi":"3.1.0","info":{"title":"parcelLab API","version":"v4"},"security":[{"OAuth2 Authentication":[]},{"HeaderToken":[]}],"components":{"securitySchemes":{"OAuth2 Authentication":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"HeaderToken":{"type":"http","scheme":"bearer","bearerFormat":"Parcellab-API-Token base64(account_id:token)","description":"Send `Authorization: Parcellab-API-Token `.\n\n`` = `base64(account_id:token)` as provided in the portal."}},"schemas":{"ReturnRegistrationReturnability":{"properties":{"article_returnability":{"items":{"$ref":"#/components/schemas/ArticleReturnabilityRules"},"title":"Article Returnability","type":"array"},"article_selection":{"items":{"$ref":"#/components/schemas/ArticleSelection"},"title":"Article Selection","type":"array"},"refund_methods":{"items":{"$ref":"#/components/schemas/RefundMethodSchema"},"title":"Refund Methods","type":"array"},"line_items_by_flag":{"items":{"$ref":"#/components/schemas/ArticlesNonReturnable"},"title":"Line Items By Flag","type":"array"},"article_display_groups":{"description":"Headless portal view model for rendering selectable or submitted articles, including bundle grouping and presentation-only children.","items":{"$ref":"#/components/schemas/ArticleDisplayGroup"},"title":"Article Display Groups","type":"array"},"split_groups":{"items":{"$ref":"#/components/schemas/SplitGroup"},"title":"Split Groups","type":"array"},"requires_split_group_selection":{"default":false,"description":"True if split returns is enabled and there are multiple groups to choose from","title":"Requires Split Group Selection","type":"boolean"}},"title":"ReturnRegistrationReturnability","type":"object"},"ArticleReturnabilityRules":{"properties":{"article":{"$ref":"#/components/schemas/LineItemForReturn"},"reasons":{"items":{"discriminator":{"mapping":{"group":"#/components/schemas/ReturnReasonGroupSchema","reason":"#/components/schemas/ReturnReasonSchema"},"propertyName":"type"},"oneOf":[{"$ref":"#/components/schemas/ReturnReasonSchema"},{"$ref":"#/components/schemas/ReturnReasonGroupSchema"}]},"title":"Reasons","type":"array"},"periods":{"$ref":"#/components/schemas/ArticlePeriods"},"has_compensation":{"default":true,"title":"Requires compensation method","type":"boolean"},"compensation_methods":{"items":{"$ref":"#/components/schemas/CompensationMethodSchema"},"title":"Compensation Methods","type":"array"},"article_filters":{"items":{"$ref":"#/components/schemas/ArticleFilterSchema"},"title":"Article Filters","type":"array"},"article_selection_fields":{"items":{"$ref":"#/components/schemas/FormFieldConfig"},"title":"Article Selection Fields","type":"array"}},"required":["article","periods","article_filters"],"title":"ArticleReturnabilityRules","type":"object"},"LineItemForReturn":{"additionalProperties":true,"properties":{"version":{"$ref":"#/components/schemas/LineItemVersionEnum","description":"Optional. Omit this key unless absolutely intended. The standard value is `v2`. If you send `version`, send `v2`.","title":"Version"},"line_item_id":{"description":"Retailer ID of the line item, only the last number part of the whole line item id string","title":"Line Item ID","type":"string"},"product_id":{"description":"Parent product identifier in the retailer's system (shared across variants).","title":"Product ID","type":"string"},"variant_id":{"description":"SKU/variant identifier; prefer for matching when available since parent product IDs are reused across variants.","title":"Variant ID","type":"string"},"sku":{"description":"Stock Keeping Unit of the line item","title":"SKU","type":"string"},"barcode":{"description":"Barcode associated with the line item variant or product","title":"Barcode","type":"string"},"order_item_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Line Item ID in the order, the whole id of the fulfillment line item","title":"Order Line Item ID"},"article_name":{"description":"Name of the article","title":"Article Name","type":"string"},"article_category":{"description":"Category of the article","title":"Article Category","type":"string"},"article_store_url":{"description":"URL to the article in the store","title":"Article Store URL","type":"string"},"article_image_url":{"description":"URL to the image of the article","title":"Article Image URL","type":"string"},"article_brand":{"description":"Brand of the article (reference only)","title":"Article Brand","type":"string"},"size":{"description":"Size of the article (reference only)","title":"Size","type":"string"},"color":{"description":"Color of the article (reference only)","title":"Color","type":"string"},"width":{"description":"Width of the article (in millimeters)","title":"Width","type":"number"},"height":{"description":"Height of the article (in millimeters)","title":"Height","type":"number"},"length":{"description":"Length of the article (in millimeters)","title":"Length","type":"number"},"length_unit":{"const":"cm","default":"cm","title":"Length Unit","type":"string"},"weight":{"description":"Weight of the article (in grams, kg, lbs, or oz)","title":"Weight","type":"number"},"weight_unit":{"allOf":[{"$ref":"#/components/schemas/WeightUnitEnum"}],"default":"g","title":"Weight Unit"},"unit_price":{"description":"Paid unit price of the article (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Unit Price","type":"string"},"unit_price_original":{"description":"Original unit price of the article (pre-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Unit Price","type":"string"},"quantity":{"description":"Unit quantity of the article","title":"Unit Quantity","type":"integer"},"amount_invoiced":{"description":"Paid line total amount for this line item (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Invoiced","type":"string"},"tax_amount":{"description":"Total tax amount for this line item (regardless of taxesIncluded)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Tax Amount","type":"string"},"harmonized_system_code":{"description":"HS/HTS code for customs classification","title":"Harmonized System Code","type":"string"},"origin_country_iso3":{"description":"ISO 3166-1 alpha-3 code of articles country of origin, might be required based on shipment regulations","pattern":"^\\w{3}$","title":"Origin Country ISO3","type":"string"},"is_bulky":{"default":false,"description":"If the article is bulky","title":"Is Bulky","type":"boolean"},"tags":{"description":"Tags for the line item, e.g. 'category:home-apparel', or 'customergroup:vip'","items":{"type":"string"},"title":"Tags","type":"array"},"bundle":{"anyOf":[{"$ref":"#/components/schemas/BundleInfo"},{"type":"null"}],"default":null,"description":"Bundle relationship metadata when the item is part of a bundle.","title":"Bundle Info"},"additional_attributes":{"description":"Additional attributes for this line item","items":{"$ref":"#/components/schemas/AdditionalAttribute"},"title":"Additional Attributes","type":"array"},"unit_price_msrp_current":{"anyOf":[{"pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","type":"string"},{"type":"null"}],"default":null,"description":"Current catalog/MSRP unit price for the same variant.","title":"Current MSRP"},"reference_date_for_return":{"description":"The date, which is used to evaluate the line item return period","format":"date","title":"Reference Date for Return","type":"string"},"reference_date_type":{"allOf":[{"$ref":"#/components/schemas/ReferenceDateTypeEnum"}],"description":"The date type, which is used to evaluate the line item return period","title":"Reference Date Type"},"fulfillment":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Id of the fulfillment that this item belongs to","title":"Fulfillment"},"quantity_returned":{"description":"Quantity of already returned items in this line.","title":"Quantity Returned","type":"integer"},"delivered_date":{"description":"Date when the line item was delivered (same as the fulfillment delivered date)","format":"date","title":"Delivered Date","type":"string"}},"required":["line_item_id"],"title":"Line Item","type":"object"},"LineItemVersionEnum":{"enum":["v1","v2"],"title":"LineItemVersionEnum","type":"string"},"WeightUnitEnum":{"enum":["kg","g","lbs","oz"],"type":"string"},"BundleInfo":{"additionalProperties":true,"properties":{"group_id":{"description":"Bundle group identifier in the retailer's system.","title":"Bundle Group ID","type":"string"},"role":{"$ref":"#/components/schemas/BundleRoleEnum","description":"Whether this line item represents a bundle parent or a bundle component.","title":"Bundle Role"},"return_policy":{"$ref":"#/components/schemas/BundleReturnPolicyEnum","default":"components_only","description":"Which lines in this bundle group are selectable for return.","title":"Bundle Return Policy"},"parent_product_id":{"description":"Parent bundle product identifier in the retailer's system.","title":"Bundle Parent Product ID","type":"string"},"parent_variant_id":{"description":"Parent bundle variant identifier in the retailer's system.","title":"Bundle Parent Variant ID","type":"string"},"parent_sku":{"description":"Parent bundle SKU, if available.","title":"Bundle Parent SKU","type":"string"},"parent_title":{"description":"Display title for the bundle parent, if available.","title":"Bundle Parent Title","type":"string"},"parent_quantity":{"description":"Quantity of the bundle parent purchased in the order.","title":"Bundle Parent Quantity","type":"integer"},"component_quantity_per_parent":{"description":"Component quantity per single bundle parent (if determinable).","title":"Bundle Component Quantity Per Parent","type":"integer"},"allocation_method":{"$ref":"#/components/schemas/BundleAllocationMethodEnum","default":"none","description":"How pricing was allocated to bundle components.","title":"Bundle Allocation Method"},"allocated_unit_price":{"description":"Snapshot of allocated component unit price (if derived from bundle totals).","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Allocated Unit Price","type":"string"},"allocated_amount_invoiced":{"description":"Snapshot of allocated component invoiced amount (if derived from bundle totals).","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Allocated Amount Invoiced","type":"string"}},"required":["group_id","role"],"title":"Bundle Info","type":"object"},"BundleRoleEnum":{"enum":["parent","component"],"title":"BundleRoleEnum","type":"string"},"BundleReturnPolicyEnum":{"enum":["parent_only","components_only","parent_and_components"],"title":"BundleReturnPolicyEnum","type":"string"},"BundleAllocationMethodEnum":{"enum":["none","component_price","msrp_ratio","equal"],"title":"BundleAllocationMethodEnum","type":"string"},"AdditionalAttribute":{"properties":{"key":{"description":"The key of the additional attribute","title":"Key","type":"string"},"value":{"default":null,"description":"The value of the additional attribute","title":"Value"}},"required":["key"],"title":"AdditionalAttribute","type":"object"},"ReferenceDateTypeEnum":{"enum":["order_date","shipping_date","delivery_date"],"type":"string"},"ReturnReasonSchema":{"properties":{"id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Id of the return reason"},"type":{"const":"reason","title":"Type of the return reason","type":"string"},"code":{"title":"Code of the return reason","type":"string"},"path":{"title":"Full path of the return reason","type":"string"},"name":{"title":"Name (non-localized) of the return reason","type":"string"},"name_localized":{"title":"Name (localized) of the return reason","type":"string"},"is_default":{"default":false,"title":"Whether this reason should be preselected when visible","type":"boolean"},"note_localized":{"default":"","title":"Note (localized) for the return reason","type":"string"},"note":{"title":"Note for the return reason","type":"string"},"problem_description":{"$ref":"#/components/schemas/ProblemDescriptionChoices"},"problem_description_min_length":{"default":0,"title":"Minimum length of the problem description","type":"integer"},"image_upload":{"$ref":"#/components/schemas/ImageUploadChoices","default":"none","title":"Image upload choices for the group"},"shopify_return_reason":{"title":"Shopify Return Reason","type":"string"},"tags":{"items":{"$ref":"#/components/schemas/ReasonTags"},"title":"Tags","type":"array"},"path_segments":{"items":{"type":"string"},"readOnly":true,"title":"Path segments","type":"array"}},"required":["type","code","path","name","name_localized","note","problem_description","shopify_return_reason","path_segments"],"title":"ReturnReasonSchema","type":"object"},"ProblemDescriptionChoices":{"description":"Return reason problem description","enum":["none","optional","required","required_in_warranty"],"title":"ProblemDescriptionChoices","type":"string"},"ImageUploadChoices":{"description":"Return reason image upload choice","enum":["none","optional","required","required_in_warranty"],"title":"ImageUploadChoices","type":"string"},"ReasonTags":{"description":"Return reason tags","enum":["warranty-exclude","trial-exclude","requires-confirmation","info-only","non-selectable"],"title":"ReasonTags","type":"string"},"ReturnReasonGroupSchema":{"properties":{"id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Id of the return reason"},"type":{"const":"group","title":"Type of the return reason","type":"string"},"code":{"title":"Code of the return reason","type":"string"},"path":{"title":"Full path of the return reason","type":"string"},"name":{"title":"Name (non-localized) of the return reason","type":"string"},"name_localized":{"title":"Name (localized) of the return reason","type":"string"},"is_default":{"default":false,"title":"Whether this reason should be preselected when visible","type":"boolean"},"note_localized":{"default":"","title":"Note (localized) for the return reason","type":"string"},"always_show":{"default":false,"title":"Whether the group should always be shown","type":"boolean"},"item_order":{"allOf":[{"$ref":"#/components/schemas/ItemOrderEnum"}],"default":"random","title":"Order of the items in the group"},"children":{"items":{"discriminator":{"mapping":{"group":"#/components/schemas/ReturnReasonGroupSchema","reason":"#/components/schemas/ReturnReasonSchema"},"propertyName":"type"},"oneOf":[{"$ref":"#/components/schemas/ReturnReasonSchema"},{"$ref":"#/components/schemas/ReturnReasonGroupSchema"}]},"title":"Children","type":"array"},"path_segments":{"items":{"type":"string"},"readOnly":true,"title":"Path segments","type":"array"}},"required":["type","code","path","name","name_localized","path_segments"],"title":"ReturnReasonGroupSchema","type":"object"},"ItemOrderEnum":{"enum":["random","fixed"],"type":"string"},"ArticlePeriods":{"properties":{"trial_period_days":{"title":"Trial Period Days","type":"integer"},"grace_period_days":{"title":"Grace Period Days","type":"integer"},"warranty_period_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Warranty Period Days"},"is_in_trial_period":{"default":false,"title":"Is In Trial Period","type":"boolean"},"is_in_warranty_period":{"default":false,"title":"Is In Warranty Period","type":"boolean"}},"required":["trial_period_days","grace_period_days"],"title":"ArticlePeriods","type":"object"},"CompensationMethodSchema":{"properties":{"category":{"title":"Category","type":"string"},"description":{"title":"Description","type":"string"},"description_localized":{"title":"Description (localized) of the compensation method","type":"string"},"external_code":{"title":"External Code","type":"string"},"tags":{"items":{"$ref":"#/components/schemas/CompensationMethodTags"},"title":"Tags","type":"array"}},"required":["category","description","description_localized","external_code"],"title":"CompensationMethodSchema","type":"object"},"CompensationMethodTags":{"enum":["warranty-exclude","trial-exclude"],"title":"CompensationMethodTags","type":"string"},"ArticleFilterSchema":{"properties":{"flag":{"$ref":"#/components/schemas/ReturnArticleFlag"},"keep_article_max_limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Keep Article Max Limit"}},"required":["flag"],"title":"ArticleFilterSchema","type":"object"},"ReturnArticleFlag":{"enum":["hidden","self_return","customer_support","carrier","open_box","marketplace","geo_restriction","hygiene","customized_product","digital_product","final_sale","non_returnable_generic","keep_article","needs_approval"],"title":"ReturnArticleFlag","type":"string"},"FormFieldConfig":{"properties":{"field_id":{"description":"Short internal key used to store and translate this answer. Allowed characters: lowercase letters, numbers, dot, underscore, hyphen, and @. ","title":"Field ID","type":"string"},"field_type":{"$ref":"#/components/schemas/FormFieldType","description":"How the input should look to the customer (text box, dropdown, number, email, date, or checkbox).","title":"Field Type"},"required":{"default":false,"description":"If enabled, customers must fill this before they can submit.","title":"Required","type":"boolean"},"options":{"description":"Technical option keys for dropdown fields.","items":{"type":"string"},"title":"Options","type":"array"},"target":{"$ref":"#/components/schemas/FieldTarget","description":"Where to save the answer. 'order_additional_fields': saved once on the return (order-level data). 'article_fields': saved on the item itself using built-in fields (e.g., 'weight', 'article_name'). 'article_custom_fields': saved as extra per-item data 'customFields'.","title":"Target Level"}},"required":["field_id","field_type","target"],"title":"Form Field Configuration","type":"object"},"FormFieldType":{"enum":["text","dropdown","integer","number","email","date","checkbox"],"title":"FormFieldType","type":"string"},"FieldTarget":{"enum":["order_additional_fields","article_fields","article_custom_fields"],"title":"FieldTarget","type":"string"},"ArticleSelection":{"properties":{"line_item_id":{"title":"Line Item Id","type":"string"},"selected":{"default":false,"title":"Selected","type":"boolean"},"return_quantity":{"default":0,"title":"Return Quantity","type":"integer"},"return_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Return Reason"},"problem_description":{"default":"","title":"Problem Description","type":"string"},"compensation_method":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Compensation Method"},"article_images":{"items":{"type":"string"},"title":"Article Images","type":"array"},"exchange_product_options":{"additionalProperties":{"type":"string"},"default":{},"title":"Exchange Product Options","type":"object"},"customFields":{"additionalProperties":true,"title":"Customfields","type":"object"}},"required":["line_item_id"],"title":"ArticleSelection","type":"object"},"RefundMethodSchema":{"properties":{"code":{"title":"Code","type":"string"},"type":{"$ref":"#/components/schemas/RefundMethods"},"code_localized":{"title":"Code Localized","type":"string"},"hint_localized":{"default":"","title":"Hint Localized","type":"string"}},"required":["code","type","code_localized"],"title":"RefundMethodSchema","type":"object"},"RefundMethods":{"enum":["original-payment-method","gift-card","store-credit","no-refund"],"title":"RefundMethods","type":"string"},"ArticlesNonReturnable":{"properties":{"articles":{"anyOf":[{"items":{"$ref":"#/components/schemas/LineItemForReturn"},"type":"array"},{"type":"null"}],"description":"List of non-returnable articles not including articles that are the hidden by specific filter flag","title":"Articles"},"flag":{"$ref":"#/components/schemas/NonReturnableFlags"},"title_localized":{"description":"Title for non-returnable article","title":"Title Localized","type":"string"},"description_localized":{"description":"Localized description for non-returnable article","title":"Description Localized","type":"string"}},"required":["articles","flag"],"title":"ArticlesNonReturnable","type":"object"},"NonReturnableFlags":{"enum":["already_returned","out_of_returnable_period","hidden","self_return","customer_support","carrier","open_box","marketplace","geo_restriction","hygiene","customized_product","digital_product","final_sale","non_returnable_generic","keep_article"],"title":"NonReturnableFlags","type":"string"},"ArticleDisplayGroup":{"properties":{"group_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Bundle group identifier when this display group represents a bundle; null for standalone display entries.","title":"Bundle Group ID"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Display title for the bundle group, if available.","title":"Bundle Title"},"sku":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Display SKU for the bundle group, if available.","title":"Bundle SKU"},"parent_quantity":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Quantity of the bundle parent purchased, if available.","title":"Bundle Parent Quantity"},"entries":{"description":"Article entries rendered inside this display group.","items":{"$ref":"#/components/schemas/ArticleDisplayEntry"},"title":"Display Entries","type":"array"}},"required":["group_id","title","sku","parent_quantity","entries"],"title":"ArticleDisplayGroup","type":"object"},"ArticleDisplayEntry":{"properties":{"line_item_id":{"description":"Selectable or submitted article line item represented by this display entry.","title":"Line Item ID","type":"string"},"index":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Zero-based index of the article in the rendered article list, used for stable DOM IDs. Null when no rendered index is needed.","title":"Display Index"},"children":{"description":"Bundle component line items shown under this entry for presentation. These children are not selectable through this entry.","items":{"$ref":"#/components/schemas/LineItemForReturn"},"title":"Presentation Children","type":"array"}},"required":["line_item_id"],"title":"ArticleDisplayEntry","type":"object"},"SplitGroup":{"description":"Represents a group of articles in split returns.","properties":{"key":{"description":"Original attribute value, used for URL params and DB storage","title":"Key","type":"string"},"display_name":{"description":"Computed display name for UI","title":"Display Name","type":"string"},"articles":{"items":{"$ref":"#/components/schemas/LineItemForReturn"},"title":"Articles","type":"array"}},"required":["key","display_name"],"title":"SplitGroup","type":"object"},"Error400Response":{"type":"object","properties":{"type":{"type":"string"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/GenericErrorItem"}}},"required":["errors","type"]},"GenericErrorItem":{"type":"object","properties":{"code":{"type":"string"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["code","detail"]},"ErrorResponse403":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ClientErrorEnum"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error403"}}},"required":["errors","type"]},"ClientErrorEnum":{"enum":["client_error"],"type":"string","description":"* `client_error` - Client Error"},"Error403":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode403Enum"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["attr","code","detail"]},"ErrorCode403Enum":{"enum":["permission_denied"],"type":"string","description":"* `permission_denied` - Permission Denied"},"ErrorResponse404":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ClientErrorEnum"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error404"}}},"required":["errors","type"]},"Error404":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode404Enum"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["attr","code","detail"]},"ErrorCode404Enum":{"enum":["not_found"],"type":"string","description":"* `not_found` - Not Found"}}},"paths":{"/v4/returns/return-registrations/{external_id}/article-info/":{"get":{"operationId":"returns_return_registrations_article_info_retrieve","description":"Retrieve all article rules for the return registration","summary":"Retrieve Article Info","parameters":[{"in":"query","name":"draft","schema":{"type":"boolean","default":false},"description":"Set to `true` to preview behavior using unpublished configuration changes (e.g., article rules or courier options)."},{"in":"path","name":"external_id","schema":{"type":"string","format":"uuid","title":"External Identifier","description":"Unique identifier for this return registration, generated by parcelLab"},"required":true}],"tags":["Return Registration"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnRegistrationReturnability"}}},"description":""},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}},"description":""},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse403"}}},"description":""},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"description":""}}}}}} ``` ## Partially Update Returns Article Information You can partially update the article information for a specific return registration using the `v4/returns/return-registrations/{external_id}/article-info` endpoint. ## Validate Article Info (Return items) > 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. ```json {"openapi":"3.1.0","info":{"title":"parcelLab API","version":"v4"},"security":[{"OAuth2 Authentication":[]},{"HeaderToken":[]}],"components":{"securitySchemes":{"OAuth2 Authentication":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"HeaderToken":{"type":"http","scheme":"bearer","bearerFormat":"Parcellab-API-Token base64(account_id:token)","description":"Send `Authorization: Parcellab-API-Token `.\n\n`` = `base64(account_id:token)` as provided in the portal."}},"schemas":{"PatchedReturnRegistrationUpdateArticleSelectionRequest":{"description":"Update the selection of articles for a return registration","properties":{"articles_return":{"items":{"$ref":"#/components/schemas/ArticleSelectionUpdate"},"title":"Return Article Selection","type":"array"},"commit":{"default":false,"description":"Whether to commit the changes to the return registration (defaults to false, convenience flag clients)","title":"Commit","type":"boolean"}},"title":"ReturnRegistrationUpdateArticleSelection","type":"object"},"ArticleSelectionUpdate":{"properties":{"line_item_id":{"title":"Line Item Id","type":"string"},"selected":{"default":true,"description":"Whether the article is selected for return (defaults to true, convenience flag clients)","title":"Selected","type":"boolean"},"return_quantity":{"default":0,"title":"Return Quantity","type":"integer"},"return_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Return Reason"},"problem_description":{"default":"","title":"Problem Description","type":"string"},"compensation_method":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Compensation Method"},"article_images":{"items":{"type":"string"},"title":"Article Images","type":"array"},"exchange_product_options":{"additionalProperties":{"type":"string"},"default":{},"title":"Exchange Product Options","type":"object"},"customFields":{"additionalProperties":true,"title":"Customfields","type":"object"}},"required":["line_item_id"],"title":"ArticleSelectionUpdate","type":"object"},"ReturnRegistrationReturnability":{"properties":{"article_returnability":{"items":{"$ref":"#/components/schemas/ArticleReturnabilityRules"},"title":"Article Returnability","type":"array"},"article_selection":{"items":{"$ref":"#/components/schemas/ArticleSelection"},"title":"Article Selection","type":"array"},"refund_methods":{"items":{"$ref":"#/components/schemas/RefundMethodSchema"},"title":"Refund Methods","type":"array"},"line_items_by_flag":{"items":{"$ref":"#/components/schemas/ArticlesNonReturnable"},"title":"Line Items By Flag","type":"array"},"article_display_groups":{"description":"Headless portal view model for rendering selectable or submitted articles, including bundle grouping and presentation-only children.","items":{"$ref":"#/components/schemas/ArticleDisplayGroup"},"title":"Article Display Groups","type":"array"},"split_groups":{"items":{"$ref":"#/components/schemas/SplitGroup"},"title":"Split Groups","type":"array"},"requires_split_group_selection":{"default":false,"description":"True if split returns is enabled and there are multiple groups to choose from","title":"Requires Split Group Selection","type":"boolean"}},"title":"ReturnRegistrationReturnability","type":"object"},"ArticleReturnabilityRules":{"properties":{"article":{"$ref":"#/components/schemas/LineItemForReturn"},"reasons":{"items":{"discriminator":{"mapping":{"group":"#/components/schemas/ReturnReasonGroupSchema","reason":"#/components/schemas/ReturnReasonSchema"},"propertyName":"type"},"oneOf":[{"$ref":"#/components/schemas/ReturnReasonSchema"},{"$ref":"#/components/schemas/ReturnReasonGroupSchema"}]},"title":"Reasons","type":"array"},"periods":{"$ref":"#/components/schemas/ArticlePeriods"},"has_compensation":{"default":true,"title":"Requires compensation method","type":"boolean"},"compensation_methods":{"items":{"$ref":"#/components/schemas/CompensationMethodSchema"},"title":"Compensation Methods","type":"array"},"article_filters":{"items":{"$ref":"#/components/schemas/ArticleFilterSchema"},"title":"Article Filters","type":"array"},"article_selection_fields":{"items":{"$ref":"#/components/schemas/FormFieldConfig"},"title":"Article Selection Fields","type":"array"}},"required":["article","periods","article_filters"],"title":"ArticleReturnabilityRules","type":"object"},"LineItemForReturn":{"additionalProperties":true,"properties":{"version":{"$ref":"#/components/schemas/LineItemVersionEnum","description":"Optional. Omit this key unless absolutely intended. The standard value is `v2`. If you send `version`, send `v2`.","title":"Version"},"line_item_id":{"description":"Retailer ID of the line item, only the last number part of the whole line item id string","title":"Line Item ID","type":"string"},"product_id":{"description":"Parent product identifier in the retailer's system (shared across variants).","title":"Product ID","type":"string"},"variant_id":{"description":"SKU/variant identifier; prefer for matching when available since parent product IDs are reused across variants.","title":"Variant ID","type":"string"},"sku":{"description":"Stock Keeping Unit of the line item","title":"SKU","type":"string"},"barcode":{"description":"Barcode associated with the line item variant or product","title":"Barcode","type":"string"},"order_item_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Line Item ID in the order, the whole id of the fulfillment line item","title":"Order Line Item ID"},"article_name":{"description":"Name of the article","title":"Article Name","type":"string"},"article_category":{"description":"Category of the article","title":"Article Category","type":"string"},"article_store_url":{"description":"URL to the article in the store","title":"Article Store URL","type":"string"},"article_image_url":{"description":"URL to the image of the article","title":"Article Image URL","type":"string"},"article_brand":{"description":"Brand of the article (reference only)","title":"Article Brand","type":"string"},"size":{"description":"Size of the article (reference only)","title":"Size","type":"string"},"color":{"description":"Color of the article (reference only)","title":"Color","type":"string"},"width":{"description":"Width of the article (in millimeters)","title":"Width","type":"number"},"height":{"description":"Height of the article (in millimeters)","title":"Height","type":"number"},"length":{"description":"Length of the article (in millimeters)","title":"Length","type":"number"},"length_unit":{"const":"cm","default":"cm","title":"Length Unit","type":"string"},"weight":{"description":"Weight of the article (in grams, kg, lbs, or oz)","title":"Weight","type":"number"},"weight_unit":{"allOf":[{"$ref":"#/components/schemas/WeightUnitEnum"}],"default":"g","title":"Weight Unit"},"unit_price":{"description":"Paid unit price of the article (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Unit Price","type":"string"},"unit_price_original":{"description":"Original unit price of the article (pre-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Original Unit Price","type":"string"},"quantity":{"description":"Unit quantity of the article","title":"Unit Quantity","type":"integer"},"amount_invoiced":{"description":"Paid line total amount for this line item (post-discount)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Amount Invoiced","type":"string"},"tax_amount":{"description":"Total tax amount for this line item (regardless of taxesIncluded)","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Tax Amount","type":"string"},"harmonized_system_code":{"description":"HS/HTS code for customs classification","title":"Harmonized System Code","type":"string"},"origin_country_iso3":{"description":"ISO 3166-1 alpha-3 code of articles country of origin, might be required based on shipment regulations","pattern":"^\\w{3}$","title":"Origin Country ISO3","type":"string"},"is_bulky":{"default":false,"description":"If the article is bulky","title":"Is Bulky","type":"boolean"},"tags":{"description":"Tags for the line item, e.g. 'category:home-apparel', or 'customergroup:vip'","items":{"type":"string"},"title":"Tags","type":"array"},"bundle":{"anyOf":[{"$ref":"#/components/schemas/BundleInfo"},{"type":"null"}],"default":null,"description":"Bundle relationship metadata when the item is part of a bundle.","title":"Bundle Info"},"additional_attributes":{"description":"Additional attributes for this line item","items":{"$ref":"#/components/schemas/AdditionalAttribute"},"title":"Additional Attributes","type":"array"},"unit_price_msrp_current":{"anyOf":[{"pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","type":"string"},{"type":"null"}],"default":null,"description":"Current catalog/MSRP unit price for the same variant.","title":"Current MSRP"},"reference_date_for_return":{"description":"The date, which is used to evaluate the line item return period","format":"date","title":"Reference Date for Return","type":"string"},"reference_date_type":{"allOf":[{"$ref":"#/components/schemas/ReferenceDateTypeEnum"}],"description":"The date type, which is used to evaluate the line item return period","title":"Reference Date Type"},"fulfillment":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Id of the fulfillment that this item belongs to","title":"Fulfillment"},"quantity_returned":{"description":"Quantity of already returned items in this line.","title":"Quantity Returned","type":"integer"},"delivered_date":{"description":"Date when the line item was delivered (same as the fulfillment delivered date)","format":"date","title":"Delivered Date","type":"string"}},"required":["line_item_id"],"title":"Line Item","type":"object"},"LineItemVersionEnum":{"enum":["v1","v2"],"title":"LineItemVersionEnum","type":"string"},"WeightUnitEnum":{"enum":["kg","g","lbs","oz"],"type":"string"},"BundleInfo":{"additionalProperties":true,"properties":{"group_id":{"description":"Bundle group identifier in the retailer's system.","title":"Bundle Group ID","type":"string"},"role":{"$ref":"#/components/schemas/BundleRoleEnum","description":"Whether this line item represents a bundle parent or a bundle component.","title":"Bundle Role"},"return_policy":{"$ref":"#/components/schemas/BundleReturnPolicyEnum","default":"components_only","description":"Which lines in this bundle group are selectable for return.","title":"Bundle Return Policy"},"parent_product_id":{"description":"Parent bundle product identifier in the retailer's system.","title":"Bundle Parent Product ID","type":"string"},"parent_variant_id":{"description":"Parent bundle variant identifier in the retailer's system.","title":"Bundle Parent Variant ID","type":"string"},"parent_sku":{"description":"Parent bundle SKU, if available.","title":"Bundle Parent SKU","type":"string"},"parent_title":{"description":"Display title for the bundle parent, if available.","title":"Bundle Parent Title","type":"string"},"parent_quantity":{"description":"Quantity of the bundle parent purchased in the order.","title":"Bundle Parent Quantity","type":"integer"},"component_quantity_per_parent":{"description":"Component quantity per single bundle parent (if determinable).","title":"Bundle Component Quantity Per Parent","type":"integer"},"allocation_method":{"$ref":"#/components/schemas/BundleAllocationMethodEnum","default":"none","description":"How pricing was allocated to bundle components.","title":"Bundle Allocation Method"},"allocated_unit_price":{"description":"Snapshot of allocated component unit price (if derived from bundle totals).","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Allocated Unit Price","type":"string"},"allocated_amount_invoiced":{"description":"Snapshot of allocated component invoiced amount (if derived from bundle totals).","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Allocated Amount Invoiced","type":"string"}},"required":["group_id","role"],"title":"Bundle Info","type":"object"},"BundleRoleEnum":{"enum":["parent","component"],"title":"BundleRoleEnum","type":"string"},"BundleReturnPolicyEnum":{"enum":["parent_only","components_only","parent_and_components"],"title":"BundleReturnPolicyEnum","type":"string"},"BundleAllocationMethodEnum":{"enum":["none","component_price","msrp_ratio","equal"],"title":"BundleAllocationMethodEnum","type":"string"},"AdditionalAttribute":{"properties":{"key":{"description":"The key of the additional attribute","title":"Key","type":"string"},"value":{"default":null,"description":"The value of the additional attribute","title":"Value"}},"required":["key"],"title":"AdditionalAttribute","type":"object"},"ReferenceDateTypeEnum":{"enum":["order_date","shipping_date","delivery_date"],"type":"string"},"ReturnReasonSchema":{"properties":{"id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Id of the return reason"},"type":{"const":"reason","title":"Type of the return reason","type":"string"},"code":{"title":"Code of the return reason","type":"string"},"path":{"title":"Full path of the return reason","type":"string"},"name":{"title":"Name (non-localized) of the return reason","type":"string"},"name_localized":{"title":"Name (localized) of the return reason","type":"string"},"is_default":{"default":false,"title":"Whether this reason should be preselected when visible","type":"boolean"},"note_localized":{"default":"","title":"Note (localized) for the return reason","type":"string"},"note":{"title":"Note for the return reason","type":"string"},"problem_description":{"$ref":"#/components/schemas/ProblemDescriptionChoices"},"problem_description_min_length":{"default":0,"title":"Minimum length of the problem description","type":"integer"},"image_upload":{"$ref":"#/components/schemas/ImageUploadChoices","default":"none","title":"Image upload choices for the group"},"shopify_return_reason":{"title":"Shopify Return Reason","type":"string"},"tags":{"items":{"$ref":"#/components/schemas/ReasonTags"},"title":"Tags","type":"array"},"path_segments":{"items":{"type":"string"},"readOnly":true,"title":"Path segments","type":"array"}},"required":["type","code","path","name","name_localized","note","problem_description","shopify_return_reason","path_segments"],"title":"ReturnReasonSchema","type":"object"},"ProblemDescriptionChoices":{"description":"Return reason problem description","enum":["none","optional","required","required_in_warranty"],"title":"ProblemDescriptionChoices","type":"string"},"ImageUploadChoices":{"description":"Return reason image upload choice","enum":["none","optional","required","required_in_warranty"],"title":"ImageUploadChoices","type":"string"},"ReasonTags":{"description":"Return reason tags","enum":["warranty-exclude","trial-exclude","requires-confirmation","info-only","non-selectable"],"title":"ReasonTags","type":"string"},"ReturnReasonGroupSchema":{"properties":{"id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Id of the return reason"},"type":{"const":"group","title":"Type of the return reason","type":"string"},"code":{"title":"Code of the return reason","type":"string"},"path":{"title":"Full path of the return reason","type":"string"},"name":{"title":"Name (non-localized) of the return reason","type":"string"},"name_localized":{"title":"Name (localized) of the return reason","type":"string"},"is_default":{"default":false,"title":"Whether this reason should be preselected when visible","type":"boolean"},"note_localized":{"default":"","title":"Note (localized) for the return reason","type":"string"},"always_show":{"default":false,"title":"Whether the group should always be shown","type":"boolean"},"item_order":{"allOf":[{"$ref":"#/components/schemas/ItemOrderEnum"}],"default":"random","title":"Order of the items in the group"},"children":{"items":{"discriminator":{"mapping":{"group":"#/components/schemas/ReturnReasonGroupSchema","reason":"#/components/schemas/ReturnReasonSchema"},"propertyName":"type"},"oneOf":[{"$ref":"#/components/schemas/ReturnReasonSchema"},{"$ref":"#/components/schemas/ReturnReasonGroupSchema"}]},"title":"Children","type":"array"},"path_segments":{"items":{"type":"string"},"readOnly":true,"title":"Path segments","type":"array"}},"required":["type","code","path","name","name_localized","path_segments"],"title":"ReturnReasonGroupSchema","type":"object"},"ItemOrderEnum":{"enum":["random","fixed"],"type":"string"},"ArticlePeriods":{"properties":{"trial_period_days":{"title":"Trial Period Days","type":"integer"},"grace_period_days":{"title":"Grace Period Days","type":"integer"},"warranty_period_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Warranty Period Days"},"is_in_trial_period":{"default":false,"title":"Is In Trial Period","type":"boolean"},"is_in_warranty_period":{"default":false,"title":"Is In Warranty Period","type":"boolean"}},"required":["trial_period_days","grace_period_days"],"title":"ArticlePeriods","type":"object"},"CompensationMethodSchema":{"properties":{"category":{"title":"Category","type":"string"},"description":{"title":"Description","type":"string"},"description_localized":{"title":"Description (localized) of the compensation method","type":"string"},"external_code":{"title":"External Code","type":"string"},"tags":{"items":{"$ref":"#/components/schemas/CompensationMethodTags"},"title":"Tags","type":"array"}},"required":["category","description","description_localized","external_code"],"title":"CompensationMethodSchema","type":"object"},"CompensationMethodTags":{"enum":["warranty-exclude","trial-exclude"],"title":"CompensationMethodTags","type":"string"},"ArticleFilterSchema":{"properties":{"flag":{"$ref":"#/components/schemas/ReturnArticleFlag"},"keep_article_max_limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Keep Article Max Limit"}},"required":["flag"],"title":"ArticleFilterSchema","type":"object"},"ReturnArticleFlag":{"enum":["hidden","self_return","customer_support","carrier","open_box","marketplace","geo_restriction","hygiene","customized_product","digital_product","final_sale","non_returnable_generic","keep_article","needs_approval"],"title":"ReturnArticleFlag","type":"string"},"FormFieldConfig":{"properties":{"field_id":{"description":"Short internal key used to store and translate this answer. Allowed characters: lowercase letters, numbers, dot, underscore, hyphen, and @. ","title":"Field ID","type":"string"},"field_type":{"$ref":"#/components/schemas/FormFieldType","description":"How the input should look to the customer (text box, dropdown, number, email, date, or checkbox).","title":"Field Type"},"required":{"default":false,"description":"If enabled, customers must fill this before they can submit.","title":"Required","type":"boolean"},"options":{"description":"Technical option keys for dropdown fields.","items":{"type":"string"},"title":"Options","type":"array"},"target":{"$ref":"#/components/schemas/FieldTarget","description":"Where to save the answer. 'order_additional_fields': saved once on the return (order-level data). 'article_fields': saved on the item itself using built-in fields (e.g., 'weight', 'article_name'). 'article_custom_fields': saved as extra per-item data 'customFields'.","title":"Target Level"}},"required":["field_id","field_type","target"],"title":"Form Field Configuration","type":"object"},"FormFieldType":{"enum":["text","dropdown","integer","number","email","date","checkbox"],"title":"FormFieldType","type":"string"},"FieldTarget":{"enum":["order_additional_fields","article_fields","article_custom_fields"],"title":"FieldTarget","type":"string"},"ArticleSelection":{"properties":{"line_item_id":{"title":"Line Item Id","type":"string"},"selected":{"default":false,"title":"Selected","type":"boolean"},"return_quantity":{"default":0,"title":"Return Quantity","type":"integer"},"return_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Return Reason"},"problem_description":{"default":"","title":"Problem Description","type":"string"},"compensation_method":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Compensation Method"},"article_images":{"items":{"type":"string"},"title":"Article Images","type":"array"},"exchange_product_options":{"additionalProperties":{"type":"string"},"default":{},"title":"Exchange Product Options","type":"object"},"customFields":{"additionalProperties":true,"title":"Customfields","type":"object"}},"required":["line_item_id"],"title":"ArticleSelection","type":"object"},"RefundMethodSchema":{"properties":{"code":{"title":"Code","type":"string"},"type":{"$ref":"#/components/schemas/RefundMethods"},"code_localized":{"title":"Code Localized","type":"string"},"hint_localized":{"default":"","title":"Hint Localized","type":"string"}},"required":["code","type","code_localized"],"title":"RefundMethodSchema","type":"object"},"RefundMethods":{"enum":["original-payment-method","gift-card","store-credit","no-refund"],"title":"RefundMethods","type":"string"},"ArticlesNonReturnable":{"properties":{"articles":{"anyOf":[{"items":{"$ref":"#/components/schemas/LineItemForReturn"},"type":"array"},{"type":"null"}],"description":"List of non-returnable articles not including articles that are the hidden by specific filter flag","title":"Articles"},"flag":{"$ref":"#/components/schemas/NonReturnableFlags"},"title_localized":{"description":"Title for non-returnable article","title":"Title Localized","type":"string"},"description_localized":{"description":"Localized description for non-returnable article","title":"Description Localized","type":"string"}},"required":["articles","flag"],"title":"ArticlesNonReturnable","type":"object"},"NonReturnableFlags":{"enum":["already_returned","out_of_returnable_period","hidden","self_return","customer_support","carrier","open_box","marketplace","geo_restriction","hygiene","customized_product","digital_product","final_sale","non_returnable_generic","keep_article"],"title":"NonReturnableFlags","type":"string"},"ArticleDisplayGroup":{"properties":{"group_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Bundle group identifier when this display group represents a bundle; null for standalone display entries.","title":"Bundle Group ID"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Display title for the bundle group, if available.","title":"Bundle Title"},"sku":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Display SKU for the bundle group, if available.","title":"Bundle SKU"},"parent_quantity":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Quantity of the bundle parent purchased, if available.","title":"Bundle Parent Quantity"},"entries":{"description":"Article entries rendered inside this display group.","items":{"$ref":"#/components/schemas/ArticleDisplayEntry"},"title":"Display Entries","type":"array"}},"required":["group_id","title","sku","parent_quantity","entries"],"title":"ArticleDisplayGroup","type":"object"},"ArticleDisplayEntry":{"properties":{"line_item_id":{"description":"Selectable or submitted article line item represented by this display entry.","title":"Line Item ID","type":"string"},"index":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Zero-based index of the article in the rendered article list, used for stable DOM IDs. Null when no rendered index is needed.","title":"Display Index"},"children":{"description":"Bundle component line items shown under this entry for presentation. These children are not selectable through this entry.","items":{"$ref":"#/components/schemas/LineItemForReturn"},"title":"Presentation Children","type":"array"}},"required":["line_item_id"],"title":"ArticleDisplayEntry","type":"object"},"SplitGroup":{"description":"Represents a group of articles in split returns.","properties":{"key":{"description":"Original attribute value, used for URL params and DB storage","title":"Key","type":"string"},"display_name":{"description":"Computed display name for UI","title":"Display Name","type":"string"},"articles":{"items":{"$ref":"#/components/schemas/LineItemForReturn"},"title":"Articles","type":"array"}},"required":["key","display_name"],"title":"SplitGroup","type":"object"},"Error400Response":{"type":"object","properties":{"type":{"type":"string"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/GenericErrorItem"}}},"required":["errors","type"]},"GenericErrorItem":{"type":"object","properties":{"code":{"type":"string"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["code","detail"]},"ErrorResponse403":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ClientErrorEnum"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error403"}}},"required":["errors","type"]},"ClientErrorEnum":{"enum":["client_error"],"type":"string","description":"* `client_error` - Client Error"},"Error403":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode403Enum"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["attr","code","detail"]},"ErrorCode403Enum":{"enum":["permission_denied"],"type":"string","description":"* `permission_denied` - Permission Denied"},"ErrorResponse404":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ClientErrorEnum"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error404"}}},"required":["errors","type"]},"Error404":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode404Enum"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["attr","code","detail"]},"ErrorCode404Enum":{"enum":["not_found"],"type":"string","description":"* `not_found` - Not Found"}}},"paths":{"/v4/returns/return-registrations/{external_id}/article-info/":{"patch":{"operationId":"returns_return_registrations_article_info_partial_update","description":"Return Registrations represent a return request from a customer. There might be multiple\nreturn registrations for a single order. There might also be multiple labels for one return\nregistration, if requested by the customer.\n\n A return registration is linked to a configuration bundle (field 'code'), multiple configurations\n might be available on one account (e.g. country-specific courier configurations).\n\n Return registrations are created by the parcelLab return portal, or by the retailer via the parcelLab API.\n\nCertain fields of the return registration are not mutable via requests on the registration resource, but require\n'action' payloads to be submitted (e.g. 'AddLabel') to the 'mutate' action.","summary":"Validate Article Info (Return items)","parameters":[{"in":"query","name":"draft","schema":{"type":"boolean","default":false},"description":"Set to `true` to preview behavior using unpublished configuration changes (e.g., article rules or courier options)."},{"in":"path","name":"external_id","schema":{"type":"string","format":"uuid","title":"External Identifier","description":"Unique identifier for this return registration, generated by parcelLab"},"required":true}],"tags":["Return Registration"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchedReturnRegistrationUpdateArticleSelectionRequest"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/PatchedReturnRegistrationUpdateArticleSelectionRequest"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/PatchedReturnRegistrationUpdateArticleSelectionRequest"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnRegistrationReturnability"}}},"description":""},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}},"description":""},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse403"}}},"description":""},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"description":""}}}}}} ``` ## Get Return Options You can retrieve the carrier details for a specific return registration using the `v4/returns/return-registrations/{external_id}/return-options` endpoint. ## Retrieve Return Options > Retrieve all courier information for the return registration ```json {"openapi":"3.1.0","info":{"title":"parcelLab API","version":"v4"},"security":[{"OAuth2 Authentication":[]},{"HeaderToken":[]}],"components":{"securitySchemes":{"OAuth2 Authentication":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"HeaderToken":{"type":"http","scheme":"bearer","bearerFormat":"Parcellab-API-Token base64(account_id:token)","description":"Send `Authorization: Parcellab-API-Token `.\n\n`` = `base64(account_id:token)` as provided in the portal."}},"schemas":{"ReturnOptions":{"properties":{"return_options":{"items":{"$ref":"#/components/schemas/ReturnOption"},"title":"Return Options","type":"array"}},"required":["return_options"],"title":"ReturnOptions","type":"object"},"ReturnOption":{"properties":{"option_code":{"title":"Option (Courier) Code","type":"string"},"identifier":{"default":"","title":"Destination Identifier (in case of multiple destinations or courier configurations sharing one courier code).","type":"string"},"name":{"title":"Option (Courier) Name","type":"string"},"label_cost":{"default":"0","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Cost of the label (if any)","type":"string"},"is_free_label":{"default":false,"title":"Whether the courier provides free labels.","type":"boolean"},"is_pickup":{"default":false,"title":"Whether the return option is a pickup.","type":"boolean"},"visibility":{"$ref":"#/components/schemas/ReturnOptionVisibility","default":"available","title":"Visibility level of the return option."},"next_best_location":{"default":"","title":"Location to redirect user to if this option is not available.","type":"string"},"retention_offer":{"anyOf":[{"$ref":"#/components/schemas/RetentionOffer"},{"type":"null"}],"default":null,"title":"Retention offer configuration."},"logo_image_url":{"title":"URL to the courier logo.","type":"string"},"pickup_date_selection":{"default":true,"title":"Whether the return option includes the option to select a pickup date.","type":"boolean"},"pickup_options":{"$ref":"#/components/schemas/DatePickerOptions","title":"Options for the date picker"},"supports_pickup_dates_query":{"default":false,"title":"Whether the courier supports querying available pickup dates.","type":"boolean"},"supports_pickup_rescheduling":{"default":false,"title":"Whether the courier supports pickup rescheduling.","type":"boolean"},"provides_label":{"default":true,"title":"Whether the courier provides a label.","type":"boolean"},"service_level":{"title":"Courier service level used for place-info routing.","type":"string"},"is_temporarily_disabled":{"default":false,"title":"Whether this return option is temporarily disabled.","type":"boolean"},"is_disabled_reason":{"default":"","title":"Reason why this option is disabled (if applicable).","type":"string"},"key":{"readOnly":true,"title":"Stable identifier for selecting this return option.","type":"string"},"title":{"readOnly":true,"title":"Localized title of the return option.","type":"string"},"description":{"readOnly":true,"title":"Localized description of the return option.","type":"string"}},"required":["option_code","name","key","title","description"],"title":"ReturnOption","type":"object"},"ReturnOptionVisibility":{"enum":["available","secondary"],"title":"ReturnOptionVisibility","type":"string"},"RetentionOffer":{"properties":{"percentage":{"pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Percentage","type":"string"},"refund_method_code":{"description":"Refund method code for this retention offer. Must match a configured refund method in the portal's courier APIs.","title":"Refund method code","type":"string"}},"required":["percentage","refund_method_code"],"title":"RetentionOffer","type":"object"},"DatePickerOptions":{"properties":{"maxDays":{"default":14,"title":"Maximum date in days from now available for selection.","type":"integer"},"excludeSaturday":{"default":false,"title":"Whether to exclude Saturdays.","type":"boolean"}},"title":"DatePickerOptions","type":"object"},"Error400Response":{"type":"object","properties":{"type":{"type":"string"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/GenericErrorItem"}}},"required":["errors","type"]},"GenericErrorItem":{"type":"object","properties":{"code":{"type":"string"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["code","detail"]},"ErrorResponse403":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ClientErrorEnum"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error403"}}},"required":["errors","type"]},"ClientErrorEnum":{"enum":["client_error"],"type":"string","description":"* `client_error` - Client Error"},"Error403":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode403Enum"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["attr","code","detail"]},"ErrorCode403Enum":{"enum":["permission_denied"],"type":"string","description":"* `permission_denied` - Permission Denied"},"ErrorResponse404":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ClientErrorEnum"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error404"}}},"required":["errors","type"]},"Error404":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode404Enum"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["attr","code","detail"]},"ErrorCode404Enum":{"enum":["not_found"],"type":"string","description":"* `not_found` - Not Found"}}},"paths":{"/v4/returns/return-registrations/{external_id}/return-options/":{"get":{"operationId":"returns_return_registrations_return_options_retrieve","description":"Retrieve all courier information for the return registration","summary":"Retrieve Return Options","parameters":[{"in":"query","name":"draft","schema":{"type":"boolean","default":false},"description":"Set to `true` to preview behavior using unpublished configuration changes (e.g., article rules or courier options)."},{"in":"path","name":"external_id","schema":{"type":"string","format":"uuid","title":"External Identifier","description":"Unique identifier for this return registration, generated by parcelLab"},"required":true}],"tags":["Return Registration"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnOptions"}}},"description":""},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}},"description":""},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse403"}}},"description":""},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"description":""}}}}}} ``` ## Assign Return Options You can apply the carrier details for a specific return registration using the `v4/returns/return-registrations/{external_id}/return-options` endpoint. ## Apply Return Option > 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. ```json {"openapi":"3.1.0","info":{"title":"parcelLab API","version":"v4"},"security":[{"OAuth2 Authentication":[]},{"HeaderToken":[]}],"components":{"securitySchemes":{"OAuth2 Authentication":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"HeaderToken":{"type":"http","scheme":"bearer","bearerFormat":"Parcellab-API-Token base64(account_id:token)","description":"Send `Authorization: Parcellab-API-Token `.\n\n`` = `base64(account_id:token)` as provided in the portal."}},"schemas":{"ReturnOptionRequestRequest":{"properties":{"options_selected":{"items":{"$ref":"#/components/schemas/ReturnOptionSelection"},"title":"Selected courier options","type":"array"}},"required":["options_selected"],"title":"ReturnOptionRequest","type":"object"},"ReturnOptionSelection":{"properties":{"key":{"title":"Stable identifier of the selected option","type":"string"}},"required":["key"],"title":"ReturnOptionSelection","type":"object"},"ReturnOptionResponse":{"properties":{"labels":{"items":{"$ref":"#/components/schemas/ReturnLabel"},"title":"Selected courier options","type":"array"}},"required":["labels"],"title":"ReturnOptionResponse","type":"object"},"ReturnLabel":{"properties":{"courier":{"description":"Return label courier code or drop-off code, e.g. barcode","title":"Return Label Courier","type":"string"},"service_level":{"description":"Service level of the return label","title":"Service Level","type":"string"},"tracking_number":{"description":"Tracking number of the return label (or in case of Barcode the barcode)","title":"Tracking number","type":"string"},"type":{"$ref":"#/components/schemas/ReturnLabelTypeEnum","default":"shipping","description":"Type of the return label, e.g. 'shipping' for a real courier label, or barcode for a (custom) drop-off code","title":"Label Type"},"flags":{"description":"Flags (extra markers) for the return label, such as 'has_dangerous_goods', or 'is_pickup'","items":{"$ref":"#/components/schemas/ReturnLabelFlagsEnum"},"title":"Label Flags","type":"array"},"documents":{"description":"Documents related to this return label (e.g. print label, barcode, packing slip, wallet-passes)","items":{"$ref":"#/components/schemas/Document"},"title":"Label","type":"array"},"locations_url":{"description":"URL to a courier-specific location finder page.","title":"Locations URL","type":"string"},"destination_id":{"description":"Destination ID for the return label, e.g. warehouse code","title":"Destination ID","type":"string"},"line_item_ids":{"description":"The line item IDs to which the label should be attached","items":{"type":"string"},"title":"Line Item IDs","type":"array"},"is_free_label":{"default":false,"description":"Indicates if the return label is free of charge","title":"Is Free Label","type":"boolean"},"label_cost_amount":{"default":"0.0","description":"Cost of the return label","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Label Cost Amount","type":"string"},"tracking_id":{"description":"Tracking ID of the shipment in the parcelLab system","title":"ParcelLab Tracking ID","type":"string"},"external_reference":{"description":"Unique retailer-provided reference of the shipment, either this tracking number is required","title":"External Reference","type":"string"},"delivery_status":{"$ref":"#/components/schemas/TrackingStageChoices","default":"Pending","description":"Current shipping stage of the return label","title":"Current Shipping Stage"},"pickup_date":{"description":"Scheduled pickup date for the return label. Nullable if not a pickup return.","format":"date","title":"Pickup Date","type":"string"},"earliest_pickup_time":{"description":"Earliest scheduled pickup time for the return label. Nullable if not a pickup return.","format":"time","title":"Earliest Pickup Time","type":"string"},"latest_pickup_time":{"description":"Latest scheduled pickup time for the return label. Nullable if not a pickup return.","format":"time","title":"Latest Pickup Time","type":"string"},"pickup_confirmation_code":{"description":"Confirmation code customer must present on pickup","title":"Pickup Confirmation Code","type":"string"},"is_pickup":{"default":false,"description":"Indicates if the return is a pickup order.","title":"Is Pickup","type":"boolean"},"configuration_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Selected return option mapping ID used to create this label.","title":"Courier Mapping ID"}},"required":["courier","tracking_number"],"title":"Return Label","type":"object"},"ReturnLabelTypeEnum":{"enum":["shipping","custom"],"title":"ReturnLabelTypeEnum","type":"string"},"ReturnLabelFlagsEnum":{"enum":["is_cancellable","is_pickup","has_dangerous_goods"],"type":"string"},"Document":{"properties":{"url":{"description":"URL to the document, in most cases this is a http URL, but it could also be a data URL (base64)","title":"Document URL","type":"string"},"content_type":{"default":"application/pdf","description":"MIME content type of the document, e.g. 'application/pdf'","title":"Content Type","type":"string"},"type":{"default":[],"description":"Type or types of the document, maybe multiple, if bundled","items":{"$ref":"#/components/schemas/DocumentTypeEnum"},"title":"Document Type","type":"array"},"expires_at":{"description":"Expiry date of the document, after which it might not be retrievable","format":"date-time","title":"Document expiry date","type":"string"}},"required":["url"],"title":"Document","type":"object"},"DocumentTypeEnum":{"enum":["label","packing_slip","barcode","customs_document","wallet_pass_io","wallet_pass_android","commercial_invoice"],"type":"string"},"TrackingStageChoices":{"enum":["Pending","Transit","Customs","LastMile","ReadyToCollect","Delivered","SentBack","Returned","Failed","Cancelled"],"title":"TrackingStageChoices","type":"string"},"Error400Response":{"type":"object","properties":{"type":{"type":"string"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/GenericErrorItem"}}},"required":["errors","type"]},"GenericErrorItem":{"type":"object","properties":{"code":{"type":"string"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["code","detail"]},"ErrorResponse403":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ClientErrorEnum"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error403"}}},"required":["errors","type"]},"ClientErrorEnum":{"enum":["client_error"],"type":"string","description":"* `client_error` - Client Error"},"Error403":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode403Enum"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["attr","code","detail"]},"ErrorCode403Enum":{"enum":["permission_denied"],"type":"string","description":"* `permission_denied` - Permission Denied"},"ErrorResponse404":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ClientErrorEnum"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error404"}}},"required":["errors","type"]},"Error404":{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ErrorCode404Enum"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["attr","code","detail"]},"ErrorCode404Enum":{"enum":["not_found"],"type":"string","description":"* `not_found` - Not Found"}}},"paths":{"/v4/returns/return-registrations/{external_id}/return-options/":{"post":{"operationId":"returns_return_registrations_return_options_create","description":"Return Registrations represent a return request from a customer. There might be multiple\nreturn registrations for a single order. There might also be multiple labels for one return\nregistration, if requested by the customer.\n\n A return registration is linked to a configuration bundle (field 'code'), multiple configurations\n might be available on one account (e.g. country-specific courier configurations).\n\n Return registrations are created by the parcelLab return portal, or by the retailer via the parcelLab API.\n\nCertain fields of the return registration are not mutable via requests on the registration resource, but require\n'action' payloads to be submitted (e.g. 'AddLabel') to the 'mutate' action.","summary":"Apply Return Option","parameters":[{"in":"path","name":"external_id","schema":{"type":"string","format":"uuid","title":"External Identifier","description":"Unique identifier for this return registration, generated by parcelLab"},"required":true}],"tags":["Return Registration"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnOptionRequestRequest"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/ReturnOptionRequestRequest"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/ReturnOptionRequestRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReturnOptionResponse"}}},"description":""},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}},"description":""},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse403"}}},"description":""},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse404"}}},"description":""}}}}}} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.parcellab.com/docs/developers/returns/return-registrations.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.