Carrier Application Definition

The Carrier Application Definition file pulls all the other definitions and implementations together to tell the ShipEngine Connect how your carrier application is structured. This file can reside anywhere within your application as long as its location is specified in the main property of your package.json file. The definition may be specified in JavaScript, TypeScript, JSON, or YAML.

Carrier Application

Name	Type	Required?	Description
`id`	UUID	✔	A UUID that uniquely identifies the application for internal ShipEngine Connect purposes. This ID should never change.
`providerId`	UUID		A UUID that is used to relate this app to an existing production application. Do not set this field unless instructed to by the ShipEngine Connect team.
`name`	string	✔	The user-friendly name for this Carrier application.
`description`	string		A short, user-friendly description of this Carrier application.
`websiteURL`	string	✔	The URL of the carrier's website.
`logo`	string	✔	The file path to the Carrier's logo image.
`icon`	string	✔	The file path to the Carrier's icon image.
`trackingURLTemplate`	string	✔	Tracking URL format for the carrier. It must be a valid URL that contains curly braces (`{ }`) where the tracking number will be inserted. For example, `http://www.parcel-post.com/tracking/{}`.
`connectionForm`	Form	✔	A form that allows the user to connect to the service. This form will usually prompt for an account number and login credentials.
`settingsForm`	Form	✔	A form that allows the user update their connection settings, such as when a password is changed.
`manifestLocations`	string		Indicates which locations are included in end-of-day manifests. This field is required if the `createManifest` method is implemented. Valid values include the following. `all_locations` - The manifest includes all warehouse locations. `single_location` - The manifest includes only the specified warehouse location.
`manifestShipments`	string		Indicates which shipments are included in end-of-day manifests. This field is required if the `createManifest` method is implemented. Valid values include the following. `all_shipments` - All shipments for the current date will be included in the manifest. `explicit_shipments` - Only the explicitly selected shipments for the current date will be included in the manifest. `exclude_shipments` - All shipments for the current date except for those explicitly excluded will be included in the manifest.
`manifestType`	string		Indicates the type of manifesting supported by the carrier. Valid values include the following: `Physical` - Use this value if the carrier supports physical manifests, even if some of the delivery services only support digital manifests. `Digital` - Use this value if the carrier supports digital manifests, even if some of the delivery services only support phyiscal manifests.
`deliveryServices`	object[] or string[]	✔	The delivery services that are offered by the carrier. These services can be defined directly inline inside this file or you may specify the path to one or more Delivery Service Definition files.
`pickupServices`	object[] or string[]	✔	The pickup services that are offered for this carrier. These services can be defined directly inline insdie this file or you may specify the path to one or more Pickup Service Definition files.
`connect`	method or string		A method that connects to an existing account using the data that was gathered in the `connectionform`. Note that this function does not return a value but rather updates the `transaction.session` property. You may define this method direcly inline inside of this file or you may specify the path to the file that exports your `connect` method.
`createShipment`	method or string		A method that creates a new shipment. You may define this method direcly inline inside of this file or you may specify the path to the file that exports your `createShipment` method.
`cancelShipments`	method or string		A method that cancels one or more shipments. You may define this method direcly inline inside of this file or you may specify the path to the file that exports your `cancelShipments` method. This property is required for carriers who allow shipments to be cancelled.
`rateShipment`	method or string	✔	A method used to calculate shipping costs for a shipment, or multiple permutations of a shipment. You may define this method direcly inline inside of this file or you may specify the path to the file that exports your `rateShipment` method. If the shipping service provider does not support rates, the platform expects to receive an empty array.
`trackShipment`	method or string		A method used to get tracking details for a shipment. You may define this method direcly inline inside of this file or you may specify the path to the file that exports your `trackShipment` method.
`createManifest`	method or string		A method that creates an end-of-date manifest. You may define this method direcly inline inside of this file or you may specify the path to the file that exports your `createManifest` method.
`schedulePickup`	method or string		A method used to schedule a package pickup at a particular time and place. You may define this method direcly inline inside of this file or you may specify the path to the file that exports your `schedulePickup` method.
`cancelPickups`	method or string		A method used to cancel a previously scheduled package pickup. You may define this method direcly inline inside of this file or you may specify the path to the file that exports your `cancelPickups` method.

Examples

import { CarrierAppDefinition } from "@shipengine/connect";
const address:CarrierAppDefinition = {
  id: "8ea1989e-d504-433f-b031-b04d5d9ace94",
  name: "Cargo Incorporated",
  description: "Cargo Incorporated is the global leader in air cargo.",
  websiteURL: "https://cargo-inc.net",
  trackingURLTemplate: "https://cargo-inc.net/tracking/{}",
  logo: "./logo.svg",
  connectionForm: "src/connection-form.js",
  manifestType: "Digital",
  connect: "src/connect.ts",
  createShipment: "src/create-shipment.ts",
  rateShipment: "src/rate-shipment.ts",
  deliveryServices: [
    "delivery-services/economy-parcel.yaml",
    "delivery-services/ground-parcel.yaml",
    "delivery-services/overnight-parcel.yaml"
  ],
  pickupServices: [
    "pickup-services/one-time.yaml",
    "pickup-services/recurring.yaml",
    "pickup-services/drop-off.yaml"
  ]
}

const address = {
  id: "8ea1989e-d504-433f-b031-b04d5d9ace94",
  name: "Cargo Incorporated",
  description: "Cargo Incorporated is the global leader in air cargo.",
  websiteURL: "https://cargo-inc.net",
  trackingURLTemplate: "https://cargo-inc.net/tracking/{}",
  logo: "./logo.svg",
  manifestType: "Digital",
  connectionForm: "src/connection-form.js",
  connect: "src/connect.js",
  createShipment: "src/create-shipment.js",
  rateShipment: "src/rate-shipment.js",
  deliveryServices: [
    "delivery-services/economy-parcel.yaml",
    "delivery-services/ground-parcel.yaml",
    "delivery-services/overnight-parcel.yaml"
  ],
  pickupServices: [
    "pickup-services/one-time.yaml",
    "pickup-services/recurring.yaml",
    "pickup-services/drop-off.yaml"
  ]
}

id: 8ea1989e-d504-433f-b031-b04d5d9ace94
name: Cargo Incorporated
description:
  Cargo Incorporated is the global leader in air cargo.
websiteURL: https://cargo-inc.net
trackingURLTemplate: https://cargo-inc.net/tracking/{}
logo: ./logo.svg
manifestType: Digital
connectionForm: src/connection-form.js
connect: src/connect.js
createShipment: src/create-shipment.js
rateShipment: src/rate-shipment.js
deliveryServices:
  - delivery-services/economy-parcel.yaml
  - delivery-services/ground-parcel.yaml
  - delivery-services/overnight-parcel.yaml
pickupServices:
  - pickup-services/one-time.yaml
  - pickup-services/recurring.yaml
  - pickup-services/drop-off.yaml

{
  "id": "8ea1989e-d504-433f-b031-b04d5d9ace94",
  "name": "Cargo Incorporated",
  "description": "Cargo Incorporated is the global leader in air cargo.",
  "websiteURL": "https://cargo-inc.net",
  "trackingURLTemplate": "https://cargo-inc.net/tracking/{}",
  "logo": "./logo.svg",
  "manifestType": "Digital",
  "connectionForm": "src/connection-form.js",
  "deliveryServices": [
    "delivery-services/economy-parcel.yaml",
    "delivery-services/ground-parcel.yaml",
    "delivery-services/overnight-parcel.yaml"
  ],
  "pickupServices": [
    "pickup-services/one-time.yaml",
    "pickup-services/recurring.yaml",
    "pickup-services/drop-off.yaml"
  ],
  "connect": "src/connect.js",
  "createShipment": "src/create-shipment.js",
  "rateShipment": "src/rate-shipment.js"
}