API reference

Wallet

The prepaid balance labels are paid from: balance, history, top-ups, saved cards and refunds.

Endpoints

GET /wallet
GET /wallet/cards
DELETE /wallet/cards/{id}
POST /wallet/cards/{id}/default
GET /wallet/refunds
POST /wallet/refunds/{transaction_id}
POST /wallet/top-up
POST /wallet/top-up/{transaction_id}/confirm
GET /wallet/topup-bonuses
GET /wallet/transactions
GET /wallet/transactions/{id}
GET /wallet/unpaid

Wallet balance

GET /v1/wallet

The wallet balance and limits.

Response in `data`

available_cents • Required integer

Wallet balance you can spend, in cents.
currency • Required string

Three-letter currency code, e.g. CAD.
on_hold_cents • Required integer
pending_cents • Required integer

Top-ups still being confirmed, in cents.

GET /v1/wallet

1
2

curl "https://api.parcelhub.ca/v1/wallet" \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "ok": true,
  "data": {
    "available_cents": 1299,
    "currency": "CAD",
    "on_hold_cents": 1299,
    "pending_cents": 1299
  },
  "request_id": "01JBX7Q2…"
}

Cards saved on the account: brand, last 4 digits, expiry and which is the default. Full card numbers are never returned. New cards are added by the customer on Stripe's secure form in the dashboard (my.parcelhub.ca/wallet/add-card), never through the API.

Response in `data`

items • Required array of objects
Each item · 9
- brand • Required string
- created_at • Required timestamp
  
  When it was created (ISO 8601, UTC).
- exp_month • Required integer
- exp_year • Required integer
- id • Required uuid
- is_default • Required boolean
- last4 • Required string
- stripe_payment_method_id • Required string
- holder_name string

GET /v1/wallet/cards

1
2

curl "https://api.parcelhub.ca/v1/wallet/cards" \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "ok": true,
  "data": {
    "items": [
      {
        "brand": "string",
        "created_at": "2026-10-31T15:04:05Z",
        "exp_month": 1,
        "exp_year": 1,
        "holder_name": "string",
        "id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
        "is_default": false,
        "last4": "string",
        "stripe_payment_method_id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f"
      }
    ]
  },
  "request_id": "01JBX7Q2…"
}

Remove a card

DELETE /v1/wallet/cards/{id}

Deletes a saved card.

Path parameters

id • Required string

Response in `data`

deleted • Required boolean

DELETE /v1/wallet/cards/{id}

1
2

curl -X DELETE "https://api.parcelhub.ca/v1/wallet/cards/3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f" \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "ok": true,
  "data": {
    "deleted": true
  },
  "request_id": "01JBX7Q2…"
}

Make a card the default

POST /v1/wallet/cards/{id}/default

Makes a saved card the default for top-ups.

Path parameters

id • Required string

Response in `data`

brand • Required string
created_at • Required timestamp

When it was created (ISO 8601, UTC).
exp_month • Required integer
exp_year • Required integer
id • Required uuid
is_default • Required boolean
last4 • Required string
stripe_payment_method_id • Required string
holder_name string

POST /v1/wallet/cards/{id}/default

1
2

curl -X POST "https://api.parcelhub.ca/v1/wallet/cards/3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f/default" \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "ok": true,
  "data": {
    "brand": "string",
    "created_at": "2026-10-31T15:04:05Z",
    "exp_month": 1,
    "exp_year": 1,
    "holder_name": "string",
    "id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
    "is_default": false,
    "last4": "string",
    "stripe_payment_method_id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f"
  },
  "request_id": "01JBX7Q2…"
}

Refund requests

GET /v1/wallet/refunds

Requests to refund unused wallet funds, with their status.

Response in `data`

items • Required array of objects
Each item · 6
- amount_cents • Required integer
  
  Amount in cents.
- created_at • Required timestamp
  
  When it was created (ISO 8601, UTC).
- id • Required uuid
- reason • Required string
- status • Required string
- transaction_id • Required uuid

GET /v1/wallet/refunds

1
2

curl "https://api.parcelhub.ca/v1/wallet/refunds" \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "ok": true,
  "data": {
    "items": [
      {
        "amount_cents": 1299,
        "created_at": "2026-10-31T15:04:05Z",
        "id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
        "reason": "string",
        "status": "string",
        "transaction_id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f"
      }
    ]
  },
  "request_id": "01JBX7Q2…"
}

Request a refund

POST /v1/wallet/refunds/{transaction_id}

Asks for unused funds from a past top-up to be refunded to the card that paid for it (never anywhere else). ParcelHub staff review each request. transaction_id is the top-up's wallet transaction.

Path parameters

transaction_id • Required string

Request body

reason • Required string

Why the refund is requested.

Response in `data`

amount_cents • Required integer

Amount in cents.
created_at • Required timestamp

When it was created (ISO 8601, UTC).
id • Required uuid
reason • Required string
status • Required string
transaction_id • Required uuid

POST /v1/wallet/refunds/{transaction_id}

curl -X POST "https://api.parcelhub.ca/v1/wallet/refunds/3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "string"
}'

Response

{
  "ok": true,
  "data": {
    "amount_cents": 1299,
    "created_at": "2026-10-31T15:04:05Z",
    "id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
    "reason": "string",
    "status": "string",
    "transaction_id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f"
  },
  "request_id": "01JBX7Q2…"
}

Top up the wallet

POST /v1/wallet/top-up

Charges the account's wallet.

Charges a saved card straight away. payment_method_id is the card's stripe_payment_method_id (pm_…) from GET /v1/wallet/cards. Then call POST /v1/wallet/top-up/{transaction_id}/confirm with the returned transaction_id to credit the wallet. Check GET /v1/wallet/topup-bonuses for the minimum and maximum.

Confirm with the account owner before calling it.

Request body

amount_cents • Required integer

Amount to add, in cents.
draft_id uuid

Paying the shortfall for this draft's label at checkout.
expected_charge_cents integer

With draft_id: the total shown to the customer, card fee included. The request is refused if the charge would differ.
payment_method_id string

The saved card's stripe_payment_method_id (pm_…) from GET /v1/wallet/cards.

Response in `data`

amount_cents • Required integer

Amount in cents.
currency • Required string

Three-letter currency code, e.g. CAD.
stripe_payment_intent_id • Required string
transaction_id • Required uuid

POST /v1/wallet/top-up

curl -X POST "https://api.parcelhub.ca/v1/wallet/top-up" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "amount_cents": 1299,
  "expected_charge_cents": 1299
}'

Response

{
  "ok": true,
  "data": {
    "amount_cents": 1299,
    "currency": "CAD",
    "stripe_payment_intent_id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
    "transaction_id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f"
  },
  "request_id": "01JBX7Q2…"
}

Confirm a top-up

POST /v1/wallet/top-up/{transaction_id}/confirm

Checks a top-up's payment with the card processor and credits the wallet (and any top-up bonus) once it succeeded. Calling it again is safe. If the bank asks for extra verification (3-D Secure) the error message contains requires_action: only the cardholder can finish that, at my.parcelhub.ca/wallet/top-up.

Path parameters

transaction_id • Required string

Response in `data`

transaction • Required object
Fields · 11
- amount_cents • Required integer
  
  Amount in cents.
- created_at • Required timestamp
  
  When it was created (ISO 8601, UTC).
- currency • Required string
  
  Three-letter currency code, e.g. CAD.
- id • Required uuid
- status • Required string
- transaction_number • Required string
- txn_type • Required string
- completed_at timestamp
- description string
- reference string
- stripe_payment_intent_id string
bonus_cents integer
bonus_kind string

POST /v1/wallet/top-up/{transaction_id}/confirm

1
2

curl -X POST "https://api.parcelhub.ca/v1/wallet/top-up/3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f/confirm" \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "ok": true,
  "data": {
    "bonus_cents": 1299,
    "bonus_kind": "string",
    "transaction": {
      "amount_cents": 1299,
      "completed_at": "2026-10-31T15:04:05Z",
      "created_at": "2026-10-31T15:04:05Z",
      "currency": "CAD",
      "description": "string",
      "id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
      "reference": "Order #1042",
      "status": "string",
      "stripe_payment_intent_id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
      "transaction_number": "string",
      "txn_type": "string"
    }
  },
  "request_id": "01JBX7Q2…"
}

Top-up options

GET /v1/wallet/topup-bonuses

The minimum top-up, the maximum balance and any bonus this account can get on its next top-up.

Response in `data`

bonuses • Required array of objects
Each item · 3
- bonus_cents • Required integer
- kind • Required string
- min_topup_cents • Required integer
enabled • Required boolean
first_topup_eligible • Required boolean
label_card_fee_bps • Required integer
max_balance_cents • Required integer
min_topup_cents • Required integer
offer object
Fields · 4
- campaign_id • Required uuid
- ends_at • Required timestamp
- joined • Required boolean
- tiers • Required array of objects
  Each item · 2
  - bonus_cents • Required integer
  - min_topup_cents • Required integer

GET /v1/wallet/topup-bonuses

1
2

curl "https://api.parcelhub.ca/v1/wallet/topup-bonuses" \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "ok": true,
  "data": {
    "bonuses": [
      {
        "bonus_cents": 1299,
        "kind": "string",
        "min_topup_cents": 1299
      }
    ],
    "enabled": true,
    "first_topup_eligible": true,
    "label_card_fee_bps": 1,
    "max_balance_cents": 1299,
    "min_topup_cents": 1299,
    "offer": {
      "campaign_id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
      "ends_at": "2026-10-31T15:04:05Z",
      "joined": true,
      "tiers": [
        {
          "bonus_cents": 1299,
          "min_topup_cents": 1299
        }
      ]
    }
  },
  "request_id": "01JBX7Q2…"
}

Wallet history

GET /v1/wallet/transactions

Top-ups, label and pickup charges, refunds and bonuses, newest first. Filter with type.

Query parameters

type string

Only this kind: top_up, payment (labels, pickups, invoices), refund or adjustment (credits and corrections).
limit integer

Most results to return.

Response in `data`

items • Required array of objects
Each item · 11
- amount_cents • Required integer
  
  Amount in cents.
- created_at • Required timestamp
  
  When it was created (ISO 8601, UTC).
- currency • Required string
  
  Three-letter currency code, e.g. CAD.
- id • Required uuid
- status • Required string
- transaction_number • Required string
- txn_type • Required string
- completed_at timestamp
- description string
- reference string
- stripe_payment_intent_id string

GET /v1/wallet/transactions

1
2

curl "https://api.parcelhub.ca/v1/wallet/transactions" \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "ok": true,
  "data": {
    "items": [
      {
        "amount_cents": 1299,
        "completed_at": "2026-10-31T15:04:05Z",
        "created_at": "2026-10-31T15:04:05Z",
        "currency": "CAD",
        "description": "string",
        "id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
        "reference": "Order #1042",
        "status": "string",
        "stripe_payment_intent_id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
        "transaction_number": "string",
        "txn_type": "string"
      }
    ]
  },
  "request_id": "01JBX7Q2…"
}

Get a transaction

GET /v1/wallet/transactions/{id}

One wallet transaction in detail.

Path parameters

id • Required string

Response in `data`

amount_cents • Required integer

Amount in cents.
created_at • Required timestamp

When it was created (ISO 8601, UTC).
currency • Required string

Three-letter currency code, e.g. CAD.
id • Required uuid
status • Required string
transaction_number • Required string
txn_type • Required string
completed_at timestamp
description string
reference string
stripe_payment_intent_id string

GET /v1/wallet/transactions/{id}

1
2

curl "https://api.parcelhub.ca/v1/wallet/transactions/3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f" \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "ok": true,
  "data": {
    "amount_cents": 1299,
    "completed_at": "2026-10-31T15:04:05Z",
    "created_at": "2026-10-31T15:04:05Z",
    "currency": "CAD",
    "description": "string",
    "id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
    "reference": "Order #1042",
    "status": "string",
    "stripe_payment_intent_id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
    "transaction_number": "string",
    "txn_type": "string"
  },
  "request_id": "01JBX7Q2…"
}

Amount owed

GET /v1/wallet/unpaid

The total of unpaid invoices; 0 when nothing is owed.

Response in `data`

amount_cents • Required integer

Amount in cents.
currency • Required string

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

GET /v1/wallet/unpaid

1
2

curl "https://api.parcelhub.ca/v1/wallet/unpaid" \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "ok": true,
  "data": {
    "amount_cents": 1299,
    "currency": "CAD"
  },
  "request_id": "01JBX7Q2…"
}

Wallet

Response in data

Response in data

Path parameters

Response in data

Path parameters

Response in data

Response in data

Path parameters

Request body

Response in data

Request body

Response in data

Path parameters

Response in data

Response in data

Query parameters

Response in data

Path parameters

Response in data

Response in data

Response in `data`

Response in `data`

Response in `data`

Response in `data`

Response in `data`

Response in `data`

Response in `data`

Response in `data`

Response in `data`

Response in `data`

Response in `data`

Response in `data`