Package Types

Retrieve available package type definitions. Package types define the packaging or unit profiles (such as pallets, cartons, satchels, or boxes) used for logistic units and consignment items.

Endpoints Overview

Method Endpoint Description
GET /v1/package-types Get a page of package types

Get Package Types Page

Retrieve a paginated list of available package types for the authenticated organisation or partner context.

Endpoint: GET /v1/package-types

Query Parameters

Parameter Type Required Description
pageIndex integer No Zero-based page index (default: 0, minimum: 0).
pageSize integer No Number of records per page (default: 50, range: 1–500).
searchText string No Filter by package type name or code prefix.
clientCodes array of strings (string[]) No Repeated parameter (clientCodes=CODE1&clientCodes=CODE2). Filter package types assigned to client partners matching the specified codes. Evaluated for organisation callers.
clientPartnerIds array of UUIDs (uuid[]) No Repeated parameter (clientPartnerIds=00000000-0000-0000-0000-000000000001). Filter package types assigned to client partners matching the specified GUIDs. Empty values are ignored, including when mixed with valid GUIDs. Evaluated for organisation callers.

Selector & Filtering Behavior

  • Selector Union (ANY / OR): When clientCodes and/or clientPartnerIds are supplied by an organisation caller, the filter matches package types assigned to ANY of the specified client partners (union).
  • Unique Total: The total count and items returned reflect distinct package types; duplicates are never returned when a package type is assigned to multiple matched client partners.
  • Empty Selectors: When both selectors are empty or omitted, organisation owners and users with Organisation Settings Read or Package Type Management permission receive all active package types in their organisation. Other authorised organisation users receive only active package types assigned to client partners in their organisation, or an empty page if none are assigned.
  • No Matching Assignments: If the assignment filter matches no active package types, the response has total: 0 and an empty packageTypes array. There is no fallback to all organisation package types. This includes unmatched selectors, clients without active assignments, and partner-scoped callers without active assignments. Search and pagination still apply.
  • Organisation and Client Scope: Assignment filters consider only client partners and package types in the authenticated organisation.
  • Partner Caller Context: For callers authenticated with partner-scoped credentials, the assignment filter uses the caller's partner. Selector parameters (clientCodes and clientPartnerIds) are ignored for assignment filtering. If the caller's partner has no active assignments, the response is an empty page.
  • Malformed GUID Validation: Non-empty clientPartnerIds parameter values must be valid GUID strings. Empty values (clientPartnerIds=) are ignored. A malformed GUID (e.g., clientPartnerIds=invalid) immediately fails model validation and returns HTTP 400 Bad Request, even for partner callers where selectors are otherwise ignored.
  • Ordering: Results are ordered by the index of searchText within the name (prefix matches first), followed by package type name.

Request Examples

curl -X GET "https://api.consignlyhq.com/v1/package-types?clientCodes=BREKKIE&clientPartnerIds=550e8400-e29b-41d4-a716-446655444000&pageIndex=0&pageSize=50" \
  -H "Authorization: Bearer YOUR_ORGANISATION_ACCESS_TOKEN"

Response Example

{
  "index": 0,
  "total": 2,
  "packageTypes": [
    {
      "id": "550e8400-e29b-41d4-a716-446655444000",
      "name": "Blue Pallet",
      "code": "CHEP"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655444001",
      "name": "Brown Pallet",
      "code": "LOSCAM"
    }
  ]
}

Response Fields

Field Type Description
index integer Current zero-based page index.
total integer Total number of unique active package types matching the criteria.
packageTypes array Array of active package type header records.
packageTypes[].id uuid Unique identifier of the package type.
packageTypes[].name string Name of the package type.
packageTypes[].code string Code of the package type.

Error Cases

Status Cause
400 Invalid query parameter: pageIndex < 0, pageSize outside 1–500, or malformed GUID in clientPartnerIds.
401 Missing or invalid bearer token.
403 Missing or invalid organisation and/or user permission

  • Partners - View client partners and partner details (use clientCodes or clientPartnerIds on /v1/package-types to filter package types assigned to client partners)
  • Consignments - Reference package types on consignment logistic units