DOCS
Ctrl K

API reference

Returns

ReturnHub: returns received at the ParcelHub warehouse for this account.

Endpoints

Return address

GET /v1/returns/address

The warehouse address to give customers for returns.

Response in data

  • addresses • Required array of objects
    Each item · 3
    • formatted • Required array of strings
    • routing_code • Required string
    • warehouse • Required object
      Fields · 7
      • city • Required string

        City.

      • code • Required string
      • country • Required string

        Two-letter country code, e.g. CA, US.

      • id • Required uuid
      • name • Required string
      • postal_code • Required string

        Postal or ZIP code.

      • province • Required string
GET /v1/returns/address 
curl "https://api.parcelhub.ca/v1/returns/address" \
  -H "Authorization: Bearer $TOKEN"
Response 
{
  "ok": true,
  "data": {
    "addresses": [
      {
        "formatted": [
          "string"
        ],
        "routing_code": "string",
        "warehouse": {
          "city": "Toronto",
          "code": "string",
          "country": "CA",
          "id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
          "name": "Alex Martin",
          "postal_code": "M5V 2T6",
          "province": "ON"
        }
      }
    ]
  },
  "request_id": "01JBX7Q2…"
}

Received parcels

GET /v1/returns/intakes

Return parcels received at the warehouse.

Query parameters

  • limit integer

    Most results to return.

Response in data

  • items • Required array of objects
    Each item · 9
    • created_at • Required timestamp

      When it was created (ISO 8601, UTC).

    • id • Required uuid
    • status • Required string
    • warehouse_id • Required uuid
    • inbound_carrier string
    • inbound_tracking string
    • organization_id uuid
    • received_at timestamp
    • sender_name string
GET /v1/returns/intakes 
curl "https://api.parcelhub.ca/v1/returns/intakes" \
  -H "Authorization: Bearer $TOKEN"
Response 
{
  "ok": true,
  "data": {
    "items": [
      {
        "created_at": "2026-10-31T15:04:05Z",
        "id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
        "inbound_carrier": "string",
        "inbound_tracking": "string",
        "organization_id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
        "received_at": "2026-10-31T15:04:05Z",
        "sender_name": "string",
        "status": "string",
        "warehouse_id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f"
      }
    ]
  },
  "request_id": "01JBX7Q2…"
}

Returned items

GET /v1/returns/items

Items received at the warehouse.

Query parameters

  • status string
  • limit integer

    Most results to return.

Response in data

  • items • Required array of objects
    Each item · 16
    • condition • Required string
    • description • Required string
    • disposition_deadline • Required date
    • free_until • Required date
    • id • Required uuid
    • intake_id • Required uuid
    • organization_id • Required uuid
    • photos • Required array of objects
      Each item · 6
      • filename • Required string
      • id • Required uuid
      • object_key • Required string
      • taken_at • Required timestamp
      • content_type string
      • url string
    • quantity • Required integer

      How many.

    • status • Required string
    • stored_since • Required date
    • warehouse_id • Required uuid
    • lien_notice_sent_at timestamp
    • location_code string
    • sku string

      Your product code.

    • weight_grams integer
GET /v1/returns/items 
curl "https://api.parcelhub.ca/v1/returns/items" \
  -H "Authorization: Bearer $TOKEN"
Response 
{
  "ok": true,
  "data": {
    "items": [
      {
        "condition": "string",
        "description": "string",
        "disposition_deadline": "2026-11-03",
        "free_until": "2026-11-03",
        "id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
        "intake_id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
        "lien_notice_sent_at": "2026-10-31T15:04:05Z",
        "location_code": "string",
        "organization_id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
        "photos": [
          {}
        ],
        "quantity": 1,
        "sku": "string",
        "status": "string",
        "stored_since": "2026-11-03",
        "warehouse_id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
        "weight_grams": 1
      }
    ]
  },
  "request_id": "01JBX7Q2…"
}

Get a returned item

GET /v1/returns/items/{id}

One item: photos, condition, storage time and what can be done with it.

Path parameters

  • id • Required string

Response in data

  • condition • Required string
  • description • Required string
  • disposition_deadline • Required date
  • free_until • Required date
  • id • Required uuid
  • intake_id • Required uuid
  • organization_id • Required uuid
  • photos • Required array of objects
    Each item · 6
    • filename • Required string
    • id • Required uuid
    • object_key • Required string
    • taken_at • Required timestamp
    • content_type string
    • url string
  • quantity • Required integer

    How many.

  • status • Required string
  • stored_since • Required date
  • warehouse_id • Required uuid
  • lien_notice_sent_at timestamp
  • location_code string
  • sku string

    Your product code.

  • weight_grams integer
GET /v1/returns/items/{id} 
curl "https://api.parcelhub.ca/v1/returns/items/3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f" \
  -H "Authorization: Bearer $TOKEN"
Response 
{
  "ok": true,
  "data": {
    "condition": "string",
    "description": "string",
    "disposition_deadline": "2026-11-03",
    "free_until": "2026-11-03",
    "id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
    "intake_id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
    "lien_notice_sent_at": "2026-10-31T15:04:05Z",
    "location_code": "string",
    "organization_id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
    "photos": [
      {
        "content_type": "string",
        "filename": "string",
        "id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
        "object_key": "string",
        "taken_at": "2026-10-31T15:04:05Z",
        "url": "https://…"
      }
    ],
    "quantity": 1,
    "sku": "string",
    "status": "string",
    "stored_since": "2026-11-03",
    "warehouse_id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
    "weight_grams": 1
  },
  "request_id": "01JBX7Q2…"
}

Decide what happens to an item

POST /v1/returns/items/{id}/disposition

return_to_merchant ships it back to the account (postage may apply), continue_storage keeps it, and auction, donate or destroy give it up, which cannot be undone.

Path parameters

  • id • Required string

Request body

  • action • Required string

    return_to_merchant, continue_storage, auction, donate or destroy.

  • notes string

    Free-text notes.

Response in data

  • action • Required string
  • id • Required uuid
  • return_item_id • Required uuid
  • executed_at timestamp
  • responded_at timestamp
POST /v1/returns/items/{id}/disposition 
curl -X POST "https://api.parcelhub.ca/v1/returns/items/3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f/disposition" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "return_to_merchant",
  "notes": "string"
}'
Response 
{
  "ok": true,
  "data": {
    "action": "string",
    "executed_at": "2026-10-31T15:04:05Z",
    "id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
    "responded_at": "2026-10-31T15:04:05Z",
    "return_item_id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f"
  },
  "request_id": "01JBX7Q2…"
}

Statements

GET /v1/returns/statements

Storage and handling statements.

Query parameters

  • limit integer

    Most results to return.

Response in data

  • items • Required array of objects
    Each item · 8
    • currency • Required string

      Three-letter currency code, e.g. CAD.

    • due_date • Required date
    • id • Required uuid
    • period_end • Required date
    • period_start • Required date
    • status • Required string
    • total_cents • Required integer

      Total, in cents.

    • paid_at timestamp
GET /v1/returns/statements 
curl "https://api.parcelhub.ca/v1/returns/statements" \
  -H "Authorization: Bearer $TOKEN"
Response 
{
  "ok": true,
  "data": {
    "items": [
      {
        "currency": "CAD",
        "due_date": "2026-11-03",
        "id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
        "paid_at": "2026-10-31T15:04:05Z",
        "period_end": "2026-11-03",
        "period_start": "2026-11-03",
        "status": "string",
        "total_cents": 1299
      }
    ]
  },
  "request_id": "01JBX7Q2…"
}

Returns summary

GET /v1/returns/summary

Counts of returned items by status and the account's ReturnHub balances.

Response in data

  • stored • Required integer
  • unpaid_cents • Required integer
GET /v1/returns/summary 
curl "https://api.parcelhub.ca/v1/returns/summary" \
  -H "Authorization: Bearer $TOKEN"
Response 
{
  "ok": true,
  "data": {
    "stored": 1,
    "unpaid_cents": 1299
  },
  "request_id": "01JBX7Q2…"
}