Return Orders

Return orders represent customer returns processed through PostCo. Each return order includes details about returned items, refund status, shipping information, and exchange requests. Use this endpoint to sync return data to your warehouse management system, build custom reporting, or trigger automated workflows based on return status changes.

Return Order model

The return order model contains comprehensive information about a customer's return request, including customer details, order references, status, line items (exchanges and refunds), shipping method, and shipment tracking.

Properties

Name
id
Type
integer
Description
Unique identifier for the return order.
Name
cust_email
Type
string
Description
Customer's email address.
Name
cust_phone
Type
string
Description
Customer's phone number.
Name
cust_first_name
Type
string
Description
Customer's first name.
Name
cust_last_name
Type
string
Description
Customer's last name.
Name
status
Type
string
Description
Current status of the return order. Most returns follow this progression: pending → reviewed → received → resolving → completing → completed. Other statuses represent exception states or specific workflows.
Possible values:
- pending - Return has been submitted and is awaiting review
- reviewed - Return has been reviewed and approved
- received - Items have been received at the warehouse
- resolving - Return is being processed
- pending_payment_from_customer - Awaiting payment from customer
- stripe_account_disabled - Payment processing unavailable
- pending_action - Requires manual action
- completing - Return is being completed
- handle_manually - Requires manual handling
- completed - Return has been fully processed
- rejected - Return was rejected
- archived - Return has been archived
Name
currency
Type
string
Description
ISO 4217 currency code (e.g., "USD", "EUR", "GBP").
Name
order_id
Type
string
Description
The original order ID from your e-commerce platform.
Name
order_name
Type
string
Description
The original order name/number (e.g., "ORDER-001").
Name
order_created_at
Type
datetime
Description
ISO8601 timestamp when the original order was created.
Name
submitted_at
Type
datetime
Description
ISO8601 timestamp when the return was submitted by the customer.
Name
reviewed_at
Type
datetime
Description
ISO8601 timestamp when the return was reviewed. null if not yet reviewed.
Name
received_at
Type
datetime
Description
ISO8601 timestamp when the return items were received. null if not yet received.
Name
resolved_at
Type
datetime
Description
ISO8601 timestamp when the return was resolved. null if not yet resolved.
Name
completed_at
Type
datetime
Description
ISO8601 timestamp when the return was completed. null if not yet completed.
Name
archived_at
Type
datetime
Description
ISO8601 timestamp when the return was archived. null if not archived.
Name
unarchived_at
Type
datetime
Description
ISO8601 timestamp when the return was unarchived. null if never unarchived.
Name
rejected_at
Type
datetime
Description
ISO8601 timestamp when the return was rejected. null if not rejected.
Name
updated_at
Type
datetime
Description
ISO8601 timestamp of the last update to the return order.
Name
exchanges
Type
array
Description
Array of exchange items. See Exchange model below.
Name
refunds
Type
array
Description
Array of refund items. See Refund model below.
Name
shipping_method
Type
object
Description
Shipping method used for the return. See Shipping Method model below. null if not applicable.
Name
shipment
Type
object
Description
Shipment tracking and label information. See Shipment model below. null if not applicable.

Exchange model

Exchange items represent products that the customer is exchanging for different products or variants.

Properties

Name
id
Type
integer
Description
Unique identifier for the exchange item.
Name
line_item_id
Type
string
Description
ID of the line item from the original order.
Name
product_id
Type
string
Description
Product ID from your e-commerce platform.
Name
variant_id
Type
string
Description
Variant ID from your e-commerce platform.
Name
product_title
Type
string
Description
Name of the product being returned.
Name
variant_title
Type
string
Description
Variant details (e.g., size, color).
Name
status
Type
string
Description
Status of the exchange item.
Possible values:
- pending - Exchange request is awaiting approval
- approved - Exchange request has been approved
- rejected - Exchange request has been rejected
- received - Returned item has been received at the warehouse
- resolved - Exchange decision has been finalized
- pending_exchange - Approved exchange is awaiting fulfillment
- completed - Exchange has been completed and new item shipped
Name
sku
Type
string
Description
Product SKU code.
Name
vendor
Type
string
Description
Product vendor or brand.
Name
extra_note
Type
string
Description
Customer's note or reason for the exchange.
Name
reject_reason
Type
string
Description
Reason for rejection if status is rejected. null otherwise.
Name
keep_item
Type
boolean
Description
When true, no return shipment is required for this item. The exchange is still approved and processed.
Name
shop_price
Type
object
Description
Original price of the item in shop currency. Money object with amount (string) and currency (string).
Name
return_item_price
Type
object
Description
Original price of the item in presentment currency. Money object with amount (string) and currency (string).
Name
tax_price
Type
object
Description
Tax amount for the item in presentment currency. Money object with amount (string) and currency (string).
Name
discount_amount
Type
object
Description
Discount applied to the item in presentment currency. Money object with amount (string) and currency (string).
Name
bonus_credit
Type
object
Description
Additional store credit offered in presentment currency. Money object with amount (string) and currency (string).
Name
return_reason
Type
object
Description
Reason for the return with id (integer) and name (string) fields.
Name
exchange_method
Type
object
Description
Exchange method details with:
- id (integer) - Method ID
- name (string) - Method name: same_product (exchange for same product in different size/color), in_app (customer selects replacement in return portal), or storefront (customer shops on store to select replacement)
- type (string) - Always exchange

Refund model

Refund items represent products that the customer is returning for a refund.

Properties

Name
id
Type
integer
Description
Unique identifier for the refund item.
Name
line_item_id
Type
string
Description
ID of the line item from the original order.
Name
product_id
Type
string
Description
Product ID from your e-commerce platform.
Name
variant_id
Type
string
Description
Variant ID from your e-commerce platform.
Name
product_title
Type
string
Description
Name of the product being returned.
Name
variant_title
Type
string
Description
Variant details (e.g., size, color).
Name
status
Type
string
Description
Status of the refund item.
Possible values:
- pending - Refund request is awaiting approval
- approved - Refund request has been approved
- rejected - Refund request has been rejected
- received - Returned item has been received at the warehouse
- resolved - Refund decision has been finalized
- pending_refund - Approved refund is awaiting payment processing
- completed - Refund has been processed and payment issued
Name
sku
Type
string
Description
Product SKU code.
Name
vendor
Type
string
Description
Product vendor or brand.
Name
extra_note
Type
string
Description
Customer's note or reason for the refund.
Name
reject_reason
Type
string
Description
Reason for rejection if status is rejected. null otherwise.
Name
keep_item
Type
boolean
Description
When true, no return shipment is required for this item. The refund is still approved and processed.
Name
shop_price
Type
object
Description
Original price of the item in shop currency. Money object with amount (string) and currency (string).
Name
return_item_price
Type
object
Description
Original price of the item in presentment currency. Money object with amount (string) and currency (string).
Name
tax_price
Type
object
Description
Tax amount for the item in presentment currency. Money object with amount (string) and currency (string).
Name
discount_amount
Type
object
Description
Discount applied to the item in presentment currency. Money object with amount (string) and currency (string).
Name
bonus_credit
Type
object
Description
Additional store credit offered in presentment currency. Money object with amount (string) and currency (string).
Name
return_reason
Type
object
Description
Reason for the return with id (integer) and name (string) fields.
Name
refund_method
Type
object
Description
Refund method details with:
- id (integer) - Method ID
- name (string) - Method name: original_payment_method, online_bank_transfer, gift_card, discount_code, apparel21_voucher, rise_ai_store_credit, or shopify_store_credit
- type (string) - Either refund or store_credit

Shipping Method model

The shipping method used for returning items.

Properties

Name
id
Type
integer
Description
Unique identifier for the shipping method.
Name
title
Type
string
Description
Display name of the shipping method.
Name
type
Type
string
Description
Type of shipping method.
Possible values:
- integrated_shipping_method - Integrated carrier (e.g., USPS, DHL)
- custom_shipping_method - Custom shipping method
- in_store_shipping_method - In-store returns
- mail_shipping_method - Mail-in returns
Name
courier
Type
string
Description
Courier name for integrated methods (e.g., "USPS", "DHL"). null for other types.

Shipment model

Shipment tracking and label information for the return.

Properties

Name
id
Type
integer
Description
Unique identifier for the shipment.
Name
status
Type
string
Description
Current shipment status.
Possible values:
- pending - Shipment pending creation
- order_created - Order created with carrier
- pending_label - Label generation in progress
- label_created - Label has been created
- dropped_off - Package dropped off
- driver_out_for_pickup - Driver is en route for pickup
- in_transit - Package is in transit
- delivered - Package delivered
- cancelled - Shipment cancelled
- delivery_failed - Delivery attempt failed
- untrackable - Tracking unavailable
Name
label_url
Type
string
Description
URL to download the shipping label PDF. null if not available.
Name
tracking_number
Type
string
Description
Tracking number for the shipment. null if not available.
Name
assigned_courier_name
Type
string
Description
Name of the courier handling the shipment.
Name
label_created_at
Type
datetime
Description
ISO8601 timestamp when the label was created. null if not created.
Name
fee
Type
object
Description
Shipping fee. Money object with amount (string) and currency (string).
Name
customer_borne
Type
boolean
Description
Indicates if the customer is responsible for paying the shipping fee. When true, the customer pays. When false, the retailer bears the cost (free shipping for the customer).
Name
paid
Type
boolean
Description
Indicates if the shipping fee has been paid or collected. true if the fee is zero, payment was successful, or the fee was deducted from the refund amount.
Name
payment_status
Type
string
Description
Detailed payment status for the shipment.
Possible values:
- pending - Customer payment is pending
- free - No payment needed (fee is zero or retailer-borne)
- paid - Payment has been collected
- deduct_from_refund - Fee was/will be deducted from refund
- process_after_resolve - Fee will be processed after resolution
- not_applicable - Payment not applicable for this shipping method
Name
from_address
Type
object
Description
Pickup/sender address. See Address model below.
Name
to_address
Type
object
Description
Delivery/warehouse address. See Address model below.

Understanding shipping payment

Use these three fields together to determine if a customer paid for return shipping:

Scenario	`customer_borne`	`paid`	`payment_status`	Meaning
Retailer pays	`false`	`true`	`free`	Retailer covered shipping cost
Customer paid	`true`	`true`	`paid`	Customer paid the shipping fee
Pending payment	`true`	`false`	`pending`	Customer still needs to pay
Free shipping	`true`	`true`	`free`	No shipping fee (fee amount is $0)
Deducted from refund	`true`	`true`	`deduct_from_refund`	Fee was deducted from customer's refund
Exchange-only return	`true`	`true`	`process_after_resolve`	Fee processed after exchange completes (no refund to deduct from)
Custom/mail shipping	—	—	`not_applicable`	Payment tracking not applicable for this method

Address model

Physical address information.

Properties

Name
address1
Type
string
Description
Primary address line.
Name
address2
Type
string
Description
Secondary address line (apartment, suite, etc.). May be empty.
Name
address3
Type
string
Description
Additional address line. null if not used.
Name
city
Type
string
Description
City name.
Name
zip
Type
string
Description
Postal/ZIP code.
Name
province
Type
string
Description
State or province name.
Name
country
Type
string
Description
Country name.
Name
district
Type
string
Description
District (used in some countries). null if not applicable.
Name
ward
Type
string
Description
Ward (used in some countries). null if not applicable.
Name
phone
Type
string
Description
Contact phone number.
Name
email
Type
string
Description
Contact email address.
Name
first_name
Type
string
Description
Contact first name.
Name
last_name
Type
string
Description
Contact last name.
Name
company
Type
string
Description
Company name. null if not provided.
Name
country_code
Type
string
Description
ISO 3166-1 alpha-2 country code (e.g., "US", "GB").
Name
province_code
Type
string
Description
Province or state code (e.g., "CA", "NY").

GET/api/public/v1/return_orders

List all return orders

This endpoint allows you to retrieve a paginated list of return orders for your shop. You can filter by status, date range, specific IDs, or order names.

Query parameters

Name
limit
Type
integer
Description
Number of items to return per page. Default: 50. Maximum: 100.
Name
cursor
Type
string
Description
Cursor for pagination. Use the next_cursor value from the previous response.
Name
ids
Type
string
Description
Comma-separated list of return order IDs to retrieve (e.g., "123,456,789").
Name
order_names
Type
string
Description
Comma-separated list of order names to filter by (e.g., "ORDER-001,ORDER-002").
Name
submitted_at_min
Type
datetime
Description
Filter return orders submitted on or after this date. ISO8601 format.
Name
submitted_at_max
Type
datetime
Description
Filter return orders submitted on or before this date. ISO8601 format.
Name
statuses
Type
string
Description
Comma-separated list of statuses to filter by (e.g., "reviewed,received,completed").

Request

GET

/api/public/v1/return_orders

curl -G https://360.postco.co/api/public/v1/return_orders \
  -H "Authorization: Bearer sk_your_api_key_here" \
  -d limit=50 \
  -d statuses=reviewed,received

Response

{
  "data": [
    {
      "id": 123,
      "cust_email": "[email protected]",
      "cust_phone": "+1234567890",
      "cust_first_name": "John",
      "cust_last_name": "Doe",
      "status": "reviewed",
      "currency": "USD",
      "order_id": "456",
      "order_name": "ORDER-001",
      "order_created_at": "2025-10-01T10:00:00Z",
      "submitted_at": "2025-10-05T14:30:00Z",
      "reviewed_at": "2025-10-06T09:00:00Z",
      "received_at": null,
      "resolved_at": null,
      "completed_at": null,
      "archived_at": null,
      "unarchived_at": null,
      "rejected_at": null,
      "updated_at": "2025-10-06T09:00:00Z",
      "exchanges": [],
      "refunds": [],
      "shipping_method": {},
      "shipment": {}
    }
  ],
  "has_more": true,
  "next_cursor": "eyJpZCI6MzAxfQ"
}

GET/api/public/v1/return_orders/:id

Retrieve a return order

This endpoint allows you to retrieve a specific return order by its ID. The response includes complete details about the return, including all line items, shipping information, and addresses.

Path parameters

Name
id
Type
integer
Description
The ID of the return order to retrieve.

Request

GET

/api/public/v1/return_orders/123

curl https://360.postco.co/api/public/v1/return_orders/123 \
  -H "Authorization: Bearer sk_your_api_key_here"

Response

{
  "id": 123,
  "cust_email": "[email protected]",
  "cust_phone": "+1234567890",
  "cust_first_name": "John",
  "cust_last_name": "Doe",
  "status": "reviewed",
  "currency": "USD",
  "order_id": "456",
  "order_name": "ORDER-001",
  "order_created_at": "2025-10-01T10:00:00Z",
  "submitted_at": "2025-10-05T14:30:00Z",
  "reviewed_at": "2025-10-06T09:00:00Z",
  "received_at": null,
  "resolved_at": null,
  "completed_at": null,
  "archived_at": null,
  "unarchived_at": null,
  "rejected_at": null,
  "updated_at": "2025-10-06T09:00:00Z",
  "exchanges": [
    {
      "id": 1,
      "line_item_id": "789",
      "product_id": "111",
      "variant_id": "222",
      "product_title": "Blue Shirt",
      "variant_title": "Large",
      "status": "approved",
      // ... more fields...
      "shop_price": {
        "amount": "29.99",
        "currency": "USD"
      },
      "return_item_price": {
        "amount": "29.99",
        "currency": "USD"
      },
      "tax_price": {
        "amount": "2.40",
        "currency": "USD"
      },
      "discount_amount": {
        "amount": "0.00",
        "currency": "USD"
      },
      "bonus_credit": {
        "amount": "5.00",
        "currency": "USD"
      },
      "return_reason": {
        "id": 10,
        "name": "Size too small"
      },
      "exchange_method": {
        "id": 1,
        "name": "in_app",
        "type": "Exchange"
      }
    }
  ],
  "refunds": [
    {
      "id": 2,
      "line_item_id": "790",
      "product_id": "112",
      "variant_id": "223",
      "product_title": "Red Pants",
      "variant_title": "Medium",
      "status": "approved",
      // ... more fields...
      "shop_price": {
        "amount": "49.99",
        "currency": "USD"
      },
      "return_item_price": {
        "amount": "49.99",
        "currency": "USD"
      },
      "tax_price": {
        "amount": "4.00",
        "currency": "USD"
      },
      "discount_amount": {
        "amount": "10.00",
        "currency": "USD"
      },
      "bonus_credit": {
        "amount": "0.00",
        "currency": "USD"
      },
      "return_reason": {
        "id": 11,
        "name": "Wrong item"
      },
      "refund_method": {
        "id": 2,
        "name": "original_payment_method",
        "type": "Refund"
      }
    }
  ],
  "shipping_method": {
    "id": 5,
    "title": "Standard Shipping",
    "type": "integrated_shipping_method",
    "courier": "USPS"
  },
  "shipment": {
    "id": 50,
    "status": "label_created",
    "label_url": "https://example.com/label.pdf",
    "tracking_number": "9400123456789012345678",
    "assigned_courier_name": "USPS",
    "label_created_at": "2025-10-05T14:35:00Z",
    "fee": {
      "amount": "0.00",
      "currency": "USD"
    },
    "customer_borne": false,
    "paid": true,
    "payment_status": "free",
    "from_address": {
      // ... more fields...
    },
    "to_address": {
      // ... more fields
    }
  }
}

PUT/api/public/v1/return_orders/:id/review

Review a return order

Review all pending items in a return order by approving, rejecting, or marking them as "keep_item."

Prerequisites:

Return order must be in pending status

Important notes:

This is an atomic operation—all pending items must be reviewed in a single request; partial reviews are not supported
Items can be approved, rejected, or marked as "keep_item" (where the customer keeps the product without returning it)
The keep_item action requires your shop to have this feature enabled in your subscription plan
reject_reason is required when rejecting items. Provide free-form text explaining the reason for rejection (e.g., "damaged item," "incorrect product returned")
If all items are rejected, the return order will be fully rejected
Limitation: Return orders using custom shipping methods that require label uploads are not supported. Use the PostCo retailer dashboard to review these returns

Path parameters

Name
id
Type
integer
Description
The ID of the return order to review.

Request body

Name
items
Type
array
Description
Array of all pending items to review. You must include all pending refunds and exchanges—partial reviews are not supported. Each item object requires:
- id (integer): The refund or exchange item ID from the return order
- type (string): Either "refund" or "exchange"
- action (string): One of approve, reject, or keep_item
- reject_reason (string, conditional): Required when action is reject. Free-form text explaining why the item was rejected

Request

PUT

/api/public/v1/return_orders/123/review

curl -X PUT https://360.postco.co/api/public/v1/return_orders/123/review \
  -H "Authorization: Bearer sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "id": 456,
        "type": "refund",
        "action": "approve"
      },
      {
        "id": 789,
        "type": "exchange",
        "action": "reject",
        "reject_reason": "Item not eligible for exchange"
      },
      {
        "id": 101,
        "type": "refund",
        "action": "keep_item"
      }
    ]
  }'

Success Response (200)

{
  "id": 123,
  "cust_email": "[email protected]",
  "cust_phone": "+1234567890",
  "cust_first_name": "John",
  "cust_last_name": "Doe",
  "status": "reviewed",
  "currency": "USD",
  "order_id": "456",
  "order_name": "ORDER-001",
  "order_created_at": "2025-10-01T10:00:00Z",
  "submitted_at": "2025-10-05T14:30:00Z",
  "reviewed_at": "2025-10-07T09:15:30Z",
  "received_at": null,
  "resolved_at": null,
  "completed_at": null,
  "archived_at": null,
  "unarchived_at": null,
  "rejected_at": null,
  "updated_at": "2025-10-07T09:15:30Z",
  "exchanges": [
    {
      "id": 789,
      "status": "rejected",
      "reject_reason": "Item not eligible for exchange",
      "rejected_at": "2025-10-07T09:15:30Z",
      // ... more fields
    }
  ],
  "refunds": [
    {
      "id": 456,
      "status": "approved",
      "approved_at": "2025-10-07T09:15:30Z",
      // ... more fields
    },
    {
      "id": 101,
      "status": "approved",
      "keep_item": true,
      "approved_at": "2025-10-07T09:15:30Z",
      // ... more fields
    }
  ],
  "shipping_method": { 
    // ... more fields
  },
  "shipment": { 
    // ... more fields
  }
}

Error Response (404)

{
  "error": {
    "type": "resource_error",
    "code": "return_order_not_found",
    "message": "Return order not found"
  }
}

Error Response (400) - Missing Items

{
  "error": {
    "type": "validation_error",
    "code": "missing_items",
    "message": "All pending items must be included in the request. Expected 2 refunds and 1 exchange.",
    "param": "items"
  }
}

Error Response (400) - Keep Item Not Allowed

{
  "error": {
    "type": "validation_error",
    "code": "keep_item_not_allowed",
    "message": "The keep_item action is not available. This feature must be enabled in your subscription plan.",
    "param": "items[].action"
  }
}

Error Response (400) - Missing Reject Reason

{
  "error": {
    "type": "validation_error",
    "code": "missing_reject_reason",
    "message": "reject_reason is required when action is 'reject' for item 789",
    "param": "items[].reject_reason"
  }
}

Error Response (422) - Invalid State

{
  "error": {
    "type": "state_error",
    "code": "invalid_state_transition",
    "message": "Return order must be in 'pending' status to be reviewed. Current status: 'reviewed'."
  }
}

Common error causes:

Missing items (400): Not all pending items were included—you must review all pending refunds and exchanges in a single request. Check the return order to see how many items are pending
keep_item not allowed (400): Your shop doesn't have the keep_item feature enabled. Contact support or approve/reject without using keep_item
Missing reject_reason (400): Items with action "reject" must include reject_reason. Provide text explaining why the item was rejected
Invalid action (400): Action must be one of: "approve", "reject", or "keep_item"
Invalid state (422): Return order must be in pending status to be reviewed. Check the return order's current status—returns that are already reviewed, received, or completed cannot be reviewed again

PUT/api/public/v1/return_orders/:id/receive

Receive a return order

Marks all approved return items (refunds and exchanges) as received at your warehouse. Typically called by warehouse management systems when items physically arrive.

Prerequisites:

Return order must be in reviewed status

Important notes:

Marks all approved items in the return order as received—individual item selection is not supported
Items approved with the "keep item" disposition (where customers keep the product) are automatically excluded
Updates the return order status to received and sets all individual line items to received
Sets the received_at timestamp on both the return order and all line items

Path parameters

Name
id
Type
integer
Description
The ID of the return order to mark as received.

Request body

No request body required for this endpoint.

Request

PUT

/api/public/v1/return_orders/123/receive

curl -X PUT https://360.postco.co/api/public/v1/return_orders/123/receive \
  -H "Authorization: Bearer sk_your_api_key_here"

Success Response (200)

{
  "id": 123,
  "cust_email": "[email protected]",
  "cust_phone": "+1234567890",
  "cust_first_name": "John",
  "cust_last_name": "Doe",
  "status": "received",
  "currency": "USD",
  "order_id": "456",
  "order_name": "ORDER-001",
  "order_created_at": "2025-10-01T10:00:00Z",
  "submitted_at": "2025-10-05T14:30:00Z",
  "reviewed_at": "2025-10-06T09:00:00Z",
  "received_at": "2025-10-07T11:23:45Z",
  "resolved_at": null,
  "completed_at": null,
  "archived_at": null,
  "unarchived_at": null,
  "rejected_at": null,
  "updated_at": "2025-10-07T11:23:45Z",
  "exchanges": [
    {
      "id": 1,
      "status": "received",
      "received_at": "2025-10-07T11:23:45Z",
      // ... more fields
    }
  ],
  "refunds": [
    {
      "id": 2,
      "status": "received",
      "received_at": "2025-10-07T11:23:45Z",
      // ... more fields
    }
  ],
  "shipping_method": { 
    // ... more fields
  },
  "shipment": { 
    // ... more fields
  }
}

Error Response (404)

{
  "error": {
    "type": "resource_error",
    "code": "return_order_not_found",
    "message": "Return order not found"
  }
}

Error Response (422)

{
  "error": {
    "type": "state_error",
    "code": "invalid_state_transition",
    "message": "Return order must be in 'reviewed' status to be received. Current status: 'completed'."
  }
}

Common 422 error causes:

Invalid state: Return order not in reviewed status (e.g., still pending, already completed, etc.). Only return orders in reviewed status can be received
Return order has no approved items to receive (all items rejected or marked as "keep item")
Return order was already marked as received (duplicate request)

PUT/api/public/v1/return_orders/:id/resolve

Resolve a return order

Coming soon: This endpoint is not yet available but will be released in a future update.

Once available, this endpoint will finalize the resolution process for return orders after items have been received at your warehouse.

Expected prerequisites:

Return order must be in received status

Check back for updates or contact PostCo support for estimated availability.

This endpoint will be documented here once available with full request/response examples and error handling details.