@shipengine/js-api 1.22.0 → 1.24.0

package/addresses/types.d.ts

@@ -10,6 +10,8 @@ export interface Address {
     companyName?: string;
     countryCode: string;
     email?: string;
+    geolocation?: string;
+    instructions?: string;
     name: string;
     phone: string;
     postalCode: string;

package/connections/api.d.ts

@@ -1,5 +1,5 @@
 import { AxiosInstance } from "axios";
-import { CarrierServicesListResponse, ConnectCarrierAccount, ConnectCarrierAccountResponse, GetCarrierConnectionFormParams, GetCarrierConnectionFormResponse, ListCarrierConnectionsParams, ListCarrierConnectionsResponse } from "./types";
+import { CarrierServicesListResponse, ConnectCarrierAccount, ConnectCarrierAccountResponse, ConnectionsCarrierName, ConnectionsCarrierSettingsData, ConnectionsCarrierSettingsResponse, GetCarrierConnectionFormParams, GetCarrierConnectionFormResponse, ListCarrierConnectionsParams, ListCarrierConnectionsResponse } from "./types";
 /**
  * # Connections API module - /v1/connections
  */
@@ -24,4 +24,14 @@ export declare class ConnectionsAPI {
      * identified by the `carrier_code`.
      */
     getCarrierConnectionsServicesList: (carrierCode: string) => Promise<import("axios").AxiosResponse<CarrierServicesListResponse, any>>;
+    /**
+     * The `getCarrierSettings` method retrieves the settings for a given carrier,
+     * identified by the `carrierName` and `carrierCode`.
+     */
+    getCarrierSettings: <T extends ConnectionsCarrierName>(carrierName: T, carrierCode: string) => Promise<import("axios").AxiosResponse<ConnectionsCarrierSettingsResponse<T>, any>>;
+    /**
+     * The `updateCarrierSettings` method updates the settings for a given carrier,
+     * identified by the `carrierName` and `carrierCode`.
+     */
+    updateCarrierSettings: <T extends ConnectionsCarrierName>(carrierName: T, carrierCode: string, formData: ConnectionsCarrierSettingsData<T>) => Promise<import("axios").AxiosResponse<void, any>>;
 }

package/connections/settings-types.d.ts

@@ -0,0 +1,42 @@
+export type DHLExpressSettings = {
+    isPrimaryAccount: boolean;
+    nickname: string;
+    shouldHideAccountNumberOnArchiveDoc: boolean;
+};
+export type FedexSettings = {
+    isPrimaryAccount: boolean;
+    letterheadImage?: string;
+    nickname: string;
+    pickupType: "none" | "regular_pickup" | "request_courier" | "drop_box" | "business_service_center" | "station";
+    signatureImage?: string;
+    smartPostEndorsement: "none" | "return_service_requested" | "forwarding_service_requested" | "address_service_requested" | "change_service_requested" | "leave_if_no_response";
+    smartPostHub: "none" | "allentown_pa" | "atlanta_ga" | "baltimore_md" | "charlotte_nc" | "chino_ca" | "dallas_tx" | "denver_co" | "detroit_mi" | "edison_nj" | "grove_city_oh" | "groveport_oh" | "houston_tx" | "indianapolis_in" | "kansas_city_ks" | "los_angeles_ca" | "martinsburg_wv" | "memphis_tn" | "minneapolis_mn" | "new_berlin_wi" | "northborough_ma" | "orlando_fl" | "phoneix_az" | "pittsburgh_pa" | "reno_nv" | "sacramento_ca" | "salt_lake_city_ut" | "seattle_wa" | "st_louis_mo" | "windsor_ct" | "newark_ny" | "south_brunswick_nj" | "scranton_pa" | "wheeling_il";
+};
+export type UPSSettings = {
+    accountCountryCode: string;
+    accountNumber: string;
+    accountPostalCode: string;
+    invoice?: {
+        controlId: string;
+        invoiceAmount: number;
+        invoiceCurrencyCode: string;
+        invoiceDate: string;
+        invoiceNumber: string;
+    };
+    isPrimaryAccount: boolean;
+    mailInnovationsCostCenter?: string;
+    mailInnovationsCustomerGuid?: string;
+    mailInnovationsCustomerId?: string;
+    mailInnovationsEndorsement: "none" | "return_service_requested" | "forwarding_service_requested" | "address_service_requested" | "change_service_requested" | "leave_if_no_response";
+    nickname: string;
+    pickupType: "daily_pickup" | "occasional_pickup" | "customer_counter";
+    useCarbonNeutralShippingProgram: boolean;
+    useConsolidationServices: boolean;
+    useGroundFreightPricing: boolean;
+    useNegotiatedRates: boolean;
+    useOrderNumberOnMailInnovationsLabels: boolean;
+};
+export type UPSUpdateSettings = Omit<UPSSettings, "accountNumber">;
+export type ConnectionsCarrierName = "dhl_express" | "fedex" | "ups";
+export type ConnectionsCarrierSettingsResponse<Name extends ConnectionsCarrierName = ConnectionsCarrierName> = Name extends "dhl_express" ? DHLExpressSettings : Name extends "fedex" ? FedexSettings : Name extends "ups" ? UPSSettings : never;
+export type ConnectionsCarrierSettingsData<Name extends ConnectionsCarrierName = ConnectionsCarrierName> = Name extends "dhl_express" ? DHLExpressSettings : Name extends "fedex" ? FedexSettings : Name extends "ups" ? UPSUpdateSettings : never;

package/connections/types.d.ts

@@ -49,3 +49,4 @@ export type CarrierProviderService = Pick<CarrierService, "name" | "serviceCode"
 export type CarrierServicesListResponse = {
     services: CarrierProviderService[];
 };
+export * from "./settings-types";

package/index.js

@@ -1221,6 +1221,25 @@ class ConnectionsAPI {
         `/v1/connections/carriers/${carrierCode}/services`
       );
     };
+    /**
+     * The `getCarrierSettings` method retrieves the settings for a given carrier,
+     * identified by the `carrierName` and `carrierCode`.
+     */
+    this.getCarrierSettings = (carrierName, carrierCode) => {
+      return this.client.get(
+        `/v1/connections/carriers/${carrierName}/${carrierCode}/settings`
+      );
+    };
+    /**
+     * The `updateCarrierSettings` method updates the settings for a given carrier,
+     * identified by the `carrierName` and `carrierCode`.
+     */
+    this.updateCarrierSettings = (carrierName, carrierCode, formData) => {
+      return this.client.put(
+        `/v1/connections/carriers/${carrierName}/${carrierCode}/settings`,
+        formData
+      );
+    };
     this.client = client;
   }
 }

package/index.mjs

@@ -1217,6 +1217,25 @@ class ConnectionsAPI {
         `/v1/connections/carriers/${carrierCode}/services`
       );
     };
+    /**
+     * The `getCarrierSettings` method retrieves the settings for a given carrier,
+     * identified by the `carrierName` and `carrierCode`.
+     */
+    this.getCarrierSettings = (carrierName, carrierCode) => {
+      return this.client.get(
+        `/v1/connections/carriers/${carrierName}/${carrierCode}/settings`
+      );
+    };
+    /**
+     * The `updateCarrierSettings` method updates the settings for a given carrier,
+     * identified by the `carrierName` and `carrierCode`.
+     */
+    this.updateCarrierSettings = (carrierName, carrierCode, formData) => {
+      return this.client.put(
+        `/v1/connections/carriers/${carrierName}/${carrierCode}/settings`,
+        formData
+      );
+    };
     this.client = client;
   }
 }

package/labels/api.d.ts

@@ -1,90 +1,5 @@
 import { AxiosInstance } from "axios";
-import { CreationRangeQuery, PageableQuery, PageableResult, SortableQuery } from "../resources";
-import { Label, LabelLayout, LabelStatus, VoidRequest } from "./types";
-/**
- * # Labels API - Create Label Options
- */
-export interface CreateLabelOptions {
-    /**
-     * `displayScheme` is an optional string to control the display scheme of the label.
-     */
-    displayScheme?: string;
-    /**
-     * `labelDownloadType` is an optional string to control the download type of the label.
-     *
-     * e.g. `url` or `inline`
-     */
-    labelDownloadType?: string;
-    /**
-     * `labelFormat` is an optional string to control the format of the label.
-     *
-     * e.g. `pdf` or `zpl`
-     */
-    labelFormat?: string;
-    /**
-     * `labelLayout` is an optional string to control the layout of the label.
-     *
-     * e.g. `4x6` or `8.5x11`
-     */
-    labelLayout?: LabelLayout;
-    /**
-     *  A unique identifier for a carrier drop-off point where a merchant plans to deliver packages. This will take precedence over a shipment's Ship From address.
-     */
-    shipFromServicePointId?: string;
-    /**
-     * A unique identifier for a carrier service point where the shipment will be delivered by the carrier. This will take precedence over a shipment's Ship To address.
-     */
-    shipToServicePointId?: string;
-    /**
-     * `validateAddress` is an optional string to control address validation during
-     * label purchase.
-     */
-    validateAddress?: string;
-}
-/**
- * # Labels API - List Labels Params
- */
-export type ListLabelsParams = {
-    /**
-     * `batchId` is an optional string to retrieve labels within a given batch.
-     */
-    batchId?: string;
-    /**
-     * `carrierId` is an optional string to limit results to only lables for
-     * a specific carrier.
-     */
-    carrierId?: string;
-    /**
-     * `labelStatus` optionally allows filtering results to a specific status.
-     */
-    labelStatus?: LabelStatus;
-    /**
-     * `rateId` is an optional string to return labels purchased with a
-     * specific rate.
-     */
-    rateId?: string;
-    /**
-     * `serviceCode` is an optional string to limit results to only labels for
-     * a specific carrier service.
-     */
-    serviceCode?: string;
-    /**
-     * `shipmentId` is an optional string to filter labels by shipment ID. This
-     * is a unique identifier that ShipEngine API associates with your shipment.
-     */
-    shipmentId?: string;
-    /** `trackingNumber` is an optional string to retrieve labels for a specific
-     * tracking number
-     */
-    trackingNumber?: string;
-    /** `warehouseId` is an optional string to limit results to only those
-     * originating from a specific warehouse.
-     */
-    warehouseId?: string;
-} & PageableQuery & CreationRangeQuery & SortableQuery<"created_at" | "modified_at" | "order_date">;
-export type ListLabelsResult = {
-    labels: Label[];
-} & PageableResult;
+import { CreateLabelOptions, Label, ListLabelsParams, ListLabelsResult, VoidRequest } from "./types";
 /**
  * # Labels API module - /v1/labels
  */

package/labels/types.d.ts

@@ -1,32 +1,16 @@
+import { Address } from "../addresses";
 import { Money } from "../payments";
 import { RelayPoint } from "../relay-points";
-import { Download, LinkedResource } from "../resources";
+import { CreationRangeQuery, Download, LinkedResource, PageableQuery, PageableResult, SortableQuery } from "../resources";
 import { ShipmentPackage } from "../shipments";
 import { RateDetail } from "../types";
-/**
- * @category Entities
- */
 export type LabelChargeEvent = "carrier_default" | "on_creation" | "on_carrier_acceptance";
-/**
- * @category Entities
- */
 export type LabelDisplayScheme = "label" | "qr_code" | "label_and_paperless";
-/**
- * @category Entities
- */
 export type LabelFormat = "pdf" | "png" | "zpl";
-/**
- * @category Entities
- */
 export type LabelLayout = "4x6" | "letter";
-/**
- * @category Entities
- */
 export type LabelStatus = "processing" | "completed" | "error" | "voided";
-/**
- * @category Entities
- */
 export type Label = {
+    alternativeIdentifiers?: string[];
     batchId: string;
     carrierCode: string;
     carrierId: string;
@@ -46,37 +30,112 @@ export type Label = {
     packageCode: string;
     packages: ShipmentPackage[];
     paperlessDownload: PaperlessDownload | null;
+    qrCodeDownload?: LinkedResource;
     rateDetails: RateDetail[];
     relayPoints: {
         shipFrom: RelayPoint;
         shipTo: RelayPoint;
     };
+    requestedComparisonAmount?: Money;
     rmaNumber: string;
     serviceCode: string;
     shipDate: string;
     shipmentCost: Money;
     shipmentId: string;
-    shippingRuleId: string;
+    shippingRuleId: string | null;
+    shipTo: Address;
     status: LabelStatus;
     trackable: boolean;
     trackingNumber: string;
     trackingStatus: string;
     trackingUrl: string;
     voided: boolean;
-    voidedAt: string;
+    voidedAt: string | null;
 };
-/**
- * @category Entities
- */
 export type PaperlessDownload = {
     handoffCode: string;
     href: string;
     instructions: string;
 };
-/**
- * @category Entities
- */
 export type VoidRequest = {
     approved: boolean;
     message: string;
 };
+export type ListLabelsResult = {
+    labels: Label[];
+} & PageableResult;
+export type ListLabelsParams = {
+    /**
+     * `batchId` is an optional string to retrieve labels within a given batch.
+     */
+    batchId?: string;
+    /**
+     * `carrierId` is an optional string to limit results to only lables for
+     * a specific carrier.
+     */
+    carrierId?: string;
+    /**
+     * `labelStatus` optionally allows filtering results to a specific status.
+     */
+    labelStatus?: LabelStatus;
+    /**
+     * `rateId` is an optional string to return labels purchased with a
+     * specific rate.
+     */
+    rateId?: string;
+    /**
+     * `serviceCode` is an optional string to limit results to only labels for
+     * a specific carrier service.
+     */
+    serviceCode?: string;
+    /**
+     * `shipmentId` is an optional string to filter labels by shipment ID. This
+     * is a unique identifier that ShipEngine API associates with your shipment.
+     */
+    shipmentId?: string;
+    /** `trackingNumber` is an optional string to retrieve labels for a specific
+     * tracking number
+     */
+    trackingNumber?: string;
+    /** `warehouseId` is an optional string to limit results to only those
+     * originating from a specific warehouse.
+     */
+    warehouseId?: string;
+} & PageableQuery & CreationRangeQuery & SortableQuery<"created_at" | "modified_at" | "order_date">;
+export interface CreateLabelOptions {
+    /**
+     * `displayScheme` is an optional string to control the display scheme of the label.
+     */
+    displayScheme?: string;
+    /**
+     * `labelDownloadType` is an optional string to control the download type of the label.
+     *
+     * e.g. `url` or `inline`
+     */
+    labelDownloadType?: string;
+    /**
+     * `labelFormat` is an optional string to control the format of the label.
+     *
+     * e.g. `pdf` or `zpl`
+     */
+    labelFormat?: string;
+    /**
+     * `labelLayout` is an optional string to control the layout of the label.
+     *
+     * e.g. `4x6` or `8.5x11`
+     */
+    labelLayout?: LabelLayout;
+    /**
+     *  A unique identifier for a carrier drop-off point where a merchant plans to deliver packages. This will take precedence over a shipment's Ship From address.
+     */
+    shipFromServicePointId?: string;
+    /**
+     * A unique identifier for a carrier service point where the shipment will be delivered by the carrier. This will take precedence over a shipment's Ship To address.
+     */
+    shipToServicePointId?: string;
+    /**
+     * `validateAddress` is an optional string to control address validation during
+     * label purchase.
+     */
+    validateAddress?: string;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipengine/js-api",
-  "version": "1.22.0",
+  "version": "1.24.0",
   "main": "./index.js",
   "types": "./index.d.ts",
   "exports": {

package/shipments/types.d.ts

@@ -6,25 +6,10 @@ import { Money } from "../payments";
 import { Rate } from "../rates";
 import { Download, LinkedResource } from "../resources";
 import { WeightWithUnit } from "../weight";
-/**
- * @category Entities
- */
 export type AddressValidationOptions = "no_validation" | "validate_only" | "validate_and_clean";
-/**
- * @category Entities
- */
 export type CustomsContents = "documents" | "gift" | "merchandise" | "returned_goods" | "sample";
-/**
- * @category Entities
- */
 export type CustomsNonDeliveryOptions = "return_to_sender" | "treat_as_abandoned";
-/**
- * @category Entities
- */
 export type BillToParties = "recipient" | "third_party";
-/**
- * @category Entities
- */
 export declare enum ConfirmationType {
     DELIVERY = "delivery",
     SIGNATURE = "signature",
@@ -34,9 +19,6 @@ export declare enum ConfirmationType {
     DELIVERY_MAILED = "delivery_mailed",
     NONE = "none"
 }
-/**
- * @category Entities
- */
 export declare enum CustomsContentsType {
     DOCUMENTS = "documents",
     GIFT = "gift",
@@ -44,20 +26,11 @@ export declare enum CustomsContentsType {
     RETURNED_GOODS = "returned_goods",
     SAMPLE = "sample"
 }
-/**
- * @category Entities
- */
 export declare enum CustomsNonDeliveryType {
     RETURN_TO_SENDER = "return_to_sender",
     TREAT_AS_ABANDONED = "treat_as_abandoned"
 }
-/**
- * @category Entities
- */
 export type CustomsTermsOfTradeCode = "exw" | "fca" | "cpt" | "cip" | "dpu" | "dap" | "ddp" | "fas" | "fob" | "cfr" | "cif" | "ddu" | "daf" | "deq" | "des";
-/**
- * @category Entities
- */
 export interface CustomsInvoiceAdditionalDetails {
     discount?: Money;
     freightCharge?: Money;
@@ -65,9 +38,6 @@ export interface CustomsInvoiceAdditionalDetails {
     otherChargeDescription?: string;
     otherCharges?: Money;
 }
-/**
- * @category Entities
- */
 export interface DangerousGoods {
     AddionalDescription?: string;
     dangerousAmount?: {
@@ -92,46 +62,19 @@ export interface DangerousGoods {
     transportMean?: DangerousGoodsTransportMean;
     tunnelCode?: string;
 }
-/**
- * @category Entities
- */
 export type DangerousGoodsPackagingGroup = "i" | "ii" | "iii";
-/**
- * @category Entities
- */
 export type DangerousGoodsPackagingInstructionSection = "section_1" | "section_2" | "section_1a" | "section_1b";
-/**
- * @category Entities
- */
 export type DangerousGoodsRegulationLevel = "lightly_regulated" | "fully_regulated" | "limited_quantities" | "excepted_quantity";
-/**
- * @category Entities
- */
 export type DangerousGoodsTransportMean = "ground" | "water" | "cargo_aircraft_only" | "passenger_aircraft";
-/**
- * @category Entities
- */
 export declare enum InsuranceProviderType {
     SHIPSURANCE = "shipsurance",
     CARRIER = "carrier",
     THIRD_PARTY = "third_party",
     NONE = "none"
 }
-/**
- * @category Entities
- */
 export type ShipmentStatus = "cancelled" | "label_purchased" | "pending" | "processing";
-/**
- * @category Entities
- */
 export type TaxableEntityType = "shipper" | "recipient";
-/**
- * @category Entities
- */
 export type TaxableIdentifierType = "vat" | "eori" | "ssn" | "ein" | "tin" | "ioss" | "pan" | "voec";
-/**
- * @category Entities
- */
 export interface Product {
     countryOfOrigin?: string;
     dangerousGoods?: DangerousGoods;
@@ -147,9 +90,6 @@ export interface Product {
     vatRate?: number;
     weight?: WeightWithUnit;
 }
-/**
- * @category Entities
- */
 export interface ShipmentItem {
     asin?: string;
     externalOrderId?: string;
@@ -159,9 +99,6 @@ export interface ShipmentItem {
     quantity: number;
     sku?: string;
 }
-/**
- * @category Entities
- */
 export type ShipmentPackage = Omit<CarrierPackage, "name"> & {
     contentDescription?: string;
     externalPackageId?: string;
@@ -178,26 +115,15 @@ export type ShipmentPackage = Omit<CarrierPackage, "name"> & {
     trackingNumber?: string;
     weight: WeightWithUnit;
 };
-/**
- * @category Entities
- */
 export interface TaxIdentifier {
     identifierType: TaxableIdentifierType;
     issuingAuthority: string;
     taxableEntityType: TaxableEntityType;
     value: string;
 }
-/**
- * @category Entities
- */
 export type OriginTypes = "pickup" | "drop_off";
-/**
- * @category Entities
- */
 export type PaymentTypes = "any" | "cash" | "cash_equivalent" | "none";
-/**
- * @deprecated since July 2023
- */
+/** @deprecated since July 2023 */
 export interface CustomsItem {
     countryOfOrigin?: string;
     customsItemId?: string;
@@ -210,14 +136,12 @@ export interface CustomsItem {
     value: Money | number;
     valueCurrency?: string;
 }
-/**
- * @category Entities
- */
 export type Customs = {
     contents: CustomsContents;
     contentsExplanation?: string;
     /**
      * @deprecated since July 2023
+     * CustomsItems array is deprecated, use the Products array within Packages instead. Leaving this here for backwards compatibility
      */
     customsItems?: CustomsItem[];
     declaration?: string;
@@ -226,13 +150,11 @@ export type Customs = {
     nonDelivery: CustomsNonDeliveryOptions;
     termsOfTradeCode?: CustomsTermsOfTradeCode;
 };
-/**
- * @category Entities
- */
 export interface Shipment {
     addressValidation?: AddressValidation;
     advancedOptions?: {
         additionalHandling?: boolean;
+        ancillaryEndorsementsOption?: string;
         billToAccount?: string;
         billToCountryCode?: string;
         billToParty?: BillToParties;
@@ -248,11 +170,20 @@ export interface Shipment {
         deliveredDutyPaid?: boolean;
         dryIce?: boolean;
         dryIceWeight?: WeightWithUnit;
+        eventNotification?: boolean;
+        fedexFreight?: {
+            bookingConfirmation?: string;
+            shipperLoadAndCount?: string;
+        };
         freightClass?: string;
+        limitedQuantity?: boolean;
         nonMachinable?: boolean;
         originType?: OriginTypes;
+        ownDocumentUpload?: boolean;
+        returnPickupAttempts?: number;
         saturdayDelivery?: boolean;
         shipperRelease?: boolean;
+        thirdPartyConsignee?: boolean;
         useUpsGroundFreightPricing?: boolean;
     };
     carrierId: string;
@@ -263,6 +194,7 @@ export interface Shipment {
     externalOrderId?: string;
     externalShipmentId?: string;
     insuranceProvider: InsuranceProviderType;
+    isReturn?: boolean;
     items: ShipmentItem[];
     modifiedAt: string;
     orderSourceCode: OrderSourceCode;
@@ -273,7 +205,9 @@ export interface Shipment {
     shipDate?: string;
     shipFrom: Address | null;
     shipmentId: string;
+    shipmentNumber?: string;
     shipmentStatus: ShipmentStatus;
+    shippingRuleId?: string;
     shipTo: Address;
     tags: {
         name: string;