Search for answers to common problems and get support from our team.

Support Menu

Contact Support

ReturnGroupSerializer V2

Overview

The ReturnGroupSerializer provides a structured representation of a return group in the v2 API, encompassing associated returns, shipments, orders, customers, exchange items, and refund transactions.

Main Schema: ReturnGroupSerializer

Description

A serializer for the ReturnGroup model that delivers a complete representation of a return group, including related sub-entities.

Fields

FieldTypeRequired?Description
idintegerYesUnique identifier for the return group
return_methodstringYesReturn method (e.g., "shipping", "in_store")
credit_methodstringNoRefund/credit method (e.g., "refund", "store_credit")
created_atstringYesISO 8601 timestamp of creation
updated_atstringYesISO 8601 timestamp of last update
orderOrderSerializerYesAssociated order details
customerCustomerSerializerYesCustomer details
shipmentsarray[ShipmentSerializer]YesAssociated shipments
returnsarray[ReturnSerializer]YesList of returns
exchange_line_itemsarray[ExchangeLineItemSerializer]YesExchange line items
refund_transactionsarray[RefundTransactionSerializer]YesRefund transactions

Example Response

 

{
  "id": 12345,
  "return_method": "shipping",
  "credit_method": "refund",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-16T14:45:00Z",
  "order": {
    "id": 67890,
    "platform_id": "gid://shopify/Order/123456789",
    "name": "#1001",
    "created_at": "2024-01-10T09:00:00Z",
    "source_name": "web",
    "fulfilled_at": "2024-01-12T15:30:00Z",
    "taxes_included": true
  },
  "customer": {
    "name": "John Doe",
    "email": "john.doe@example.com"
  },
  "shipments": [
    {
      "id": 111,
      "status": "DELIVERED",
      "carrier": "FedEx",
      "tracking_number": "123456789012",
      "created_at": "2024-01-13T08:00:00Z"
    }
  ],
  "returns": [
    {
      "id": 222,
      "platform_id": "gid://shopify/Return/987654321",
      "created_at": "2024-01-15T10:30:00Z",
      "status": "OPEN",
      "shipment_id": 111,
      "product_platform_id": "gid://shopify/Product/456789",
      "product_name": "Cotton T-Shirt",
      "variant_platform_id": "gid://shopify/ProductVariant/789012",
      "variant_name": "Medium / Blue",
      "sku": "TSHIRT-M-BLUE",
      "quantity": 1,
      "return_reason": "Wrong size",
      "return_note": "Ordered medium but need large",
      "subtotal": {
        "shop_money": {
          "amount": 25.0,
          "currency_code": "USD"
        },
        "presentment_money": {
          "amount": 25.0,
          "currency_code": "USD"
        }
      },
      "discounted_subtotal": {
        "shop_money": {
          "amount": 20.0,
          "currency_code": "USD"
        },
        "presentment_money": {
          "amount": 20.0,
          "currency_code": "USD"
        }
      },
      "tax_total": {
        "shop_money": {
          "amount": 1.6,
          "currency_code": "USD"
        },
        "presentment_money": {
          "amount": 1.6,
          "currency_code": "USD"
        }
      },
      "total": {
        "shop_money": {
          "amount": 21.6,
          "currency_code": "USD"
        },
        "presentment_money": {
          "amount": 21.6,
          "currency_code": "USD"
        }
      }
    }
  ],
  "exchange_line_items": [
    {
      "id": "exch_001",
      "product_platform_id": "gid://shopify/Product/456789",
      "product_name": "Cotton T-Shirt",
      "variant_platform_id": "gid://shopify/ProductVariant/789013",
      "variant_name": "Large / Blue",
      "sku": "TSHIRT-L-BLUE",
      "quantity": 1,
      "subtotal": {
        "shop_money": {
          "amount": 25.0,
          "currency_code": "USD"
        },
        "presentment_money": {
          "amount": 25.0,
          "currency_code": "USD"
        }
      },
      "discounted_subtotal": {
        "shop_money": {
          "amount": 20.0,
          "currency_code": "USD"
        },
        "presentment_money": {
          "amount": 20.0,
          "currency_code": "USD"
        }
      },
      "tax_total": {
        "shop_money": {
          "amount": 1.6,
          "currency_code": "USD"
        },
        "presentment_money": {
          "amount": 1.6,
          "currency_code": "USD"
        }
      },
      "total": {
        "shop_money": {
          "amount": 21.6,
          "currency_code": "USD"
        },
        "presentment_money": {
          "amount": 21.6,
          "currency_code": "USD"
        }
      }
    }
  ],
  "refund_transactions": [
    {
      "platform_id": "gid://shopify/Refund/555666777",
      "amount": {
        "shop_money": {
          "amount": 21.6,
          "currency_code": "USD"
        },
        "presentment_money": {
          "amount": 21.6,
          "currency_code": "USD"
        }
      },
      "gateway": "shopify_payments"
    }
  ]
}

 

🧩 Subtypes

👤 CustomerSerializer

FieldTypeRequiredDescription
namestringYesFull name of the customer
emailstringYesCustomer's email address

Example

{
  "name": "John Doe",
  "email": "john.doe@example.com"
}

📦 OrderSerializer

FieldTypeRequiredDescription
idintegerYesUnique order ID
platform_idstringYesPlatform-specific ID
namestringYesOrder number (e.g. #1001)
created_atstringYesISO 8601 creation timestamp
source_namestringNoOrder source (web, pos, etc.)
fulfilled_atstringNoFulfillment timestamp
taxes_includedbooleanYesIf taxes are included in pricing

Example

{
  "id": 67890,
  "platform_id": "gid://shopify/Order/123456789",
  "name": "#1001",
  "created_at": "2024-01-10T09:00:00Z",
  "source_name": "web",
  "fulfilled_at": "2024-01-12T15:30:00Z",
  "taxes_included": true
}

🚚 ShipmentSerializer

FieldTypeRequiredDescription
idintegerYesShipment ID
statusstringYes

Shipment status. Possible Values:

  1. DRAFT
  2. CREATED
  3. IN_TRANSIT
  4. DELIVERED
  5. FAILED
  6. CANCELED
carrierstringNoCarrier name
tracking_numberstringNoTracking number
created_atstringYesCreation timestamp

Example

{
  "id": 111,
  "status": "DELIVERED",
  "carrier": "FedEx",
  "tracking_number": "123456789012",
  "created_at": "2024-01-13T08:00:00Z"
}

🔁 ReturnSerializer

FieldTypeRequiredDescription
idintegerYesReturn ID
platform_idstringNoPlatform return ID
created_atstringYesReturn creation timestamp
statusstringYes

Return status. Possible values:

  1. IN_REVIEW
  2. OPEN
  3. COMPLETED
  4. CANCELED
shipment_idintegerNoLinked shipment ID
product_platform_idstringYesPlatform product ID
product_namestringYesName of the product
variant_platform_idstringYesPlatform variant ID
variant_namestringYesName of the product variant
skustringNoSKU
quantityintegerYesQuantity returned
return_reasonstringYesReason provided
return_notestringNoOptional customer note
subtotalMoneyBagYesPre-discount price
discounted_subtotalMoneyBagYesPost-discount price
tax_totalMoneyBagYesTax total
totalMoneyBagYesFinal total

Example

{
  "id": 222,
  "platform_id": "gid://shopify/Return/987654321",
  "created_at": "2024-01-15T10:30:00Z",
  "status": "OPEN",
  "shipment_id": 111,
  "product_platform_id": "gid://shopify/Product/456789",
  "product_name": "Cotton T-Shirt",
  "variant_platform_id": "gid://shopify/ProductVariant/789012",
  "variant_name": "Medium / Blue",
  "sku": "TSHIRT-M-BLUE",
  "quantity": 1,
  "return_reason": "Wrong size",
  "return_note": "Ordered medium but need large",
  "subtotal": {
    "shop_money": {
      "amount": 25.0,
      "currency_code": "USD"
    },
    "presentment_money": {
      "amount": 25.0,
      "currency_code": "USD"
    }
  },
  "discounted_subtotal": {
    "shop_money": {
      "amount": 20.0,
      "currency_code": "USD"
    },
    "presentment_money": {
      "amount": 20.0,
      "currency_code": "USD"
    }
  },
  "tax_total": {
    "shop_money": {
      "amount": 1.6,
      "currency_code": "USD"
    },
    "presentment_money": {
      "amount": 1.6,
      "currency_code": "USD"
    }
  },
  "total": {
    "shop_money": {
      "amount": 21.6,
      "currency_code": "USD"
    },
    "presentment_money": {
      "amount": 21.6,
      "currency_code": "USD"
    }
  }
}

🔄 ExchangeLineItemSerializer

FieldTypeRequiredDescription
idstringYesExchange item ID
product_platform_idstringYesProduct ID
product_namestringYesName of the product
variant_platform_idstringYesVariant ID
variant_namestringYesVariant name
skustringNoSKU
quantityintegerYesQuantity exchanged
subtotalMoneyBagYesPre-discount subtotal
discounted_subtotalMoneyBagYesPost-discount subtotal
tax_totalMoneyBagYesTax total
totalMoneyBagYesTotal

Example

{
  "id": "exch_001",
  "product_platform_id": "gid://shopify/Product/456789",
  "product_name": "Cotton T-Shirt",
  "variant_platform_id": "gid://shopify/ProductVariant/789013",
  "variant_name": "Large / Blue",
  "sku": "TSHIRT-L-BLUE",
  "quantity": 1,
  "subtotal": {
    "shop_money": {
      "amount": 25.0,
      "currency_code": "USD"
    },
    "presentment_money": {
      "amount": 25.0,
      "currency_code": "USD"
    }
  },
  "discounted_subtotal": {
    "shop_money": {
      "amount": 20.0,
      "currency_code": "USD"
    },
    "presentment_money": {
      "amount": 20.0,
      "currency_code": "USD"
    }
  },
  "tax_total": {
    "shop_money": {
      "amount": 1.6,
      "currency_code": "USD"
    },
    "presentment_money": {
      "amount": 1.6,
      "currency_code": "USD"
    }
  },
  "total": {
    "shop_money": {
      "amount": 21.6,
      "currency_code": "USD"
    },
    "presentment_money": {
      "amount": 21.6,
      "currency_code": "USD"
    }
  }
}

💸 RefundTransactionSerializer

FieldTypeRequiredDescription
platform_idstringNoPlatform-specific refund ID
amountMoneyBagYesRefund amount
gatewaystringNoPayment gateway used

Example

{
  "platform_id": "gid://shopify/Refund/555666777",
  "amount": {
    "shop_money": {
      "amount": 21.6,
      "currency_code": "USD"
    },
    "presentment_money": {
      "amount": 21.6,
      "currency_code": "USD"
    }
  },
  "gateway": "shopify_payments"
}

MoneyBag

FieldTypeRequiredDescription
shop_moneyMoneySerializerYesAmount in shop's base currency
presentment_moneyMoneySerializerYesAmount in customer’s local currency

MoneySerializer

FieldTypeRequiredDescription
amountfloatYesAmount
currency_codestringYesCurrency code (ISO 4217)

Related Links