---
title: "Get Package Usage"
method: GET
path: "/inventory/packages/usage/{package_id}"
tags: ["provider", "inventory"]
---

# Get Package Usage

`GET /inventory/packages/usage/{package_id}`

Get the usage of a package with optional filtering and sorting.

## Path parameters

- `package_id` string, required

## Query parameters

- `patient_name` string, nullable — Filter by patient name
- `last_activity_date` string, nullable — Filter by last activity date
- `purchased_date` string, nullable — Filter by purchased date
- `status` string[], nullable — Filter by package status
- `sort_by` string, nullable — Sort field
- `sort_direction` string, nullable — Sort direction (asc or desc)

## Headers

- `TENANT` string, required
- `API-KEY` string, required

## Response `200`

Successful Response

- SoldPackageDetail[]
  - `id` string — Unique identifier for the sold package
  - `packageId` string, required — Package ID that was sold
  - `patientId` string, required — Patient ID who purchased the package
  - `chargeItemId` string, required — Charge item ID associated with the package purchase
  - `status` 'USED' | 'ACTIVE' | 'CANCELLED', required
  - `package` PackageDetail, required
    - `id` string — Unique identifier for the package
    - `name` string, required — Name of the package
    - `description` string, nullable — Optional description of the package
    - `isArchived` boolean — Whether the package is archived
    - `price` integer, required — Price of the package in cents
    - `internalNotes` string, nullable — Optional internal notes for the package
    - `items` PackageItemOutput[], nullable — Items included in the package
      - `id` string — Unique identifier for the package item
      - `packageId` string, required — Package ID this item belongs to
      - `itemId` string, required — Item ID for this package item
      - `quantity` integer, nullable — Quantity of the item in the package
      - `price` integer, required — Price of the item in the package in cents
      - `item` ItemTiny
        - `id` string — Unique identifier for the item
        - `name` string, required — Name of the item
        - `brandName` string, nullable — Optional brand name of the item
        - `description` string, nullable — Optional description of the item
        - `price` integer, required — Price of the item in cents
        - `category` string, nullable — Category name (references category.name)
        - `unit` 'AMPOULES' | 'APPLICATORS' | 'BOTTLES' | 'BOXES' | 'CAPSULES' | 'CUPS' | 'DOSES' | 'G_PER_ML' | 'GRAMS' | 'IU' | 'IU_PER_ML' | 'OUNCES' | 'FLUID_OUNCES' | 'KG' | 'KITS' | 'LITERS' | 'MCG' | 'MG' | 'MG_PER_ML' | 'ML' | 'MMOL' | 'MICROGRAM_PER_ML' | 'PACKS' | 'PAIRS' | 'PATCHES' | 'PERCENTAGE' | 'PIECES' | 'POUCHES' | 'ROLLS' | 'SACHETS' | 'SHEETS' | 'SPRAYS' | 'STRIPS' | 'SYRINGES' | 'TABLETS' | 'TABLETS_PER_DAY' | 'TESTS' | 'TUBES' | 'UNITS' | 'VIALS' | 'TREATMENTS' | 'SESSIONS' | 'PULSES' | 'JOULES' | 'CENTIMETERS' | 'THREAD_COUNT' | 'INJECTIONS' | 'WRINKLE_UNITS' | 'POUNDS' | 'FEET' | 'INCHES'
        - `isPhysical` boolean — Whether the item is physical
        - `isArchived` boolean — Whether the item is archived
        - `internalNotes` string, nullable — Optional internal notes for the item
        - `taxable` boolean — Whether the item is subject to taxes
        - `sortOrder` integer, nullable — Optional sort order for the item
        - `allowCustomPricing` boolean — Whether custom pricing is allowed for this item
        - `type` 'ITEM' | 'PRODUCT' | 'MEDICATION' | 'SERVICE' | 'PACKAGE' | 'MEMBERSHIP'
    - `category` string, nullable — Category name (references category.name)
    - `numberOfActivePatients` integer — Number of active patients on this package
    - `numberOfPatients` integer — Total number of patients who have purchased this package
    - `createdDate` string, date-time, nullable — Date the package was created
  - `createdDate` string, date-time, required — Date the package was created
  - `updatedDate` string, date-time, nullable — Date the package was updated
  - `items` ChargeItemDetailWithCharge[] — Items used in the package
    - `id` string, nullable — Unique identifier for the charge item
    - `itemId` string, nullable — Optional unique identifier for the item
    - `chargeId` string, required — Identifier of the charge this item is associated with
    - `name` string, nullable — Name of the item (None for items with associated inventory item)
    - `description` string, nullable — Description of the item
    - `quantity` integer, required — Quantity of the item being charged
    - `discountAmount` integer, nullable — Discount amount for the item
    - `discountPercentage` number, nullable — Discount percentage for the item
    - `discountReason` string, nullable — Reason for discount
    - `price` integer, required — Price of the item in cents
    - `soldPackageId` string, nullable — Unique identifier for the sold package usage
    - `bankedQuantity` integer, nullable — Quantity to bank for later use
    - `bankedItemId` string, nullable — ID of banked item being used (for tracking usage)
    - `issuedDiscountId` string, nullable — Unique identifier for the specific issued discount instance used
    - `soldByProviderId` string, nullable — Unique identifier for the provider who sold the item
    - `taxAmount` integer, nullable — Tax amount for the item in cents
    - `pricingId` string, nullable — Unique identifier for the pricing for the item
    - `shipmentIds` string[], nullable — Optional list of shipment IDs to reduce the stock quantity of
    - `item` ItemTiny
      - `id` string — Unique identifier for the item
      - `name` string, required — Name of the item
      - `brandName` string, nullable — Optional brand name of the item
      - `description` string, nullable — Optional description of the item
      - `price` integer, required — Price of the item in cents
      - `category` string, nullable — Category name (references category.name)
      - `unit` 'AMPOULES' | 'APPLICATORS' | 'BOTTLES' | 'BOXES' | 'CAPSULES' | 'CUPS' | 'DOSES' | 'G_PER_ML' | 'GRAMS' | 'IU' | 'IU_PER_ML' | 'OUNCES' | 'FLUID_OUNCES' | 'KG' | 'KITS' | 'LITERS' | 'MCG' | 'MG' | 'MG_PER_ML' | 'ML' | 'MMOL' | 'MICROGRAM_PER_ML' | 'PACKS' | 'PAIRS' | 'PATCHES' | 'PERCENTAGE' | 'PIECES' | 'POUCHES' | 'ROLLS' | 'SACHETS' | 'SHEETS' | 'SPRAYS' | 'STRIPS' | 'SYRINGES' | 'TABLETS' | 'TABLETS_PER_DAY' | 'TESTS' | 'TUBES' | 'UNITS' | 'VIALS' | 'TREATMENTS' | 'SESSIONS' | 'PULSES' | 'JOULES' | 'CENTIMETERS' | 'THREAD_COUNT' | 'INJECTIONS' | 'WRINKLE_UNITS' | 'POUNDS' | 'FEET' | 'INCHES'
      - `isPhysical` boolean — Whether the item is physical
      - `isArchived` boolean — Whether the item is archived
      - `internalNotes` string, nullable — Optional internal notes for the item
      - `taxable` boolean — Whether the item is subject to taxes
      - `sortOrder` integer, nullable — Optional sort order for the item
      - `allowCustomPricing` boolean — Whether custom pricing is allowed for this item
      - `type` 'ITEM' | 'PRODUCT' | 'MEDICATION' | 'SERVICE' | 'PACKAGE' | 'MEMBERSHIP'
    - `locationId` string, nullable — Location ID where the sale occurred
    - `locationName` string, nullable — Location name where the sale occurred
    - `saleDate` string, date-time, nullable — Date when the sale occurred
    - `charge` ChargeSummaryForItem, required
      - `id` string, required — Unique identifier for the charge
      - `patientId` string, required — Identifier of the patient being charged
      - `total` integer, required — Total amount of the charge.
      - `totalOutstanding` integer, required — Total outstanding amount that is yet to be paid.
      - `description` string, nullable — Description of the charge.
      - `status` 'OUTSTANDING' | 'PAID' | 'EXTERNAL_SETTLEMENT' | 'VOID' | 'WRITE_OFF' | 'REFUNDED' | 'CHARGEBACK' | 'PAYMENT_PLAN' | 'COLLECTIONS', required
      - `createdDate` string, date-time, nullable — The date when the charge was created.
  - `patient` PatientSummary, required
    - `id` string, required — The unique identifier for the user.
    - `firstName` string, nullable — The user's first name.
    - `lastName` string, nullable — The user's last name.
    - `phoneNumber` string, nullable — The user's phone number.
    - `email` string, nullable — The user's email address.
    - `type` 'PROVIDER' | 'PATIENT' | 'ASSISTANT', required
    - `locationId` string, nullable — The location of the user.
    - `externalId` string, nullable — The user's external identifier if available.
    - `address` string, nullable — The user's primary address.
    - `addressLineTwo` string, nullable — Additional address information.
    - `city` string, nullable — The city of the user's address.
    - `state` string, nullable — The state of the user's address.
    - `zipCode` string, nullable — The postal code of the user's address.
    - `country` string, nullable — The country of the user's address.
    - `createdDate` string, date-time, required — The date and time when the user was created.
    - `addressValid` boolean, nullable — Whether the user's address is valid.
    - `meta` object, nullable — Any additional metadata about the user relevant to your system.
    - `isArchived` boolean, nullable — Whether the user is archived.
    - `primaryLocationId` string, nullable — The primary location of the user.
    - `gender` string, nullable — The gender of the patient.
    - `dateOfBirth` string, date, nullable — The date of birth of the patient.
    - `patientMedications` string[], nullable — List of patient's self-reported medications.
    - `onSchedulingBlacklist` boolean, nullable — Whether the patient is on the scheduling blacklist.
    - `surchargeDisabled` boolean, nullable — Whether surcharges are disabled for this patient.
    - `tags` PatientTagSummary[], nullable — List of patient tags
      - `id` string, required — Unique identifier for the patient tag
      - `name` string, required — Name of the patient tag
      - `emoji` string, nullable — Emoji associated with the tag
      - `color` string, nullable — Color code for the tag (hex format)
      - `isActive` boolean, required — Whether the tag is active
      - `createdDate` string, date-time, required — Date and time when the tag was created
      - `updatedDate` string, date-time, nullable — Date and time when the tag was last updated
    - `creditBalance` integer, nullable — Patient's credit balance in cents.
    - `preferredProviderId` string, nullable — The preferred provider ID for this patient.
  - `chargeItem` ChargeItem, required
    - `id` string, nullable — Unique identifier for the charge item
    - `itemId` string, nullable — Optional unique identifier for the item
    - `chargeId` string, required — Identifier of the charge this item is associated with
    - `name` string, nullable — Name of the item (None for items with associated inventory item)
    - `description` string, nullable — Description of the item
    - `quantity` integer, required — Quantity of the item being charged
    - `discountAmount` integer, nullable — Discount amount for the item
    - `discountPercentage` number, nullable — Discount percentage for the item
    - `discountReason` string, nullable — Reason for discount
    - `price` integer, required — Price of the item in cents
    - `soldPackageId` string, nullable — Unique identifier for the sold package usage
    - `bankedQuantity` integer, nullable — Quantity to bank for later use
    - `bankedItemId` string, nullable — ID of banked item being used (for tracking usage)
    - `issuedDiscountId` string, nullable — Unique identifier for the specific issued discount instance used
    - `soldByProviderId` string, nullable — Unique identifier for the provider who sold the item
    - `taxAmount` integer, nullable — Tax amount for the item in cents
    - `pricingId` string, nullable — Unique identifier for the pricing for the item
    - `shipmentIds` string[], nullable — Optional list of shipment IDs to reduce the stock quantity of

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/decodahealth/apis/decoda-api.md) · [All operations](https://skmtc.dev/decodahealth/apis/decoda-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/decodahealth/decoda-api/revisions/4939a65a89d2/schema)