Create return request

POST /Return/CreateReturnRequest — OMS API · Cancellation & Return

Creates a return package (return request) for a shipped package and returns the return code (RMA) that the customer will give to the cargo. The request appears on the seller's return requests screen; the result is reported via ReturnOrderPackageConfirmedEvent / ReturnOrderPackageRejectedEvent webhooks.

When to call: When the customer initiates a return.

  • Send as many lines in returnPackageItemLines as the quantity to be returned; sourceOrderItemLineId values must be unique.
  • Use GetStatusReasonByType (statusType=Returned) for reasonId.
  • If carrierCode is not sent, the system selects the appropriate cargo company.
  • If products belong to different seller packages, if there are products not belonging to the package, or if sourceReturnPackageId has already been used, HTTP 200 with isSuccess: false is returned.

İstek gövdesi

  • pickupDate (string): Date when the cargo will pick up the return (parsable date/time string).
  • carrierCode (string): Return cargo company code. If not sent, the system selects the appropriate company.
  • isConfirmed (boolean): Whether the return will be opened as approved. Default is false (falls to seller approval).
  • locationCode (string): Location code where the return will be delivered.
  • sourcePackageId (string, zorunlu): The sourcePackageId value of the returned shipment package.
  • returnPackageItems (object[], zorunlu): Returned items.
    • returnPackageItems.quantity (integer<int32>, zorunlu): Return quantity.
    • returnPackageItems.sourceOrderItemId (string, zorunlu): The sourceOrderItemId value of the returned item.
    • returnPackageItems.returnPackageItemLines (object[]): Returned lines; send as many lines as the quantity.
      • returnPackageItems.returnPackageItemLines.reasonId (integer<int32>, zorunlu): Return reason ID; the id from GetStatusReasonByType (statusType=Returned) response.
      • returnPackageItems.returnPackageItemLines.reasonDesc (string): Return description.
      • returnPackageItems.returnPackageItemLines.sourceOrderItemLineId (string, zorunlu): The sourceOrderItemLineId value of the returned line; must be unique.
      • returnPackageItems.returnPackageItemLines.returnPackageItemLinePhotos (object[]): Photos related to the line.
  • returnPickupAddress (object): Address where the return will be picked up.
    • returnPickupAddress.phone (string, zorunlu): Phone number.
    • returnPickupAddress.region (string): Region information.
    • returnPickupAddress.isValid (boolean): Whether the address is verified.
    • returnPickupAddress.zipCode (string, zorunlu): Postal code.
    • returnPickupAddress.cityCode (string): City code.
    • returnPickupAddress.cityName (string, zorunlu): City name.
    • returnPickupAddress.lastName (string, zorunlu): Recipient's last name.
    • returnPickupAddress.firstName (string, zorunlu): Recipient's first name.
    • returnPickupAddress.stateCode (string): State/region code.
    • returnPickupAddress.stateName (string): State/region name (for international addresses).
    • returnPickupAddress.taxNumber (string): Tax number (for corporate invoices).
    • returnPickupAddress.taxOffice (string): Tax office (for corporate invoices).
    • returnPickupAddress.streetCode (string): Street code.
    • returnPickupAddress.streetName (string): Street name.
    • returnPickupAddress.addressType (string, zorunlu): Address type: Shipment (delivery) or Invoice (billing).
    • returnPickupAddress.companyName (string): Company name (for corporate invoices).
    • returnPickupAddress.countryName (string, zorunlu): Country name.
    • returnPickupAddress.phonePrefix (string): Phone country code prefix.
    • returnPickupAddress.addressLine1 (string, zorunlu): Address line 1.
    • returnPickupAddress.addressLine2 (string, zorunlu): Address line 2. This field is mandatory; if there is no second line, send a value like -.
    • returnPickupAddress.buildingCode (string): Building code.
    • returnPickupAddress.districtCode (string): District code.
    • returnPickupAddress.districtName (string, zorunlu): District name.
    • returnPickupAddress.provinceName (string): Province name (for international addresses).
    • returnPickupAddress.identityNumber (string): Identity number (for individual invoices).
    • returnPickupAddress.sourceAddressId (string, zorunlu): The ID of the address in your system; must be unique within the order (can be 1, 2, etc.).
    • returnPickupAddress.externalCityCode (string): External system code for the city.
    • returnPickupAddress.formattedAddress (string): Formatted full address text.
    • returnPickupAddress.neighborhoodCode (string): Neighborhood code.
    • returnPickupAddress.addressAttributes (object[]): Additional fields related to the address.
      • returnPickupAddress.addressAttributes.attributeKey (string, zorunlu): Additional field name.
      • returnPickupAddress.addressAttributes.attributeValue (string, zorunlu): Additional field value.
    • returnPickupAddress.externalStateCode (string): External system code for the state/region.
    • returnPickupAddress.neighbourhoodName (string): Neighborhood name.
    • returnPickupAddress.externalStreetCode (string): External system code for the street.
    • returnPickupAddress.externalAddressCode (string): External system code for the address.
    • returnPickupAddress.externalBuildingCode (string): External system code for the building.
    • returnPickupAddress.externalDistrictCode (string): External system code for the district.
    • returnPickupAddress.externalNeighborhoodCode (string): External system code for the neighborhood.
  • sourceReturnPackageId (string): The ID you will assign to the return package. If empty, OMS generates it; a second return with the same ID will be rejected.

Yanıtlar

  • 200: Successful. Always check the isSuccess field in the body.
  • 400: Body validation failed (missing required field, type mismatch, or malformed JSON). Response is in ASP.NET Core ValidationProblemDetails format; the errors field indicates which field is invalid.
  • 401: Authorization header missing, token invalid or expired. Body returns empty; obtain a new token via /Auth/login.
  • 500: Unexpected server error. This response returns with PascalCase field names (unlike other responses) and includes null fields.

200 yanıt alanları

  • data (object): Created refund package.
    • data.rmaCode (string): Return (RMA) code that the customer will give to the cargo.
    • data.cargoName (string): Return cargo company name.
    • data.carrierCode (string): Return cargo company code.
    • data.rmaExpireDay (integer<int32>): Number of days the RMA code is valid.
    • data.rmaExpireDate (string<date-time>): Expiration of the RMA code validity.
    • data.refundPayments (object[]): Created payment refunds. Returned only if not empty.
      • data.refundPayments.total (number<double>): Payment amount.
      • data.refundPayments.status (integer<int32>): Return status code.
      • data.refundPayments.authCode (string): Provision code. Returns only if populated.
      • data.refundPayments.interest (number<double>): Maturity difference.
      • data.refundPayments.paidDate (string<date-time>): Payment time. Returns only if populated.
      • data.refundPayments.posPoint (number<double>): POS points. Returns only if populated.
      • data.refundPayments.refundId (string): Return record ID.
      • data.refundPayments.createdOn (string<date-time>): Creation time. Returns only if populated.
      • data.refundPayments.statusName (string): Return status name.
      • data.refundPayments.paymentType (string): Payment type.
      • data.refundPayments.refundTotal (number<double>): Amount to be refunded.
      • data.refundPayments.transactionId (string): Transaction ID. Returns only if populated.
      • data.refundPayments.paymentMethodId (string): Payment method ID.
      • data.refundPayments.transactionCode (string): Transaction code. Returns only if populated.
      • data.refundPayments.captureTransactionId (string): Collection transaction ID. Returns only if populated.
    • data.returnPackageId (string): ID of the created return package.
  • isSuccess (boolean, zorunlu): true if the return request was created.
  • statusCode (string): Not used; usually null.
  • errorMesssage (string): Error message. Returned only if there is an error.