Public API GatewayAbstractions Reference
Guides
Help CenterAsk a Dev

Updating Shipment Packages with APIs

Suggest Edits

Before You Start

Ensure you read through the Public API Getting Started guide to learn how to get authorized and locate your API Keys.

✅Read more

Getting Started with the Public API

GET GetPackages

GetPackages allows you to get packages based on the warehouse, invoice date, and status.

Request URL

https://dsapi.directscale.com/v1/orders/packages[?warehouseId][&invoiceStartDate][&invoiceEndDate][&packageStatuses]

Parameters:

  • warehouseId (int) - The ID of the warehouse from which to retrieve the packages.

  • [optional] invoiceStartDate (date/time string) - Filters packages whose order's invoice date is the value specified or later. If left out/blank, the default value is today at midnight.

  • [optional] invoiceEndDate (date/time string) - Filters packages whose status is one the value(s) specified. Filters packages whose order's invoice date is the value specified or earlier. If left out/blank, the default value is the current date/time.

  • [optional] packageStatuses (PackageStatus[]) - Multiple values must be comma-separated. The default value is "NotSpecified", which will return packages of all PackageStatus types.

    Status options include:

    • "Submitted" - Initial status for orders when they are paid and placed.
    • "NotSpecified"
    • "Printed"
    • "Shipped"

Response Body

[
  {
    "ID": 687,
    "CustomerID": "2",
    "Address1": "350 S. 400 W.",
    "Address2": "Ste 225",
    "Carrier": "FedEx Freight",
    "City": "Lindon",
    "CountryCode": "US",
    "Height": 0,
    "Length": 0,
    "Notes": "1 of 1",
    "OrderNumber": 694,
    "ShipByDate": "2020-08-04T15:04:50Z",
    "PrintedDate": null,
    "ShippedDate": null,
    "ShipMethodID": 1,
    "State": "UT",
    "WarehouseID": 1,
    "Weight": 1,
    "Width": 0,
    "Zip": "84042",
    "ShipTo": "Sam Space",
    "Status": "Submitted",
    "TrackingNumber": "abc-123-def-456",
    "Code": "",
    "LineItems": [
      {
        "OrderLineItemId": 113,
        "Amount": 10,
        "Bonus": 0,
        "CategoryId": 1,
        "Cost": 0,
        "CurrencyCode": "USD",
        "Height": 0,
        "Length": 0,
        "OrderNumber": 694,
        "PackageNumber": 687,
        "Cv": 10,
        "Qv": 10,
        "Qty": 1,
        "Sku": "TestSKU-383Q",
        "ItemId": 58,
        "ProductName": "ProductName-2HZN9U",
        "Weight": 1,
        "Width": 0,
        "FlagCancer": false,
        "FlagBirthDefects": false,
        "HasKitGroups": false,
        "Image": "/no_image.jpg"
      }
    ]
  }
]

PUT UpdatePackageStatus

With UpdatePackageStatus you can update a specific order package's status and any associated info (carrier, printed date, shipped date, tracking number).

Request URL

https://dsapi.directscale.com/v1/orders/packages/{packageId}/package-status

Parameter:

  • packageId (int) - The ID of the package to update.

Request Body

{
  "carrier": "FedEx",
  "packageStatus": "Shipped",
  "printedDate": "",
  "shippedDate": "2020-08-11T22:04:34.802Z",
  "trackingNumber": "asdf-1234-qwer-5678"
}

Supported packageStatus:

  • "Submitted" - Initial status for orders when they are paid and placed.
  • "NotSpecified" - The default value is "NotSpecified", which will return packages of all PackageStatus types.
  • "Printed" - If used, the printedDate parameter will be used to set the Printed Date on the package. If the printedDate parameter does not contain a value, the current date/time will be used instead.
  • "Shipped" - If you don't provide a status, it will default to "NotSpecified". Only the carrier info (Carrier and Tracking Number) will be updated. When you update the status to "Shipped," it does hit the MarkPackagesShipped Hook. Any Hook logic programmed will still execute.

Any attempt to update a package or packages to a different status will result in an error.

PUT UpdatePackageStatusBatch

UpdatePackageStatusBatch allows you to update the status of multiple packages at once.

Request URL

https://dsapi.directscale.com/v1/orders/packages/batch/package-status

Request Body

[
  {
    "packageId": 1234,
    "carrier": "FedEx",
    "packageStatus": "Shipped",
    "printedDate": "",
    "shippedDate": "2020-08-11T22:04:34.802Z",
    "trackingNumber": "asdf-1234-qwer-5678"
  },
  {
    "packageId": 1235,
    "carrier": "",
    "packageStatus": "Printed",
    "printedDate": "2020-08-11T22:04:35.107Z",
    "shippedDate": "",
    "trackingNumber": ""
  }
]

Supported packageStatus:

  • "Submitted" - Initial status for orders when they are paid and placed.
  • "NotSpecified" - The default value is "NotSpecified", which will return packages of all PackageStatus types.
  • "Printed" - If used, the printedDate parameter will be used to set the Printed Date on the package. If the printedDate parameter does not contain a value, the current date/time will be used instead.
  • "Shipped" - If you don't provide a status, it will default to "NotSpecified". Only the carrier info (Carrier and Tracking Number) will be updated.

Any attempt to update a package or packages to a different status will result in an error.

POST SplitPackage

SplitPackage allows you to create additional packages from an already-existing package. You can get the needed package details from the GetPackages API.

Request URL

https://dsapi.directscale.com/v1/orders/packages/split/{packageId}

Parameter:

  • packageId (int) - The ID of the package to update.

📘Note

The API splits out ItemIDs but not quantities. For example, if you order five of the same item, but the company only has two, the same ItemID cannot be split into multiple packages.

⚠Important

The existing package will not be removed or replaced due to this call. Instead, some of the existing package's line items will be split off and assigned to the new packages specified.

Request body

[
  {
    "height": 12.5,
    "itemIds": [
      1,
      2
    ],
    "length": 16.75,
    "notes": "Deliver to door around back.",
    "shipByDate": "2020-11-11",
    "shipMethodId": 1,
    "shippingAddress": {
      "Street1": "1234 Test Dr.",
      "Street2": "Suite 225",
      "City": "Placerville",
      "PostalCode": "95667",
      "Region": "CA",
      "CountryCode": "US"
    },
    "shipToName": "Sam Space",
    "warehouseId": 1,
    "weight": 1,
    "width": 7.25
  },
  {
    "height": 10.75,
    "itemIds": [
      93
    ],
    "length": 10.75,
    "notes": "Deliver to door around back.",
    "shipByDate": "2020-11-11",
    "shipMethodId": 5,
    "shippingAddress": {
      "Street1": "1234 Test Dr.",
      "Street2": "Suite 225",
      "Street3": "",
      "City": "Placerville",
      "PostalCode": "95667",
      "Region": "CA",
      "CountryCode": "US"
    },
    "shipToName": "Sam Space",
    "warehouseId": 2,
    "weight": 1,
    "width": 7.25
  }
]

Example Scenario

A given package (Package# 222) currently has four line items assigned to it with the following item IDs:

  • 3
  • 4
  • 22
  • 19

Additionally, let's suppose that the 3PL working with this API wants to re-assign items 4 and 22 to a single new package. The process would look like this:

  1. Specify the existingPackageId (222).

  2. The newPackages array would contain one entry. This entry, among other specifications, would include two item ids in the itemIds parameter: 4 and 22.

  3. The 3PL would then send the request.

  4. The 3PL receives a response--an array of packages with two entries:

    • The old package (Package# 222) that now only lists two line items associated with it (3 and 19)
    • A new package (Package# 251) that lists two line items associated with it (4 and 22)

Updated over 3 years ago