Skip to content
Docs
Sign in
Docs menu

API reference

Plans

Create the retail plans you bill your customers on, priced on top of your wholesale plans.

HoundSat bills you on wholesale plans; you bill your customers on retail plans you create, each based on one of your wholesale plans. Plans are priced per device, per MB, in tiers, or as a pooled allowance shared by a customer's devices. Prices are US cents. Staff never see pricing fields.

Endpoints

The plan object

A wholesale or retail plan and its pricing.

Attributes

  • iduuidRequired

    Unique identifier.

  • allowance_mbinteger· nullable

    pooled: MB per active device that join the customer's pool (at most 1,000,000,000).

  • base_plan_iduuid· nullable
  • currencystringRequired

    Always USD (no tax).

  • data_allowance_mbinteger· nullable

    Informational data allowance in MB shown with the plan (never billed; at most 1,000,000,000).

  • inserted_attimestampRequired
  • kindenumRequired

    wholesale (platform -> reseller) | retail (reseller -> customer).

    One ofwholesaleretail

  • monthly_fee_centsinteger· nullable

    Per-device monthly fee in US cents, for each device active on at least one day of the month (no proration). per_device (required), pooled (optional). At most 99,999,999. Owner/Admin only.

  • namestringRequired
  • organization_iduuidRequired
  • overage_per_mbstring· nullable

    pooled: US cents per MB above the pool, up to 4 decimals, at most 1,000,000. Owner/Admin only.

  • price_per_mbstring· nullable

    per_mb: US cents per MB (1,000,000 bytes), up to 4 decimals, at most 1,000,000. Owner/Admin only.

  • pricing_modelenumRequired

    per_device | per_mb | tiered | pooled.

    One ofper_deviceper_mbtieredpooled

  • reseller_iduuid· nullable
  • statusenumRequired

    active | archived (archived plans can't be newly assigned).

    One ofactivearchived

  • tiersarray of object· nullable

    tiered: graduated per device, ascending; up_to_mb is the tier's upper bound in MB (null on the last tier only, which is unbounded) and price_per_mb the price in US cents per MB inside the tier. Owner/Admin only.

    • price_per_mbstringRequired
    • up_to_mbinteger· nullable
  • updated_attimestampRequired
The plan object
{
  "type": "plan",
  "id": "5f0c2b7e-8d41-4a96-b3e2-91c7d0a4e6f8",
  "attributes": {
    "allowance_mb": 1,
    "base_plan_id": "1e8a6c4d-0f2b-4a37-9d51-c6e3b7a0f489",
    "currency": "usd",
    "data_allowance_mb": 1,
    "inserted_at": "2026-10-12T14:03:21Z",
    "kind": "wholesale",
    "monthly_fee_cents": 1250,
    "name": "Northwind Freight",
    "organization_id": "a7d35c90-2e14-4f6b-8c03-5b9e1d4a2f67",
    "overage_per_mb": "…",
    "price_per_mb": "…",
    "pricing_model": "per_device",
    "reseller_id": "a7d35c90-2e14-4f6b-8c03-5b9e1d4a2f67",
    "status": "active",
    "tiers": [
      {
        "price_per_mb": "…",
        "up_to_mb": 1
      }
    ],
    "updated_at": "2026-10-12T14:03:21Z"
  }
}

Endpoints

List plans

get/api/json/plans

The wholesale plans offered to you and your retail plans, by name. Customers see the retail plans billed to them.

Who
Resellers and Customers
Roles
Owner, Admin, Staff

Query parameters

  • filter[<field>]object

    Narrows the list: filter[status]=active, or with an operator: filter[inserted_at][greater_than_or_equal]=2026-10-01T00:00:00Z. Operators: in, is_nil, greater_than, greater_than_or_equal, less_than, less_than_or_equal.

    One ofallowance_mbbase_plan_idcurrencydata_allowance_mbidinserted_atkindnameorganization_idpricing_modelreseller_idstatusupdated_at

  • sortstring

    A field to sort by; prefix it with - for descending, e.g. sort=-inserted_at. Separate several with commas.

  • page[limit]integer

    Page size: 50 by default, at most 200.

  • page[after]string

    The cursor from links.next of the previous page. page[offset] works too.

  • page[count]boolean

    true adds the total number of matches in meta.page.total.

Request
curl https://api.houndsat.com/api/json/plans \
  -H "Authorization: Bearer $HOUNDSAT_TOKEN"
Response200 OK
{
  "data": [
    {
      "type": "plan",
      "id": "5f0c2b7e-8d41-4a96-b3e2-91c7d0a4e6f8",
      "attributes": {
        "allowance_mb": 1,
        "base_plan_id": "1e8a6c4d-0f2b-4a37-9d51-c6e3b7a0f489",
        "currency": "usd",
        "data_allowance_mb": 1,
        "inserted_at": "2026-10-12T14:03:21Z",
        "kind": "wholesale",
        "monthly_fee_cents": 1250,
        "name": "Northwind Freight",
        "organization_id": "a7d35c90-2e14-4f6b-8c03-5b9e1d4a2f67",
        "overage_per_mb": "…",
        "price_per_mb": "…",
        "pricing_model": "per_device",
        "reseller_id": "a7d35c90-2e14-4f6b-8c03-5b9e1d4a2f67",
        "status": "active",
        "tiers": [
          {
            "price_per_mb": "…",
            "up_to_mb": 1
          }
        ],
        "updated_at": "2026-10-12T14:03:21Z"
      }
    }
  ],
  "links": {
    "next": "/api/json/plans?page[after]=g2wAAAABbQAAACQ1ZjBj…"
  }
}

Get a plan

get/api/json/plans/{id}

One plan you can read.

Who
Resellers and Customers
Roles
Owner, Admin, Staff

Path parameters

  • iduuidRequired

    The record's id.

Request
curl https://api.houndsat.com/api/json/plans/5f0c2b7e-8d41-4a96-b3e2-91c7d0a4e6f8 \
  -H "Authorization: Bearer $HOUNDSAT_TOKEN"
Response200 OK
{
  "data": {
    "type": "plan",
    "id": "5f0c2b7e-8d41-4a96-b3e2-91c7d0a4e6f8",
    "attributes": {
      "allowance_mb": 1,
      "base_plan_id": "1e8a6c4d-0f2b-4a37-9d51-c6e3b7a0f489",
      "currency": "usd",
      "data_allowance_mb": 1,
      "inserted_at": "2026-10-12T14:03:21Z",
      "kind": "wholesale",
      "monthly_fee_cents": 1250,
      "name": "Northwind Freight",
      "organization_id": "a7d35c90-2e14-4f6b-8c03-5b9e1d4a2f67",
      "overage_per_mb": "…",
      "price_per_mb": "…",
      "pricing_model": "per_device",
      "reseller_id": "a7d35c90-2e14-4f6b-8c03-5b9e1d4a2f67",
      "status": "active",
      "tiers": [
        {
          "price_per_mb": "…",
          "up_to_mb": 1
        }
      ],
      "updated_at": "2026-10-12T14:03:21Z"
    }
  }
}

Create a retail plan

post/api/json/plans/retail

Creates a retail plan for your customers, based on one of your active wholesale plans (base_plan_id). Assign it with Set a customer's default plan or per device.

Who
Resellers
Roles
Owner, Admin

Attributes

Sent as data.attributes.

  • namestringRequired
  • pricing_modelenumRequired

    per_device | per_mb | tiered | pooled.

    One ofper_deviceper_mbtieredpooled

  • allowance_mbinteger· nullable

    pooled: MB per active device that join the customer's pool (at most 1,000,000,000).

  • base_plan_iduuid· nullable
  • data_allowance_mbinteger· nullable

    Informational data allowance in MB shown with the plan (never billed; at most 1,000,000,000).

  • monthly_fee_centsinteger· nullable

    Per-device monthly fee in US cents, for each device active on at least one day of the month (no proration). per_device (required), pooled (optional). At most 99,999,999. Owner/Admin only.

  • overage_per_mbstring· nullable

    pooled: US cents per MB above the pool, up to 4 decimals, at most 1,000,000. Owner/Admin only.

  • price_per_mbstring· nullable

    per_mb: US cents per MB (1,000,000 bytes), up to 4 decimals, at most 1,000,000. Owner/Admin only.

  • tiersarray of object· nullable

    tiered: graduated per device, ascending; up_to_mb is the tier's upper bound in MB (null on the last tier only, which is unbounded) and price_per_mb the price in US cents per MB inside the tier. Owner/Admin only.

    • price_per_mbstringRequired

      US cents per MB inside the tier (at most 1,000,000).

    • up_to_mbinteger· nullable

      Upper bound in MB (at most 1,000,000,000); null on the last tier (unbounded).

Request
curl -X POST https://api.houndsat.com/api/json/plans/retail \
  -H "Authorization: Bearer $HOUNDSAT_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{"data":{"type":"plan","attributes":{"name":"Northwind Freight","pricing_model":"per_device","allowance_mb":1,"base_plan_id":"1e8a6c4d-0f2b-4a37-9d51-c6e3b7a0f489","data_allowance_mb":1,"monthly_fee_cents":1250,"overage_per_mb":"…","price_per_mb":"…","tiers":[{"price_per_mb":"…","up_to_mb":1}]}}}'
Response201 Created
{
  "data": {
    "type": "plan",
    "id": "5f0c2b7e-8d41-4a96-b3e2-91c7d0a4e6f8",
    "attributes": {
      "allowance_mb": 1,
      "base_plan_id": "1e8a6c4d-0f2b-4a37-9d51-c6e3b7a0f489",
      "currency": "usd",
      "data_allowance_mb": 1,
      "inserted_at": "2026-10-12T14:03:21Z",
      "kind": "wholesale",
      "monthly_fee_cents": 1250,
      "name": "Northwind Freight",
      "organization_id": "a7d35c90-2e14-4f6b-8c03-5b9e1d4a2f67",
      "overage_per_mb": "…",
      "price_per_mb": "…",
      "pricing_model": "per_device",
      "reseller_id": "a7d35c90-2e14-4f6b-8c03-5b9e1d4a2f67",
      "status": "active",
      "tiers": [
        {
          "price_per_mb": "…",
          "up_to_mb": 1
        }
      ],
      "updated_at": "2026-10-12T14:03:21Z"
    }
  }
}

Update a plan

patch/api/json/plans/{id}

Renames a retail plan or changes its pricing. Changes apply to every month billed afterwards.

Who
Resellers
Roles
Owner, Admin

Path parameters

  • iduuidRequired

    The record's id.

Attributes

Sent as data.attributes.

  • allowance_mbinteger· nullable

    pooled: MB per active device that join the customer's pool (at most 1,000,000,000).

  • data_allowance_mbinteger· nullable

    Informational data allowance in MB shown with the plan (never billed; at most 1,000,000,000).

  • monthly_fee_centsinteger· nullable

    Per-device monthly fee in US cents, for each device active on at least one day of the month (no proration). per_device (required), pooled (optional). At most 99,999,999. Owner/Admin only.

  • namestring· nullable
  • overage_per_mbstring· nullable

    pooled: US cents per MB above the pool, up to 4 decimals, at most 1,000,000. Owner/Admin only.

  • price_per_mbstring· nullable

    per_mb: US cents per MB (1,000,000 bytes), up to 4 decimals, at most 1,000,000. Owner/Admin only.

  • pricing_modelenum· nullable

    per_device | per_mb | tiered | pooled.

    One ofper_deviceper_mbtieredpooled

  • tiersarray of object· nullable

    tiered: graduated per device, ascending; up_to_mb is the tier's upper bound in MB (null on the last tier only, which is unbounded) and price_per_mb the price in US cents per MB inside the tier. Owner/Admin only.

    • price_per_mbstringRequired

      US cents per MB inside the tier (at most 1,000,000).

    • up_to_mbinteger· nullable

      Upper bound in MB (at most 1,000,000,000); null on the last tier (unbounded).

Request
curl -X PATCH https://api.houndsat.com/api/json/plans/5f0c2b7e-8d41-4a96-b3e2-91c7d0a4e6f8 \
  -H "Authorization: Bearer $HOUNDSAT_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{"data":{"type":"plan","id":"5f0c2b7e-8d41-4a96-b3e2-91c7d0a4e6f8","attributes":{"allowance_mb":1,"data_allowance_mb":1,"monthly_fee_cents":1250,"name":"Northwind Freight","overage_per_mb":"…","price_per_mb":"…","pricing_model":"per_device","tiers":[{"price_per_mb":"…","up_to_mb":1}]}}}'
Response200 OK
{
  "data": {
    "type": "plan",
    "id": "5f0c2b7e-8d41-4a96-b3e2-91c7d0a4e6f8",
    "attributes": {
      "allowance_mb": 1,
      "base_plan_id": "1e8a6c4d-0f2b-4a37-9d51-c6e3b7a0f489",
      "currency": "usd",
      "data_allowance_mb": 1,
      "inserted_at": "2026-10-12T14:03:21Z",
      "kind": "wholesale",
      "monthly_fee_cents": 1250,
      "name": "Northwind Freight",
      "organization_id": "a7d35c90-2e14-4f6b-8c03-5b9e1d4a2f67",
      "overage_per_mb": "…",
      "price_per_mb": "…",
      "pricing_model": "per_device",
      "reseller_id": "a7d35c90-2e14-4f6b-8c03-5b9e1d4a2f67",
      "status": "active",
      "tiers": [
        {
          "price_per_mb": "…",
          "up_to_mb": 1
        }
      ],
      "updated_at": "2026-10-12T14:03:21Z"
    }
  }
}

Archive a plan

patch/api/json/plans/{id}/archive

Keeps a plan's current assignments but stops it from being assigned again.

Who
Resellers
Roles
Owner, Admin

Path parameters

  • iduuidRequired

    The record's id.

Request
curl -X PATCH https://api.houndsat.com/api/json/plans/5f0c2b7e-8d41-4a96-b3e2-91c7d0a4e6f8/archive \
  -H "Authorization: Bearer $HOUNDSAT_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{"data":{"type":"plan","id":"5f0c2b7e-8d41-4a96-b3e2-91c7d0a4e6f8","attributes":{}}}'
Response200 OK
{
  "data": {
    "type": "plan",
    "id": "5f0c2b7e-8d41-4a96-b3e2-91c7d0a4e6f8",
    "attributes": {
      "allowance_mb": 1,
      "base_plan_id": "1e8a6c4d-0f2b-4a37-9d51-c6e3b7a0f489",
      "currency": "usd",
      "data_allowance_mb": 1,
      "inserted_at": "2026-10-12T14:03:21Z",
      "kind": "wholesale",
      "monthly_fee_cents": 1250,
      "name": "Northwind Freight",
      "organization_id": "a7d35c90-2e14-4f6b-8c03-5b9e1d4a2f67",
      "overage_per_mb": "…",
      "price_per_mb": "…",
      "pricing_model": "per_device",
      "reseller_id": "a7d35c90-2e14-4f6b-8c03-5b9e1d4a2f67",
      "status": "active",
      "tiers": [
        {
          "price_per_mb": "…",
          "up_to_mb": 1
        }
      ],
      "updated_at": "2026-10-12T14:03:21Z"
    }
  }
}

Unarchive a plan

patch/api/json/plans/{id}/unarchive

Makes an archived plan assignable again.

Who
Resellers
Roles
Owner, Admin

Path parameters

  • iduuidRequired

    The record's id.

Request
curl -X PATCH https://api.houndsat.com/api/json/plans/5f0c2b7e-8d41-4a96-b3e2-91c7d0a4e6f8/unarchive \
  -H "Authorization: Bearer $HOUNDSAT_TOKEN" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{"data":{"type":"plan","id":"5f0c2b7e-8d41-4a96-b3e2-91c7d0a4e6f8","attributes":{}}}'
Response200 OK
{
  "data": {
    "type": "plan",
    "id": "5f0c2b7e-8d41-4a96-b3e2-91c7d0a4e6f8",
    "attributes": {
      "allowance_mb": 1,
      "base_plan_id": "1e8a6c4d-0f2b-4a37-9d51-c6e3b7a0f489",
      "currency": "usd",
      "data_allowance_mb": 1,
      "inserted_at": "2026-10-12T14:03:21Z",
      "kind": "wholesale",
      "monthly_fee_cents": 1250,
      "name": "Northwind Freight",
      "organization_id": "a7d35c90-2e14-4f6b-8c03-5b9e1d4a2f67",
      "overage_per_mb": "…",
      "price_per_mb": "…",
      "pricing_model": "per_device",
      "reseller_id": "a7d35c90-2e14-4f6b-8c03-5b9e1d4a2f67",
      "status": "active",
      "tiers": [
        {
          "price_per_mb": "…",
          "up_to_mb": 1
        }
      ],
      "updated_at": "2026-10-12T14:03:21Z"
    }
  }
}

Delete a plan

delete/api/json/plans/{id}

Deletes a plan nothing uses. Archive a plan that is in use instead.

Who
Resellers
Roles
Owner, Admin

Path parameters

  • iduuidRequired

    The record's id.

Request
curl -X DELETE https://api.houndsat.com/api/json/plans/5f0c2b7e-8d41-4a96-b3e2-91c7d0a4e6f8 \
  -H "Authorization: Bearer $HOUNDSAT_TOKEN"
Response200 OK
(empty body)