> ## Documentation Index > Fetch the complete documentation index at: https://docs.arcuserp.com/llms.txt > Use this file to discover all available pages before exploring further. # List packages > Returns a paginated list of shipment packages for the entity. Supports filtering by `order_id`, `status` (draft / packed / shipped / delivered), `carrier`, `date_range`, and `location_id` (Layer 4 warehouse isolation, inherited via the package's order). Results are cursor-paginated using `next_cursor`. Requires `fulfillment:read` scope. ## OpenAPI ````yaml /openapi.yaml get /packages openapi: 3.1.0 info: title: Arcus ERP Public API version: 1.0.0 description: > Arcus ERP public REST API. Designed for external integrations and data migration. **Authentication.** Bearer token (API key) via the `Authorization` header. Format: `Authorization: Bearer ark_live_ent__` (or `ark_test_*` for sandbox). API keys are issued per-entity in **Settings > Developers > API Keys**. **Entity scoping.** The entity is encoded in the API key prefix; routes are flat (e.g. `/v1/accounts`, `/v1/orders`, `/v1/products`). A small set of platform endpoints (migration, reconciliation, events, webhook endpoints, API keys) use the `/v1/entities/{entity_id}/...` form -- those are noted in their tags. **Key capabilities.** - Related-resource hydration via `?expand[]=` (see `x-arcus-expand` on each resource). - Cursor-based pagination (`starting_after` / `ending_before` / `limit`). - Idempotency via the `Idempotency-Key` header. - Webhook events for asynchronous notification. - Conditional requests / ETag for cache validation. servers: - url: https://api.arcuserp.com/v1 description: Arcus ERP API (accepts both live `ark_live_*` and test `ark_test_*` keys) - url: https://dev-api.arcuserp.com/v1 description: >- Dev sandbox API (test-only data, accepts `ark_test_*` keys against dev RDS) security: [] paths: /packages: get: tags: - Fulfillment summary: List packages description: > Returns a paginated list of shipment packages for the entity. Supports filtering by `order_id`, `status` (draft / packed / shipped / delivered), `carrier`, `date_range`, and `location_id` (Layer 4 warehouse isolation, inherited via the package's order). Results are cursor-paginated using `next_cursor`. Requires `fulfillment:read` scope. operationId: listPackages parameters: - name: order_id in: query schema: type: string format: uuid - name: status in: query schema: type: string enum: - open - fulfilled - voided - name: location_id in: query schema: type: string format: uuid description: > Filter to a single warehouse location (Layer 4 isolation). Resolved from the `X-Location-Id` request header first, then this query param. Packages inherit location from their order (`packages.order_id -> orders.location_id`); packages whose order has NULL `location_id` remain visible at every location (NULL-universal). - name: exclude_empty in: query description: | When `true`, draft packages with zero items are excluded from the response. Useful for operator queues that should never show orphan packages while still allowing audit workflows to fetch them with the default `false`. Default: `false` (backwards-compat; every existing caller continues to receive empty drafts). Added 2026-05-16 per NEW-GAP-WH-ORPHAN-EMPTY-DRAFT-PACKAGES-LITTER-FULFILLMENT-STATION. schema: type: boolean default: false - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/StartingAfter' - name: expand[] in: query schema: type: array items: type: string enum: - data.items - data.items.product - data.label - data.tracking_events - data.order style: form explode: true responses: '200': description: Paginated package list content: application/json: schema: type: object properties: object: type: string enum: - list data: type: array items: $ref: '#/components/schemas/Package' has_more: type: boolean '401': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' security: - ApiKeyAuth: [] components: parameters: Limit: name: limit in: query required: false description: | Maximum number of records to return per page. Default 25, max 500. Use together with starting_after for cursor pagination. For larger bulk extraction workflows prefer the migration endpoints. schema: type: integer minimum: 1 maximum: 500 default: 25 StartingAfter: name: starting_after in: query required: false description: | Cursor for pagination. Pass the id of the last record from the previous page to fetch the next page. Mutually exclusive with ending_before. schema: type: string maxLength: 200 schemas: Package: type: object description: | A shipment / box created during fulfillment. One package contains many package items (line item splits) and at most one shipment label. properties: id: type: string format: uuid object: type: string enum: - package entity_id: type: string format: uuid readOnly: true order_id: type: string format: uuid package_number: type: string readOnly: true description: Sequential per entity. status: type: string enum: - packing - packed - labeled - shipped - delivered - returned - void readOnly: true weight_lb: type: number nullable: true length_in: type: number nullable: true width_in: type: number nullable: true height_in: type: number nullable: true carrier: type: string nullable: true description: e.g. ups, usps, fedex, dhl. service_level: type: string nullable: true description: e.g. ground, priority, 2day. tracking_number: type: string nullable: true tracking_url: type: string nullable: true ship_cost: type: number nullable: true billed_ship_cost: type: number nullable: true description: Cost billed to customer (vs purchased cost). location_id: type: string format: uuid nullable: true insurance_amount_override: type: number nullable: true description: > Manual override of the auto-computed Shippo-insurance declared value. When set, overrides the value derived from products flagged apply_freight_insurance. insurance: type: object nullable: true readOnly: true description: > Auto-insurance summary. `null` when no package item opts in and there is no override / entity threshold. `bought: true` after a label has been purchased (amount = the value actually insured at Shippo); `bought: false` projects what the next label purchase will insure. properties: active: type: boolean bought: type: boolean amount: type: number description: Insured declared value (USD). currency: type: string fee_estimate: type: number description: ~1.5% of declared value; the exact fee is in the rate. provider: type: string nullable: true description: UPS | USPS | FEDEX | DHL once the carrier is chosen. covered_items: type: array items: type: string covered_item_count: type: integer source: type: string enum: - product_toggle - entity_threshold - manual_override shipped_at: type: string format: date-time nullable: true readOnly: true delivered_at: type: string format: date-time nullable: true readOnly: true metadata: type: object nullable: true created_at: type: string format: date-time readOnly: true updated_at: type: string format: date-time readOnly: true ErrorEnvelope: type: object description: | Canonical error response envelope. All API errors use this shape. required: - error - code properties: error: type: string description: Machine-readable error key example: not_found code: type: string description: Machine-readable error code (often same as error) example: not_found type: type: string enum: - validation_error - permission_error - not_found - conflict - rate_limit - internal - expand_error - not_implemented example: not_found hint: type: string description: Human-readable one-sentence explanation (English) example: >- The requested order does not exist or does not belong to this entity. param: type: string description: The parameter that caused the error, if applicable example: expand[0] required: type: string description: The scope required (only on insufficient_scope errors) example: accounts:read request_id: type: string description: >- Unique request ID for support tracing (maps to CloudWatch log stream) example: req_abc123 responses: Error: description: Error response (400/401/403/404/409/422/429/500) content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' securitySchemes: ApiKeyAuth: type: http scheme: bearer description: | API key issued per entity via Settings > Developers > API Keys. Each key carries scopes (e.g. orders:read, products:write). Bearer token format: Authorization: Bearer ark_live_ent__ Test keys use ark_test_ent__. Both are issued per entity via Settings > Developers > API Keys. ````