Discounts

Get a discount campaign

GET /v1/discounts/campaigns/{id}

A discount campaign (from a my.parcelhub.ca/discount/… link) and whether this account can claim it.

Path parameters

• id • Required string

Response in data

• campaign • Required object
  Fields · 14

  • appliesTo • Required array of strings
  • claimCount • Required integer
  • id • Required uuid
  • percentageBps • Required integer
  • state • Required string

    Province or state code, e.g. ON, BC, NY.

  • theme • Required string
  • expiresAt timestamp
  • maxClaims integer
  • maxDiscountCents integer
  • minPurchaseCents integer
  • remaining integer
  • startsAt timestamp
  • subtitle string
  • title string
• claimed • Required boolean
• code string

1
2

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

{
  "ok": true,
  "data": {
    "campaign": {
      "appliesTo": [
        "string"
      ],
      "claimCount": 1,
      "expiresAt": "2026-10-31T15:04:05Z",
      "id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
      "maxClaims": 1,
      "maxDiscountCents": 1,
      "minPurchaseCents": 1,
      "percentageBps": 1,
      "remaining": 1,
      "startsAt": "2026-10-31T15:04:05Z",
      "state": "ON",
      "subtitle": "string",
      "theme": "string",
      "title": "string"
    },
    "claimed": true,
    "code": "string"
  },
  "request_id": "01JBX7Q2…"
}

Claim a discount campaign

POST /v1/discounts/campaigns/{id}/claim

Adds the campaign to the account so it applies at checkout.

Path parameters

• id • Required string

Response in data

• message • Required string
• outcome • Required string
• code string

1
2

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

1
2
3
4
5
6
7
8
9

{
  "ok": true,
  "data": {
    "code": "string",
    "message": "string",
    "outcome": "string"
  },
  "request_id": "01JBX7Q2…"
}

Check a discount code

POST /v1/discounts/validate

Whether a code is valid and what it takes off an amount. Nothing is used up.

Request body

• code • Required string

  The discount code.

• subtotal_cents • Required integer

  The amount the discount would apply to, in cents.

• target_kind string

  What it is for: shipment.

Response in data

• applied_cents • Required integer
• ok • Required boolean
• code string
• message string
• rejection string

1
2
3
4
5
6
7
8

curl -X POST "https://api.parcelhub.ca/v1/discounts/validate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "string",
  "subtotal_cents": 1299,
  "target_kind": "shipment"
}'

1
2
3
4
5
6
7
8
9
10
11

{
  "ok": true,
  "data": {
    "applied_cents": 1299,
    "code": "string",
    "message": "string",
    "ok": true,
    "rejection": "string"
  },
  "request_id": "01JBX7Q2…"
}

Get a promotion

GET /v1/promos/{id}

A promotion (from a my.parcelhub.ca/promo/… link) and whether this account can claim it.

Path parameters

• id • Required string

Response in data

• campaign • Required object
  Fields · 16

  • claimCount • Required integer
  • creditCents • Required integer
  • endsAt • Required timestamp
  • id • Required uuid
  • kind • Required string
  • startsAt • Required timestamp
  • state • Required string

    Province or state code, e.g. ON, BC, NY.

  • carrier string

    Carrier code, as returned with each rate.

  • carrierLabel string
  • maxClaims integer
  • minTopupCents integer
  • remaining integer
  • requiredShipments integer
  • subtitle string
  • tiers array of objects
    Each item · 2

    • bonusCents • Required integer
    • minTopupCents • Required integer
  • title string
• eligibility • Required object
  Fields · 4

  • eligible • Required boolean
  • reason • Required string
  • progressCurrent integer
  • progressRequired integer
• claimedAt timestamp
• claimedCents integer

1
2

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

{
  "ok": true,
  "data": {
    "campaign": {
      "carrier": "ups",
      "carrierLabel": "string",
      "claimCount": 1,
      "creditCents": 1,
      "endsAt": "2026-10-31T15:04:05Z",
      "id": "3f2b8c1e-5d6a-4b7c-9e0f-1a2b3c4d5e6f",
      "kind": "string",
      "maxClaims": 1,
      "minTopupCents": 1,
      "remaining": 1,
      "requiredShipments": 1,
      "startsAt": "2026-10-31T15:04:05Z",
      "state": "ON",
      "subtitle": "string",
      "tiers": [
        {
          "bonusCents": 1,
          "minTopupCents": 1
        }
      ],
      "title": "string"
    },
    "claimedAt": "2026-10-31T15:04:05Z",
    "claimedCents": 1,
    "eligibility": {
      "eligible": true,
      "progressCurrent": 1,
      "progressRequired": 1,
      "reason": "string"
    }
  },
  "request_id": "01JBX7Q2…"
}

Claim a promotion

POST /v1/promos/{id}/claim

Claims the promotion onto the account.

Path parameters

• id • Required string

Response in data

• armed • Required boolean
• creditedCents • Required integer
• walletAvailableCents • Required integer
• bonusCents integer
• minTopupCents integer

1
2

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

1
2
3
4
5
6
7
8
9
10
11

{
  "ok": true,
  "data": {
    "armed": true,
    "bonusCents": 1,
    "creditedCents": 1,
    "minTopupCents": 1,
    "walletAvailableCents": 1
  },
  "request_id": "01JBX7Q2…"
}

Referrals

GET /v1/referrals

The account's referral link, the people it referred and the credit earned.

Response in data

• enabled • Required boolean
• program • Required object
  Fields · 6

  • stage1Cents • Required integer
  • stage1ThresholdCents • Required integer
  • stage2Cents • Required integer
  • stage2ThresholdCents • Required integer
  • headline string
  • subtitle string
• referrals • Required any
• rewards • Required any
• stats • Required any
• code string
• shareUrl string

1
2

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

{
  "ok": true,
  "data": {
    "code": "string",
    "enabled": true,
    "program": {
      "headline": "string",
      "stage1Cents": 1,
      "stage1ThresholdCents": 1,
      "stage2Cents": 1,
      "stage2ThresholdCents": 1,
      "subtitle": "string"
    },
    "referrals": null,
    "rewards": null,
    "shareUrl": "string",
    "stats": null
  },
  "request_id": "01JBX7Q2…"
}