Schemas

The customer's address where the rider will pick up the return item.

Where the picked-up item should be delivered — either the seller's address (RTS) or your warehouse (RTO).

List of items being picked up. At least one item required.

Customer name. Truncated to 100 characters.

Customer phone number. 10-14 characters, digits and an optional leading +. Sent through as given — no country-code stripping happens on this field.

Full pickup address.

6-digit pickup pincode.

Second line of the pickup address.

Secondary phone number for the customer.

GPS accuracy of the supplied coordinates — L (over 500m), H (100-500m), G (under 100m). A value outside this set is dropped rather than rejected.

Type of pickup location. A value outside this set is dropped rather than rejected.

Customer's state.

seller — return to the seller (RTS). origin or warehouse — return to your warehouse (RTO); the two behave identically.

Full return address.

6-digit return destination pincode.

Seller name or warehouse name. Required for seller return type.

Contact number. Required for seller return type. Optional otherwise. A leading +91 or 91 is stripped on this field.

Your internal identifier for this seller or warehouse location.

Your unique order identifier. Sending the same ID twice returns the existing order instead of creating a duplicate.

Your own tracking number. If not provided, Shadowfax auto-assigns one.

Product value. If Rs. 50,000 or above, eway_bill becomes mandatory.

Total order amount including taxes.

GST e-way bill number (exactly 12 digits). Mandatory when price is Rs. 50,000 or above.

regular — standard pickup. slot — pickup in a chosen window; requires preferred_start_time and preferred_end_time. self_drop — customer drops the item off; cannot be combined with a seller return type. surface — surface transport, enabled per account.

Invoice date. Format: YYYY-MM-DD.

Actual weight in kilograms. Sending grams will place the shipment in the highest weight slab.

Volumetric weight in kilograms. Sending grams will place the shipment in the highest weight slab.

Name of the reseller, if applicable.

Start of the requested pickup window. Required when pickup_type is slot.

End of the requested pickup window. Required when pickup_type is slot.

Optional extras. return_otp must be exactly 4 digits if supplied. rider_name must be a non-empty string if supplied.

Product name.

Item price.

Your SKU identifier.

Reason for return — free text or your internal reason code.

Whether the rider should perform a quality check before accepting the item.

HSN code for GST classification.

Invoice number for this item.

Registered seller details for GST/tax purposes.

Tax breakdown for the item.

Extra item attributes for QC and handling.

Custom quality check questions the rider must verify during pickup.

Seller's GSTIN number.

Product image URLs for rider QC reference.

Number of units.

Unit of measurement (e.g. pcs, kg).

IMEI number for electronics.

Serial number for the item.

Flag for items needing special handling.

Category of special handling required.

The QC question shown to the rider.

Whether the rider must answer this before completing pickup.

Expected answer or reference value.

Always null on success.

Error details — either a string message or an object with field-level validation errors.

Masked empty in tracking responses.

Masked empty in tracking responses.

Masked empty in tracking responses.

ISO 8601 timestamp.

ISO 8601 timestamp.

Empty in tracking responses.

Client's SKU identifier.

Product name.

Arbitrary key-value pairs (color, size, etc.).

Whether this SKU was physically collected by the rider.

passed — QC passed at doorstep. fail — QC failed at doorstep. fail_hub — QC failed at hub.

Rider or hub QC remarks.

Seller details as returned in tracking SKU objects. Field names differ from the order creation schema.

Tax breakdown as returned in tracking SKU objects.

Images captured during QC (URLs).

Registered seller name.

Registered seller address.

ISO 8601 timestamp of the transition.

Hub or location name where the event occurred.

Display name of the state. The values in use are: New, Assigned, Out For Pickup, Picked, Received, Cancelled, Cid, Not Contactable, Not Attempted, Undelivered, On Hold, Returned To Client, QC Failed, Lost, Pending Inscan, Item added to Bag, Bag In Transit, Bag Received, Bag Received at Via, Received at Return DC, In Transit for RTS, In Transit for RTO, Bag in transit for return, Received at RTS destination hub, Return Shipment Out for Delivery, Return to Seller initiated. Treat this as an open set — an event whose state is not recognised falls back to the raw internal label, so match on known values and pass anything else through unchanged.

Additional context about the event.

Client's order identifier.

Always 'pickup' for reverse logistics orders.

AWB number (same as the path parameter).

Shadowfax client ID.

Return destination pincode. Null if not set.

Always null in tracking responses.

Address structure returned in tracking responses. PII fields (name, phone_number, address_line) are masked empty for privacy.

Seller/return address. Null for RTO orders.

ISO 8601 timestamp of the last status update.

Current status of the order, as a display name.

Scheduled pickup date as milliseconds since epoch.

Order creation date as milliseconds since epoch.

Confirmed pickup type.

Chronological list of all state transitions.

Start of the agreed pickup window. Set only for slot pickups, null otherwise.

End of the agreed pickup window. Set only for slot pickups, null otherwise.

List of AWB numbers to track. Maximum 50.

AWB number or your client_order_id identifying the order to cancel.

Reason for cancellation.

AWB number of the order to update.

Updated customer pickup details. Cannot be modified after Out For Pickup.

Updated return/seller details. Cannot be modified after RTS/RTO phase begins.

Updated order-level metadata.

Updated SKU/product information.

Customer phone number.

Customer alternate phone number.

Updated pickup address.

Updated pickup pincode.

Return destination contact number.

Updated return destination pincode.

Updated return address.

Whether to capture image at delivery.

GST e-way bill number (exactly 12 digits).

E-way bill number for the return leg.

Invoice number.

Actual weight in grams.

Volumetric weight in grams.

Shadowfax internal SKU ID (if known).

Your SKU identifier.

Product name.

Seller details as returned in tracking SKU objects. Field names differ from the order creation schema.

Tax breakdown as returned in tracking SKU objects.

Arbitrary key-value pairs (color, size, etc.).

List of AWB numbers. Maximum 100.

Dictionary keyed by AWB number with POD information.

Who took delivery. Null when the captured value is outside this set.

Name of the person who received the item. Comes back as the literal string "None" when it was not captured.

Contact number of the recipient. Comes back as the literal string "None" when it was not captured.

URL of the recipient's signature image. Comes back as the literal string "None" when no signature was captured — not JSON null.

Number of AWB numbers to generate. Default 1000, maximum 350,000.

List of generated AWB numbers.

6-digit pincode.

List of service tiers available for this pincode (e.g., 'Regular', 'Surface').

Error message.

HTTP status code.

Success message.

HTTP status code.

Reason for the failure. Carries the same text as message rather than a separate code.

Human-readable error message.

Your client_order_id from the original request.

The AWB of the existing order. Note the field name differs from awb_number on a fresh creation.

pickup for reverse orders.

Display status, title-case (e.g. New) — differs from the lower-case new returned on a fresh creation.

Pickup address as stored.

SKUs as stored.