> ## Documentation Index > Fetch the complete documentation index at: https://docs.frate.com/llms.txt > Use this file to discover all available pages before exploring further. # Return Groups > Manage returns through the Frate API ## OpenAPI ````yaml GET /v2/return-groups openapi: 3.1.0 info: title: Frate Returns API version: 0.1.0 servers: - url: /api security: [] paths: /v2/return-groups: get: summary: Return Groups description: Public API return groups endpoint operationId: return_groups_v2_return_groups_get parameters: - name: return_group_id in: query required: false schema: anyOf: - type: integer - type: 'null' title: Return Group Id - name: email in: query required: false schema: anyOf: - type: string - type: 'null' title: Email - name: order_id in: query required: false schema: anyOf: - type: integer - type: 'null' title: Order Id - name: order_name in: query required: false schema: anyOf: - type: string - type: 'null' title: Order Name - name: tracking_code in: query required: false schema: anyOf: - type: string - type: 'null' title: Tracking Code - name: min_created_at in: query required: false schema: anyOf: - type: string format: date-time - type: 'null' title: Min Created At - name: max_created_at in: query required: false schema: anyOf: - type: string format: date-time - type: 'null' title: Max Created At - name: min_updated_at in: query required: false schema: anyOf: - type: string format: date-time - type: 'null' title: Min Updated At - name: max_updated_at in: query required: false schema: anyOf: - type: string format: date-time - type: 'null' title: Max Updated At - name: min_shipped_at in: query required: false schema: anyOf: - type: string format: date-time - type: 'null' title: Min Shipped At - name: max_shipped_at in: query required: false schema: anyOf: - type: string format: date-time - type: 'null' title: Max Shipped At - name: limit in: query required: false schema: anyOf: - type: integer - type: 'null' title: Limit - name: offset in: query required: false schema: anyOf: - type: integer - type: 'null' title: Offset - name: x-frate-api-token in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Frate-Api-Token responses: '200': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/ReturnGroupSerializer' title: Response Return Groups V2 Return Groups Get '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: ReturnGroupSerializer: properties: type: type: string const: return_group title: Type description: The type identifier for this resource default: return_group id: type: integer title: Id description: Unique identifier for the return group return_method: $ref: '#/components/schemas/ReturnMethodEnum' description: The method used for the return credit_method: anyOf: - $ref: '#/components/schemas/CreditMethodEnum' - type: 'null' description: The method used for crediting the customer created_at: type: string title: Created At description: ISO 8601 timestamp when the return group was created updated_at: type: string title: Updated At description: ISO 8601 timestamp when the return group was last updated return_outcome: anyOf: - $ref: '#/components/schemas/ReturnOutcomeEnum' - type: 'null' description: The outcome of the return order: $ref: '#/components/schemas/OrderSerializer' description: The associated order for this return group customer: $ref: '#/components/schemas/CustomerSerializer' description: The customer who initiated the return shipments: items: $ref: '#/components/schemas/ShipmentSerializer' type: array title: Shipments description: List of shipments associated with the returns in this group returns: items: $ref: '#/components/schemas/ReturnLineItemSerializer' type: array title: Returns description: List of individual returns that make up this return group exchange_line_items: items: $ref: '#/components/schemas/ExchangeLineItemSerializer' type: array title: Exchange Line Items description: Line items for exchanges if the customer chose to exchange items refund_transactions: items: $ref: '#/components/schemas/RefundTransactionSerializer' type: array title: Refund Transactions description: List of refund transactions processed for this return group suggested_refund: $ref: '#/components/schemas/SuggestedRefundSerializer' description: Suggested refund amount and breakdown for this return group type: object required: - id - return_method - created_at - updated_at - return_outcome - order - customer - shipments - returns - exchange_line_items - refund_transactions - suggested_refund title: ReturnGroup description: ReturnGroup HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError ReturnMethodEnum: type: string enum: - TRADITIONAL - SELF_SHIP - STORE_DROP_OFF - RETURN_BEAR - HAPPY_RETURNS - GLOBAL_E - ECODROP title: ReturnMethodEnum CreditMethodEnum: type: string enum: - STORE_CREDIT - ORIGINAL_PAYMENT_METHOD title: CreditMethodEnum ReturnOutcomeEnum: type: string enum: - credit - refund - exchange+refund - exchange - exchange+credit - upsell title: ReturnOutcomeEnum OrderSerializer: properties: type: type: string const: order title: Type description: The type identifier for this resource default: order id: type: integer title: Id description: Unique identifier for the order platform_id: type: string title: Platform Id description: The order ID from the e-commerce platform (e.g., Shopify order ID) name: type: string title: Name description: The order name/number as displayed on the platform tags: items: type: string type: array title: Tags description: Tags associated with the order created_at: type: string title: Created At description: ISO 8601 timestamp when the order was created on the platform source_name: anyOf: - type: string - type: 'null' title: Source Name description: The source name of the order (e.g., 'web', 'pos', 'mobile') fulfilled_at: anyOf: - type: string - type: 'null' title: Fulfilled At description: ISO 8601 timestamp when the order was fulfilled taxes_included: type: boolean title: Taxes Included description: Whether taxes are included in the order total type: object required: - id - platform_id - name - tags - created_at - taxes_included title: Order description: Order CustomerSerializer: properties: type: type: string const: customer title: Type description: The type identifier for this resource default: customer name: type: string title: Name description: The customer's full name email: type: string title: Email description: The customer's email address phone: anyOf: - type: string - type: 'null' title: Phone description: The customer's phone number type: object required: - name - email - phone title: Customer description: Customer ShipmentSerializer: properties: type: type: string const: shipment title: Type description: The type identifier for this resource default: shipment id: type: integer title: Id description: Unique identifier for the shipment status: $ref: '#/components/schemas/ShipmentStatusEnum' description: Current status of the shipment carrier: anyOf: - type: string - type: 'null' title: Carrier description: The shipping carrier (e.g., 'USPS', 'FedEx', 'UPS') tracking_number: anyOf: - type: string - type: 'null' title: Tracking Number description: The tracking number for the shipment created_at: type: string title: Created At description: ISO 8601 timestamp when the shipment was created origin_address: anyOf: - $ref: '#/components/schemas/AddressSerializer' - type: 'null' description: The origin address for the shipment destination_address: anyOf: - $ref: '#/components/schemas/AddressSerializer' - type: 'null' description: The destination address for the shipment shipped_at: anyOf: - type: string - type: 'null' title: Shipped At description: ISO 8601 timestamp when the shipment was shipped delivered_at: anyOf: - type: string - type: 'null' title: Delivered At description: ISO 8601 timestamp when the shipment was delivered return_group_id: anyOf: - type: integer - type: 'null' title: Return Group Id description: The ID of the return group for the shipment return_ids: items: type: integer type: array title: Return Ids description: The IDs of the returns for the shipment type: object required: - id - status - created_at title: Shipment description: Shipment ReturnLineItemSerializer: properties: type: type: string const: return_line_item title: Type description: The type identifier for this resource default: return_line_item id: type: integer title: Id description: Unique identifier for the return platform_id: anyOf: - type: string - type: 'null' title: Platform Id description: The return ID from the e-commerce platform created_at: type: string title: Created At description: ISO 8601 timestamp when the return was created status: $ref: '#/components/schemas/InternalReturnStatusEnum' description: Current status of the return shipment_id: anyOf: - type: integer - type: 'null' title: Shipment Id description: ID of the associated shipment for this return platform_refund_transaction_ids: items: type: string type: array title: Platform Refund Transaction Ids description: The refund transaction IDs from the e-commerce platform platform_line_item_id: type: string title: Platform Line Item Id description: The line item ID from the e-commerce platform product_platform_id: type: string title: Product Platform Id description: The product ID from the e-commerce platform product_name: type: string title: Product Name description: The name of the product being returned variant_platform_id: type: string title: Variant Platform Id description: The variant ID from the e-commerce platform variant_name: type: string title: Variant Name description: The name of the specific variant being returned sku: anyOf: - type: string - type: 'null' title: Sku description: The SKU (Stock Keeping Unit) of the item being returned barcode: anyOf: - type: string - type: 'null' title: Barcode description: The barcode of the item being returned quantity: type: integer title: Quantity description: The quantity of items being returned return_reason: type: string title: Return Reason description: The reason provided for the return deprecated: true return_note: anyOf: - type: string - type: 'null' title: Return Note description: Additional notes provided with the return deprecated: true return_reason_details: $ref: '#/components/schemas/ReturnReasonSerializer' description: The details of the reason provided for the return questions_answers: items: $ref: '#/components/schemas/QuestionAnswerSerializer' type: array title: Questions Answers description: The questions and answers provided for the return subtotal: $ref: '#/components/schemas/MoneyBag' description: The subtotal amount before discounts and taxes discounted_subtotal: $ref: '#/components/schemas/MoneyBag' description: The subtotal amount after discounts but before taxes discount_total: $ref: '#/components/schemas/MoneyBag' description: The total discount amount for this return tax_total: $ref: '#/components/schemas/MoneyBag' description: The total tax amount for this return tax_percentage: type: number title: Tax Percentage description: The tax percentage applied to this return total: $ref: '#/components/schemas/MoneyBag' description: The total amount for this return (including taxes and discounts) last_rma_number: anyOf: - type: string - type: 'null' title: Last Rma Number description: The last processed RMA number for this return last_rma_provider: anyOf: - $ref: '#/components/schemas/RmaPlatformEnum' - type: 'null' description: The last processed RMA provider for this return type: object required: - id - created_at - status - platform_refund_transaction_ids - platform_line_item_id - product_platform_id - product_name - variant_platform_id - variant_name - quantity - return_reason - return_reason_details - questions_answers - subtotal - discounted_subtotal - discount_total - tax_total - tax_percentage - total title: ReturnLineItem description: ReturnLineItem ExchangeLineItemSerializer: properties: type: type: string const: exchange_line_item title: Type description: The type identifier for this resource default: exchange_line_item id: type: string title: Id description: Unique identifier for the exchange line item line_item_platform_id: anyOf: - type: string - type: 'null' title: Line Item Platform Id description: >- The line item ID from the e-commerce platform. Note: This is only set for exchanges using the exchange API once the exchange has been processed product_platform_id: type: string title: Product Platform Id description: The product ID from the e-commerce platform product_name: type: string title: Product Name description: The name of the product being exchanged variant_platform_id: type: string title: Variant Platform Id description: The variant ID from the e-commerce platform variant_name: type: string title: Variant Name description: The name of the specific variant being exchanged sku: anyOf: - type: string - type: 'null' title: Sku description: The SKU (Stock Keeping Unit) of the item being exchanged status: $ref: '#/components/schemas/ExchangeLineItemStatusEnum' description: The status of the exchange line item quantity: type: integer title: Quantity description: The quantity of items being exchanged subtotal: $ref: '#/components/schemas/MoneyBag' description: The subtotal amount before discounts and taxes discounted_subtotal: $ref: '#/components/schemas/MoneyBag' description: The subtotal amount after discounts but before taxes discount_total: $ref: '#/components/schemas/MoneyBag' description: The total discount amount for this exchange item tax_total: $ref: '#/components/schemas/MoneyBag' description: The total tax amount for this exchange item tax_percentage: type: number title: Tax Percentage description: >- The total tax percentage for this exchange item (expressed as a percentage, not a decimal) total: $ref: '#/components/schemas/MoneyBag' description: >- The total amount for this exchange item (including taxes and discounts) type: object required: - id - line_item_platform_id - product_platform_id - product_name - variant_platform_id - variant_name - status - quantity - subtotal - discounted_subtotal - discount_total - tax_total - tax_percentage - total title: ExchangeLineItem description: ExchangeLineItem RefundTransactionSerializer: properties: type: type: string const: refund_transaction title: Type description: The type identifier for this resource default: refund_transaction platform_id: anyOf: - type: string - type: 'null' title: Platform Id description: The transaction ID from the payment platform amount: $ref: '#/components/schemas/MoneyBag' description: The refund amount for this transaction gateway: anyOf: - type: string - type: 'null' title: Gateway description: The payment gateway used for the refund (e.g., 'stripe', 'paypal') type: object required: - amount title: RefundTransaction description: RefundTransaction SuggestedRefundSerializer: properties: type: type: string const: suggested_refund title: Type description: The type identifier for this resource default: suggested_refund refund_total: $ref: '#/components/schemas/MoneyBag' description: The total suggested refund amount for the return group return_total: $ref: '#/components/schemas/MoneyBag' description: The total value of items being returned return_tax_total: $ref: '#/components/schemas/MoneyBag' description: The total tax amount for returned items exchange_total: $ref: '#/components/schemas/MoneyBag' description: The total value of items being exchanged exchange_tax_total: $ref: '#/components/schemas/MoneyBag' description: The total tax amount for exchanged items handling_fee: $ref: '#/components/schemas/MoneyBag' description: The handling fee for the return group shipping_fee: $ref: '#/components/schemas/MoneyBag' description: The shipping fee for the return group store_credit_incentive: $ref: '#/components/schemas/MoneyBag' description: The store credit incentive for the return group type: object required: - refund_total - return_total - return_tax_total - exchange_total - exchange_tax_total - handling_fee - shipping_fee - store_credit_incentive title: SuggestedRefund description: SuggestedRefund ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError ShipmentStatusEnum: type: string enum: - DRAFT - CREATED - IN_TRANSIT - DELIVERED - FAILED - CANCELED - UNKNOWN title: ShipmentStatusEnum AddressSerializer: properties: address1: type: string title: Address1 description: The first line of the address address2: anyOf: - type: string - type: 'null' title: Address2 description: The second line of the address city: type: string title: City description: The city of the address province: anyOf: - type: string - type: 'null' title: Province description: The province of the address zip: type: string title: Zip description: The zip code of the address country: type: string title: Country description: The country of the address type: object required: - address1 - city - province - zip - country title: Address description: Address InternalReturnStatusEnum: type: string enum: - IN_REVIEW - OPEN - COMPLETED - CANCELED title: InternalReturnStatusEnum ReturnReasonSerializer: properties: type: type: string const: return_reason title: Type description: The type identifier for this resource default: return_reason value: type: string title: Value description: The reason provided for the return label: type: string title: Label description: The label of the reason path: items: type: string type: array title: Path description: The path to the reason in reasons tree path_labels: items: type: string type: array title: Path Labels description: The path to the reason in reasons tree in labels note: anyOf: - type: string - type: 'null' title: Note description: Additional notes provided by user for the return type: object required: - value - label - path - path_labels - note title: ReturnReason description: ReturnReason QuestionAnswerSerializer: properties: type: type: string const: question_answer title: Type description: The type identifier for this resource default: question_answer question_text: type: string title: Question Text description: The question text question_description: type: string title: Question Description description: The question description question_type: type: string enum: - TEXT - SELECT title: Question Type description: The type of question answers: items: type: string type: array title: Answers description: The text answer or selected options type: object required: - question_text - question_description - question_type - answers title: QuestionAnswer description: QuestionAnswer MoneyBag: properties: shop_money: $ref: '#/components/schemas/MoneySerializer' description: The amount in the shop's currency presentment_money: $ref: '#/components/schemas/MoneySerializer' description: The amount in the presentment currency type: object title: MoneyBag description: MoneyBag RmaPlatformEnum: type: string enum: - SHIPWIRE - TWO_BOXES - RETURN_BEAR - BLADE - TRACKSTAR - MANUAL - SHIPHERO - HAPPY_RETURNS title: RmaPlatformEnum ExchangeLineItemStatusEnum: type: string enum: - UNPROCESSED - PROCESSED - CANCELED title: ExchangeLineItemStatusEnum MoneySerializer: properties: amount: type: number title: Amount default: 0 currency_code: $ref: '#/components/schemas/CurrencyCodeEnum' default: USD type: object title: MoneySerializer description: Money CurrencyCodeEnum: type: string enum: - USD - EUR - GBP - JPY - CNY - CAD - AUD - CHF - AED - AFN - BDT - BHD - BND - BTN - HKD - IDR - ILS - INR - IQD - IRR - JOD - KHR - KRW - KWD - KZT - LAK - LKR - MMK - MNT - MOP - MVR - MYR - NPR - OMR - PHP - PKR - QAR - SAR - SGD - THB - TWD - UZS - VND - YER - BWP - CDF - DJF - EGP - ERN - ETB - GHS - GMD - GNF - KES - KMF - LRD - LSL - MAD - MGA - MWK - MZN - NAD - NGN - RWF - SDG - SLL - SOS - SSP - TND - TZS - UGX - ZAR - ZMW - ARS - BBD - BMD - BOB - BRL - BSD - BZD - CLP - COP - CRC - CUP - DOP - FKP - GYD - HNL - JMD - KID - KYD - MXN - NIO - PAB - PEN - PYG - SRD - TTD - UYU - VED - VES - ALL - AMD - AZN - BAM - BGN - BYN - CZK - DKK - GEL - HRK - HUF - ISK - LTL - LVL - MDL - MKD - NOK - PLN - RON - RSD - RUB - SEK - TRY - UAH - FJD - NZD - PGK - SBD - TOP - VUV - WST - AOA - ANG - AWG - BIF - CVE - LBP - LYD - MRU - MUR - SCR - SHP - STN - SYP - SZL - TJS - TMT - XAF - XCD - XOF - XPF - XXX - GIP - JEP - SLE title: CurrencyCodeEnum ````