eShipper REST APIs

https://ww2.eshipper.com/v2/api-docs/
Admin
eShipper REST APIs enable businesses to programmatically integrate their ERP, Order Management, and...
Tokens:50,496
Snippets:159
Trust Score:9.9
Update:1 year ago
Show doc for...
Tokens:
Raw
### Authenticate User - Web User Example

Source: https://ww2.eshipper.com/v2/api-docs/REST%20APIs

This code example shows how to authenticate a web user using their username and password. It is intended for users who registered directly on the eShipper website. The 'principal' field should contain the username and 'credential' should contain the password.

```JSON
{
  "principal": "john",
  "credential": "password"
}
```

--------------------------------

### Authenticate User (XML)

Source: https://ww2.eshipper.com/v2/api-docs/REST%20APIs

Provides XML examples for authenticating a web user with username/password and an API-only user with a key/secret.

```xml
<AuthenticationRequest><principal>john</principal><credential>password</credential></AuthenticationRequest>
```

```xml
<AuthenticationRequest><principal>AT1234567890</principal><credential>aAbBcCdDeEfFgGhHiIjJkKlLmMnNoOpPqQrRsStTuUvVwWxXyYzZ0123456=</credential></AuthenticationRequest>
```

--------------------------------

### API Authentication Header Example

Source: https://ww2.eshipper.com/v2/api-docs/REST%20APIs

This example demonstrates how to include the bearer token in the Authorization header for API requests. The token is obtained after a successful sign-in and is essential for authenticating subsequent API calls.

```http
Authorization: bearer aAbBcCdDeEfFgGhHiIjJkKlLmMnNoOpPqQrRsStTuUvVwWxXyYzZ0123456=
```

--------------------------------

### Refresh Token Request Example (XML)

Source: https://ww2.eshipper.com/v2/api-docs/REST%20APIs

This snippet shows how to refresh an access token using a provided refresh token in XML format. It is applicable for both web and API-only users.

```xml
<RefreshTokenDTO>
  <refresh_token>eyJhbGciOiJIU</refresh_token>
</RefreshTokenDTO>
```

--------------------------------

### Refresh Token Request Example (JSON)

Source: https://ww2.eshipper.com/v2/api-docs/REST%20APIs

This snippet demonstrates how to refresh an access token using a provided refresh token in JSON format. It is applicable for both web and API-only users.

```json
{
  "refresh_token": "eyJhbGciOiJIU"
}
```

--------------------------------

### Authenticate User - API-only User Example

Source: https://ww2.eshipper.com/v2/api-docs/REST%20APIs

This example illustrates how to authenticate an API-only user using an API key and secret. This method is suitable for programmatic access to the eShipper API. The 'principal' field should be the API key and 'credential' should be the associated secret.

```JSON
{
  "principal": "AT1234567890",
  "credential": "aAbBcCdDeEfFgGhHiIjJkKlLmMnNoOpPqQrRsStTuUvVwWxXyYzZ0123456="
}
```

--------------------------------

### API Authentication Error Response (XML)

Source: https://ww2.eshipper.com/v2/api-docs/REST%20APIs

Defines the XML schema for error responses, specifically detailing authentication failures. It guides users on how to correctly format the 'Authorization' header or alternative authentication methods.

```xml
<ErrorResponse_APIv2UserView>
  <!-- Schema details for error response -->
</ErrorResponse_APIv2UserView>
```

--------------------------------

### Get Return Shipment Rates Request and Response (XML)

Source: https://ww2.eshipper.com/v2/api-docs/REST%20APIs

Specifies the XML schema for requesting return shipment rates and the schema for the successful response containing available rates. This endpoint allows users to find the best rates for return shipments.

```xml
<ReturnQuoteRequest_APIv2UserView>
  <!-- Schema details for return quote request -->
</ReturnQuoteRequest_APIv2UserView>

<ReturnQuoteResponse_APIv2UserView>
  <!-- Schema details for return quote response -->
</ReturnQuoteResponse_APIv2UserView>
```

--------------------------------

### Register New Company

Source: https://ww2.eshipper.com/v2/api-docs/REST%20APIs

Registers a new company with the system.

```APIDOC
## POST /api/v2/register

### Description
Registers a new company.

### Method
POST

### Endpoint
/api/v2/register

### Parameters
(Request body details would typically follow here in a full OpenAPI spec)

### Response
(Success and error response details would typically follow here in a full OpenAPI spec)
```

--------------------------------

### Account Details

Source: https://ww2.eshipper.com/v2/api-docs/REST%20APIs

Information required for creating a new user account for the e-shipper platform.

```APIDOC
## Account Details (AccountDetails)

### Description
This object contains the necessary information to register a new company account on the e-shipper platform. The provided contact will be set as the initial administrator.

### Required Properties
- **contactName** (string) - The name of the primary contact person for the account.
- **emailAddress** (string) - The email address for the account contact.
- **password** (string) - The password for the user account.
- **phone** (string) - The contact phone number for the company.
- **userName** (string) - The username for logging into the system.

### Properties
- **contactName** (string) - The name of the contact registering the company. It will be designated as the initial admin to manage the company (maxLength: 100, minLength: 3).
- **emailAddress** (string) - Email address of the contact registering the company.
- **phone** (string) - Company contact phone number with country prefix (e.g., +14165550852). Must match the pattern: `^(\\+\\d{1,3}( )?)?((\\(\\d{3}\\))|\\d{3})[- .]?\\d{3}[- .]?\\d{4}$`.
- **userName** (string) - Username of the contact registering for the company. It will be used by the designated user to login into the system (maxLength: 100, minLength: 3).
- **password** (string) - Password of the contact registering for the company. It will be used by the designated user to login into the system.

### Example
```json
{
  "contactName": "Jane Doe",
  "emailAddress": "jane.doe@example.com",
  "phone": "+14165551234",
  "userName": "janedoe_admin",
  "password": "SecureP@ssw0rd123"
}
```
```

--------------------------------

### GET /api/v2/track/events

Source: https://ww2.eshipper.com/v2/api-docs/REST%20APIs

Retrieves tracking events that have been published via webhooks.

```APIDOC
## GET /api/v2/track/events

### Description
Fetch tracking events which system had published over webhooks.

### Method
GET

### Endpoint
/api/v2/track/events

### Parameters
#### Query Parameters
- **trackingNumbers** (array of strings) - Optional - A list of tracking numbers to filter events.
- **includePublished** (boolean) - Optional - Whether to include published events. Defaults to true.
- **pageable** (Pageable object) - Required - Specifies pagination details for the request.

### Response
#### Success Response (200)
- The response is an array of TrackingEvents objects, representing the tracking events for the specified shipments.

#### Error Response (401)
- Description: Authentication failed - either authentication information is missing from the request, is invalid, or has expired. Please make sure to include an 'Authorization' header with the HTTP request, having its value set to 'Bearer [authentication token]' (without quotes), where [authentication token] refers to the token returned by the Sign-in API upon successful authentication. For instance, if the token returned by the Sign-in API is aAbBcCdDeEfFgGhHiIjJkKlLmMnNoOpPqQrRsStTuUvVwWxXyYzZ0123456, send the header as 'Authorization: Bearer aAbBcCdDeEfFgGhHiIjJkKlLmMnNoOpPqQrRsStTuUvVwWxXyYzZ0123456'. Please note that authentication can also fail if the authentication token has expired - do make sure to check the time of expiration included in the response from the Sign-in API. Alternatively, pass the username in request header X-API-KEY and password in request header X-API-SECRET.
```

--------------------------------

### GET /api/v2/track/shipment-number/{orderId}

Source: https://ww2.eshipper.com/v2/api-docs/REST%20APIs

Fetches tracking information for a shipment using its unique order ID.

```APIDOC
## GET /api/v2/track/shipment-number/{orderId}

### Description
Fetch tracking information for a shipment having a specified shipment number.

### Method
GET

### Endpoint
/api/v2/track/shipment-number/{orderId}

### Parameters
#### Path Parameters
- **orderId** (integer) - Required - The unique identifier for the shipment.

### Response
#### Success Response (200)
- The response contains tracking information for the specified shipment, which can be returned in JSON or XML format.

#### Error Response (404)
- Description: If no shipment with the specified identifier id found, or if tracking information for the said shipment is unavailable.

#### Error Response (401)
- Description: Authentication failed - either authentication information is missing from the request, is invalid, or has expired. Please make sure to include an 'Authorization' header with the HTTP request, having its value set to 'Bearer [authentication token]' (without quotes), where [authentication token] refers to the token returned by the Sign-in API upon successful authentication. For instance, if the token returned by the Sign-in API is aAbBcCdDeEfFgGhHiIjJkKlLmMnNoOpPqQrRsStTuUvVwWxXyYzZ0123456, send the header as 'Authorization: Bearer aAbBcCdDeEfFgGhHiIjJkKlLmMnNoOpPqQrRsStTuUvVwWxXyYzZ0123456'. Please note that authentication can also fail if the authentication token has expired - do make sure to check the time of expiration included in the response from the Sign-in API. Alternatively, pass the username in request header X-API-KEY and password in request header X-API-SECRET.
```

--------------------------------

### Shipment Creation Parameters

Source: https://ww2.eshipper.com/v2/api-docs/REST%20APIs

This section details the various optional parameters that can be included when creating a shipment.

```APIDOC
## Shipment Creation Request Body Parameters

### Description
This endpoint allows for the creation of shipments with a comprehensive set of optional parameters to customize shipping details, such as references, billing information, insurance, and special delivery instructions.

### Method
POST

### Endpoint
/shipments

### Parameters
#### Request Body
- **reference1** (string) - Optional - Optional reference code with which the sender identifies the shipment.
- **reference2** (string) - Optional - Optional second reference code with which the sender identifies the shipment.
- **reference3** (string) - Optional - Optional third reference code with which the sender identifies the shipment.
- **transactionId** (string) - Optional - Optional transaction or co-relation id with which the sender identifies the shipment. It can be used to link shipments between sender system and eShipper system. It is not printed on the label but would be used for lookup and reporting purposes only.
- **billingReference** (string) - Optional - Optional billing identifier to bill shipments together with the same identifier within a billing cycle.
- **currency** (string) - Optional - Optional currency code for the shipment.
- **signatureRequired** (string) - Optional - Whether signature must be obtained at the time of delivery. Additional charges may apply. Specify only if required, skip if not required for the current shipment.
- **insuranceType** (string) - Optional - Choose eShipper or Carrier as the insurance provider for shipments requiring insurance cover. Additional cost may apply over and above the shipping costs, based on the nature of shipment.
- **dangerousGoodsType** (string) - Optional - Whether any of the packages included in the shipment contains dangerous goods, as designated by a regulatory authority. The exact nature of dangerous goods must be specified here for proper handling of the packages by the carrier. Specify only if required, skip if the current shipment does not contain any goods deemed to be dangerous.
- **pickup** (object) - Optional - Details for shipment pickup. Refers to `#/components/schemas/PickupRequest`.
- **customsInformation** (object) - Optional - Information related to customs for international shipments. Refers to `#/components/schemas/CustomsInformation`.
- **thirdPartyBilling** (object) - Optional - Details for third-party billing. Refers to `#/components/schemas/ThirdPartyBilling`.
- **commodityType** (string) - Optional - Classification of goods being transported based on their nature, characteristics, and handling requirements.
- **isSaturdayService** (boolean) - Optional - Whether the shipment is expected to be delivered to the recipient on a Saturday. Set to true if Saturday delivery should be attempted, subject to the carrier's ability to do so. Some carriers may apply a surcharge for attempting deliveries on a Saturday. Specify only if applicable and required, skip if not required for the current shipment.
- **holdForPickupRequired** (boolean) - Optional - Whether the carrier should hold the shipment at a location near the intended destination for the recipient to pick up. Additional charges may apply. Specify only if applicable, skip if not required for the current shipment.
- **specialEquipment** (boolean) - Optional - Whether the shipment contains any equipment that requires special handling during pickup, delivery or while in transit. Additional charges may apply. Specify only if applicable, skip if not required for the current shipment.
- **deliveryAppointment** (boolean) - Optional - Whether the carrier must make an appointment with the recipient before attempting delivery. Additional charges may apply. Specify only if applicable and required, skip if not required for the current shipment.
- **insideDelivery** (boolean) - Optional - Whether the shipment must be delivered inside residential or commercial premises. Additional charges may apply. Specify only if applicable and required, skip if not required for the current shipment.
- **insidePickup** (boolean) - Optional - Whether the shipment pickup must be made from inside residential or commercial premises. Additional charges may apply. Specify only if applicable and required, skip if not required for the current shipment.

### Request Example
```json
{
  "reference1": "INV12345",
  "currency": "USD",
  "signatureRequired": "true",
  "insuranceType": "eShipper",
  "isSaturdayService": true,
  "pickup": {
    "location": "business",
    "readyTime": "17:00:00",
    "closeTime": "19:00:00",
    "date": "2023-10-27"
  }
}
```

### Response
#### Success Response (201 Created)
- **shipmentId** (string) - Unique identifier for the created shipment.
- **status** (string) - Current status of the shipment.

#### Response Example
```json
{
  "shipmentId": "shp_12345abcde",
  "status": "PENDING"
}
```
```

--------------------------------

### Shipment Creation Parameters

Source: https://ww2.eshipper.com/v2/api-docs/REST%20APIs

Details on optional parameters for creating a shipment, including pickup and delivery options, and special handling requirements.

```APIDOC
## Shipment Creation Parameters

### Description
This section details optional parameters that can be included when creating a shipment. These parameters cover various aspects such as pickup/delivery preferences, special handling, and service-specific options.

### Parameters

#### Request Body Parameters

- **pickupFromInsidePremises** (boolean) - Optional - Indicates if the shipment pickup requires access to the inside of residential or commercial premises. Not all carriers support this, and additional charges may apply.
- **saturdayPickupRequired** (boolean) - Optional - Specifies if the shipment pickup is required on a Saturday. Not all carriers support Saturday pickups, and additional charges may apply.
- **pickupTailgate** (boolean) - Optional - Indicates if a tailgate or liftgate is required at the time of shipment pickup. Not all carriers support this, and additional charges may apply.
- **deliveryTailgate** (boolean) - Optional - Indicates if a tailgate or liftgate is required at the time of shipment delivery. Not all carriers support this, and additional charges may apply.
- **limitedAccess** (boolean) - Optional - Indicates if the shipment destination has limited access or restriction protocols. Not all carriers support this, and additional charges may apply.
- **excessLength** (boolean) - Optional - Indicates if the shipment exceeds standard pallet dimension thresholds. Not all carriers support this, and additional charges may apply.
- **stackable** (boolean) - Optional - Denotes if packages can be stacked. Non-stackable items may incur surcharges. Set to `false` for fragile items to prevent stacking.
- **noSafeDrop** (boolean) - Optional - Prevents a safe drop for the shipment; recipient presence is required for delivery.
- **fbaApproved** (boolean) - Optional - Indicates if the item has been approved by Amazon.
- **cardForPickup** (boolean) - Optional - Requests card-for-pickup service; the item will not be delivered to the door, and a notice card will be left for pickup at a designated location.
- **serviceId** (integer) - Optional - Identifier for a specific shipping service (e.g., UPS Ground Saver).
- **cod** (Cod) - Optional - Cash on Delivery details for the shipment.

### Request Example
```json
{
  "pickupFromInsidePremises": true,
  "saturdayPickupRequired": false,
  "pickupTailgate": true,
  "deliveryTailgate": false,
  "limitedAccess": false,
  "excessLength": false,
  "stackable": true,
  "noSafeDrop": false,
  "fbaApproved": true,
  "cardForPickup": false,
  "serviceId": 12345
}
```

### Response
*(Success response details would typically be provided here, but are not available in the input text.)*

#### Success Response (200)
*(No specific fields described in the input text for success response.)*

#### Response Example
```json
{
  "message": "Shipment details updated successfully."
}
```
```

--------------------------------

### GET /api/v2/authenticated

Source: https://ww2.eshipper.com/v2/api-docs/REST%20APIs

Checks the authentication status of the current user. This endpoint returns a '200 OK' status if the user is authenticated.

```APIDOC
## GET /api/v2/authenticated

### Description
Indicates whether the user is authenticated.

### Method
GET

### Endpoint
/api/v2/authenticated

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **status** (string) - Indicates '200 OK' if the user is authenticated.

#### Response Example
```json
"200 OK"
```

#### Error Response (401)
- **description** (string) - Authentication failed. Ensure 'Authorization' header is set to 'Bearer [token]' or use 'X-API-KEY' and 'X-API-SECRET' headers.
```

--------------------------------

### GET /api/v2/quote/{id}

Source: https://ww2.eshipper.com/v2/api-docs/REST%20APIs

Retrieves a previously saved quote by its identifier. Returns an error if the quote is not found or if authentication fails.

```APIDOC
## GET /api/v2/quote/{id}

### Description
Retrieves a previously saved quote using its unique identifier. An error is returned if no quote with the specified identifier is found.

### Method
GET

### Endpoint
/api/v2/quote/{id}

#### Path Parameters
- **id** (integer) - Required - The unique identifier of the quote to retrieve.

### Response
#### Success Response (200)
- **QuoteResponse** (object) - Contains the details of the retrieved quote.

#### Error Response (404)
- **Response** (object) - Returned if no quote matching the specified criteria is found.

#### Error Response (401)
- **Response** (object) - Authentication failed. Include an 'Authorization' header with 'Bearer [authentication token]' or use 'X-API-KEY' and 'X-API-SECRET' headers.
```

--------------------------------

### HTTP Headers for API Authentication

Source: https://ww2.eshipper.com/v2/api-docs/REST%20APIs

Illustrates the required HTTP headers for API authentication. It shows the format for using a Bearer token or alternative API key and secret for authentication.

```http
Authorization: Bearer [authentication token]
X-API-KEY: [username]
X-API-SECRET: [password]
```

--------------------------------

### GET /api/v2/ship/{orderId}/label

Source: https://ww2.eshipper.com/v2/api-docs/REST%20APIs

Retrieves the shipping label for a specified order ID. This is essential for fulfilling shipment requirements.

```APIDOC
## GET /api/v2/ship/{orderId}/label

### Description
Retrieves the shipping label for a specified order ID. This endpoint is crucial for generating and obtaining the necessary label for shipping a package.

### Method
GET

### Endpoint
/api/v2/ship/{orderId}/label

### Parameters
#### Path Parameters
- **orderId** (integer) - Required - The unique identifier for the shipping order for which the label is requested.

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **(string)** - The shipping label data, often in a string format representing the label content or a URL to it.

#### Response Example
```json
{
  "example": "Label content or URL"
}
```

#### Error Response (401)
- **description**: Authentication failed. Ensure an 'Authorization' header with a valid 'Bearer [authentication token]' is included. Alternatively, use 'X-API-KEY' and 'X-API-SECRET' headers. Token may be expired.

#### Error Response (404)
- **description**: If no shipment matching the specified criteria is found.
```

--------------------------------

### POST /api/v2/pickup

Source: https://ww2.eshipper.com/v2/api-docs/REST%20APIs

Initiate a pickup request for a shipping order. This endpoint is used to schedule a pickup for an already created shipping order.

```APIDOC
## POST /api/v2/pickup

### Description
Request pickup for a shipping order. This endpoint allows you to schedule a pickup for a specific shipping order.

### Method
POST

### Endpoint
/api/v2/pickup

### Parameters
#### Request Body
- **PickupRequest** (object) - Required - Contains details for the pickup request. Refer to the PickupRequest schema for specific fields.

### Request Example
```json
{
  "pickup_details": {
    "pickup_date": "2023-10-27",
    "pickup_time": "14:00",
    "pickup_location": "123 Main St, Anytown, CA 90210"
  },
  "order_id": "ORD123456"
}
```

### Response
#### Success Response (201)
- **pickup_id** (string) - A unique identifier for the scheduled pickup.
- **status** (string) - The current status of the pickup request (e.g., "Scheduled").

#### Response Example (201)
```json
{
  "pickup_id": "PU789012",
  "status": "Scheduled"
}
```
```

--------------------------------

### GET /Returns/Rates

Source: https://ww2.eshipper.com/v2/api-docs/REST%20APIs

Retrieves rates for a return shipment based on origin, destination, carrier, service, and additional service requirements.

```APIDOC
## POST /Returns/Rates

### Description
Get rates for a return shipment based on origin and destination, preferred carrier(s), service(s) and additional service requirements.

### Method
POST

### Endpoint
/Returns/Rates

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Optional limit to restrict the number of return rates returned. Defaults to unlimited.
- **type** (string) - Optional - Optional service type for return rates. Use 'STN' for normal, 'STS' for faster, 'STU' for urgent. Defaults to all available service types.
- **sort** (string) - Optional - Optional order for sorting return rates. Use 'PRICE', 'TRANSIT_TIME', 'CARRIER', 'MODE'. Defaults to 'PRICE'.

#### Request Body
- **application/json** (schema: ReturnQuoteRequest_APIv2UserView) - Required
- **application/xml** (schema: ReturnQuoteRequest_APIv2UserView) - Required

### Response
#### Success Response (200)
- Description: Rates available for the specified return shipment. One quote is returned for every carrier and service combination.

#### Error Response (400)
- Description: When there are validation errors while creating a return quote.
- Content:
  - application/json (schema: ErrorResponse_APIv2UserView)
  - application/xml (schema: ErrorResponse_APIv2UserView)
```

--------------------------------

### ReturnShippingRequest

Source: https://ww2.eshipper.com/v2/api-docs/REST%20APIs

Initiates a return shipment. This endpoint is used to create and process a return shipment request.

```APIDOC
## POST /api/returns/ship

### Description
Initiates a return shipment.

### Method
POST

### Endpoint
/api/returns/ship

### Parameters
#### Request Body
- **scheduledShipDate** (string) - Required - Date and time of dispatch for the shipment in yyyy-MM-dd HH:mm format.
- **from** (object) - Required - The return origin address.
- **to** (object) - Required - The return destination address.
- **packagingUnit** (string) - Required - Measurement system for packages (Imperial or Metric).
- **packages** (object) - Required - Details of the packages in the shipment.
- **saturdayPickupRequired** (boolean) - Required - Indicates if Saturday pickup is required.
- **insuranceType** (string) - Required - Type of insurance for the shipment.
- **reference1** (string) - Optional - First reference code for the shipment.
- **reference2** (string) - Optional - Second reference code for the shipment.
- **reference3** (string) - Optional - Third reference code for the shipment.
- **transactionId** (string) - Optional - Transaction or co-relation ID.
- **billingReference** (string) - Optional - Billing identifier for grouping shipments.
- **currency** (string) - Optional - Currency code for the shipment.
- **signatureRequired** (string) - Required - Signature requirement for the shipment.
- **serviceId** (integer) - Optional - Identifier for a specific shipping service.
- **thirdPartyBilling** (object) - Optional - Third-party billing details.
- **commodityType** (string) - Optional - Classification of goods.
- **boxFreeLabelFree** (boolean) - Optional - Flag for label-free boxes.
- **qrCodePackaged** (boolean) - Optional - Flag for QR code packaging.
- **returnLabelPackaged** (boolean) - Optional - Flag for return label packaging.

### Request Example
```json
{
  "scheduledShipDate": "2023-10-27 14:00",
  "from": { ... },
  "to": { ... },
  "packagingUnit": "Metric",
  "packages": { ... },
  "saturdayPickupRequired": true,
  "insuranceType": "None",
  "signatureRequired": "NoSignatureRequired",
  "serviceId": 123,
  "commodityType": "Documents"
}
```

### Response
#### Success Response (200)
- **type** (object) - The type of the response.
- **message** (string) - An informative message associated with the response.
- **quoteId** (integer) - The ID of the saved quote.

#### Response Example
```json
{
  "type": { ... },
  "message": "Return shipment processed successfully.",
  "quoteId": 54321
}
```
```

--------------------------------

### GET /api/v2/ship/{orderId}

Source: https://ww2.eshipper.com/v2/api-docs/REST%20APIs

Fetches the details of a specific shipment using its order ID. This endpoint provides comprehensive information about a shipment.

```APIDOC
## GET /api/v2/ship/{orderId}

### Description
Fetch a shipment having a specified identifier.

### Method
GET

### Endpoint
/api/v2/ship/{orderId}

### Parameters
#### Path Parameters
- **orderId** (integer) - Required - The unique identifier for the shipment.

### Response
#### Success Response (200)
- **ShippingReply** - On successful retrieval of shipment details.

#### Error Response (401)
- **description**: Authentication failed - either authentication information is missing from the request, is invalid, or has expired. Please make sure to include an 'Authorization' header with the HTTP request, having its value set to 'Bearer [authentication token]' (without quotes), where [authentication token] refers to the token returned by the Sign-in API upon successful authentication. For instance, if the token returned by the Sign-in API is aAbBcCdDeEfFgGhHiIjJkKlLmMnNoOpPqQrRsStTuUvVwWxXyYzZ0123456, send the header as 'Authorization: Bearer aAbBcCdDeEfFgGhHiIjJkKlLmMnNoOpPqQrRsStTuUvVwWxXyYzZ0123456'. Please note that authentication can also fail if the authentication token has expired - do make sure to check the time of expiration included in the response from the Sign-in API. Alternatively, pass the username in request header X-API-KEY and password in request header X-API-SECRET.

#### Error Response (404)
- **description**: If no shipment matching the specified criteria is found.
```

--------------------------------

### Shipment Creation

Source: https://ww2.eshipper.com/v2/api-docs/REST%20APIs

This section details the parameters required to create a new shipment using the eShipper API.

```APIDOC
## POST /api/v2/shipments

### Description
This endpoint allows users to create a new shipment. It requires detailed information about the sender, recipient, package dimensions, weights, and any special services required.

### Method
POST

### Endpoint
/api/v2/shipments

### Parameters
#### Request Body
- **scheduledShipDate** (string) - Required - Date and time of dispatch for the shipment in yyyy-MM-dd HH:mm format.
- **from** (object) - Required - Sender's address details. See `ShipFromAddress` schema.
- **to** (object) - Required - Recipient's address details. See `ShipToAddress` schema.
- **packagingUnit** (string) - Required - Measurement system used for packages (Imperial or Metric).
- **packages** (array) - Required - An array of package details. See `Packages_APIv2UserView` schema.
- **reference1** (string) - Optional - Reference code for the shipment.
- **reference2** (string) - Optional - Second reference code for the shipment.
- **reference3** (string) - Optional - Third reference code for the shipment.
- **transactionId** (string) - Optional - Transaction or co-relation ID for the shipment.
- **billingReference** (string) - Optional - Billing identifier/reference to group shipments.
- **currency** (string) - Optional - Currency code for the shipment.
- **signatureRequired** (boolean) - Optional - Whether signature is required upon delivery.
- **insuranceType** (string) - Optional - Insurance provider (eShipper or Carrier).
- **dangerousGoodsType** (string) - Optional - Specifies if the shipment contains dangerous goods and their type.
- **pickup** (object) - Optional - Pickup request details. See `PickupRequest_APIv2UserView` schema.
- **customsInformation** (object) - Optional - Customs information for international shipments. See `CustomsInformation_APIv2UserView` schema.
- **customsInBondFreight** (boolean) - Optional - Indicates if freight is in bond for customs.
- **cod** (object) - Optional - Cash on Delivery details. See `Cod_APIv2UserView` schema.
- **isSaturdayService** (boolean) - Optional - Whether Saturday delivery service is requested.
- **holdForPickupRequired** (boolean) - Optional - Whether the shipment should be held for pickup by the recipient.
- **specialEquipment** (boolean) - Optional - Indicates if special equipment is required for handling.

### Request Example
```json
{
  "scheduledShipDate": "2023-10-27 14:30",
  "from": {
    "name": "Sender Name",
    "companyName": "Sender Company",
    "address1": "123 Sender St",
    "address2": "Suite 100",
    "city": "Sender City",
    "stateOrProvinceCode": "CA",
    "postalCode": "90210",
    "countryCode": "US",
    "phone": "123-456-7890",
    "email": "sender@example.com"
  },
  "to": {
    "name": "Recipient Name",
    "companyName": "Recipient Company",
    "address1": "456 Recipient Ave",
    "address2": null,
    "city": "Recipient City",
    "stateOrProvinceCode": "NY",
    "postalCode": "10001",
    "countryCode": "US",
    "phone": "987-654-3210",
    "email": "recipient@example.com"
  },
  "packagingUnit": "Imperial",
  "packages": [
    {
      "weight": 5,
      "weightUnit": "lb",
      "length": 10,
      "width": 8,
      "height": 6,
      "dimensionUnit": "in"
    }
  ],
  "reference1": "PO12345",
  "isSaturdayService": false,
  "signatureRequired": true
}
```

### Response
#### Success Response (200)
- **shipmentId** (string) - The unique identifier for the created shipment.
- **trackingNumber** (string) - The tracking number for the shipment.
- **status** (string) - The current status of the shipment.

#### Response Example
```json
{
  "shipmentId": "shp_12345abcde",
  "trackingNumber": "1Z999AA10123456784",
  "status": "Created"
}
```

```

--------------------------------

### GET /api/v2/track/tracking-number/{trackingNumber}

Source: https://ww2.eshipper.com/v2/api-docs/REST%20APIs

Fetches tracking information for a shipment using its master tracking number. This endpoint is part of the Tracking API.

```APIDOC
## GET /api/v2/track/tracking-number/{trackingNumber}

### Description
Fetch tracking information for a shipment having a specified master tracking number.

### Method
GET

### Endpoint
/api/v2/track/tracking-number/{trackingNumber}

### Parameters
#### Path Parameters
- **trackingNumber** (string) - Required - The master tracking number of the shipment.

### Request Example
```json
{
  "example": "Not applicable for GET request"
}
```

### Response
#### Success Response (200)
- **TrackingReply** (object) - Contains the tracking details for the shipment.

#### Error Response (404)
- **Response** (object) - Indicates that no shipment with the specified identifier was found or tracking information is unavailable.

#### Error Response (401)
- **Response** (object) - Authentication failed. Ensure an 'Authorization: Bearer [token]' header is included, or use 'X-API-KEY' and 'X-API-SECRET' headers. Check token expiration.

#### Response Example
```json
{
  "example": "{\"trackingNumber\": \"1Z999AA10123456789\", \"status\": \"In Transit\", \"history\": [{\"timestamp\": \"2023-10-27T10:00:00Z\", \"location\": \"Origin Facility\", \"description\": \"Package received by carrier\"}]}"
}
```
```

--------------------------------

### GET /api/v2/ship/{orderId}/order-details

Source: https://ww2.eshipper.com/v2/api-docs/REST%20APIs

Fetches the order details for a given shipping order as a PDF document. Requires a valid order ID.

```APIDOC
## GET /api/v2/ship/{orderId}/order-details

### Description
Fetches the order details for a given shipping order, typically as a PDF document. This endpoint is useful for obtaining comprehensive information about a specific shipment.

### Method
GET

### Endpoint
/api/v2/ship/{orderId}/order-details

### Parameters
#### Path Parameters
- **orderId** (integer) - Required - The unique identifier for the shipping order.

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **(string)** - The shipping order details, often in a string format representing a PDF document or a URL to it.

#### Response Example
```json
{
  "example": "PDF content or URL"
}
```

#### Error Response (401)
- **description**: Authentication failed. Ensure an 'Authorization' header with a valid 'Bearer [authentication token]' is included. Alternatively, use 'X-API-KEY' and 'X-API-SECRET' headers. Token may be expired.

#### Error Response (404)
- **description**: If no shipment matching the specified criteria is found.
```

--------------------------------

### Authentication API

Source: https://ww2.eshipper.com/v2/api-docs/REST%20APIs

This section details the authentication endpoint for the eShipper API. It supports authentication for both web users and API-only users.

```APIDOC
## POST /api/v2/auth/authenticate

### Description
Authenticates a user based on provided credentials. Returns a security token upon successful authentication.

### Method
POST

### Endpoint
/api/v2/auth/authenticate

### Parameters
#### Request Body
- **principal** (string) - Required - The username or API key.
- **credential** (string) - Required - The password or API secret.

### Request Example (JSON)
```json
{
  "principal": "AT1234567890",
  "credential": "aAbBcCdDeEfFgGhHiIjJkKlLmMnNoOpPqQrRsStTuUvVwWxXyYzZ0123456="
}
```

### Request Example (XML)
```xml
<AuthenticationRequest>
  <principal>AT1234567890</principal>
  <credential>aAbBcCdDeEfFgGhHiIjJkKlLmMnNoOpPqQrRsStTuUvVwWxXyYzZ0123456=</credential>
</AuthenticationRequest>
```

### Response
#### Success Response (200)
- **token** (string) - The security token for subsequent requests.

#### Response Example (JSON)
```json
{
  "token": "your_security_token_here"
}
```
```

--------------------------------

### GET /api/v2/returns/{orderId}

Source: https://ww2.eshipper.com/v2/api-docs/REST%20APIs

Fetches shipment details for a given order ID. Handles successful retrieval, cases where the shipment is not found, and authentication failures.

```APIDOC
## GET /api/v2/returns/{orderId}

### Description
Fetches the details of a return shipment using its unique order identifier.

### Method
GET

### Endpoint
/api/v2/returns/{orderId}

#### Path Parameters
- **orderId** (integer) - Required - The unique identifier of the order for which to retrieve return shipment details.

### Response
#### Success Response (200)
- **ShippingReply** (object) - Contains the details of the return shipment.

#### Error Response (404)
- **Response** (object) - Returned if no return shipment matching the specified criteria is found.

#### Error Response (401)
- **Response** (object) - Authentication failed. Include an 'Authorization' header with 'Bearer [authentication token]' or use 'X-API-KEY' and 'X-API-SECRET' headers.
```

--------------------------------

### Pickup Request Schema Definition

Source: https://ww2.eshipper.com/v2/api-docs/REST%20APIs

Defines the structure for a pickup request. Includes contact details, pickup date and time, location, and instructions. Pickup details are optional.

```json
{
  "required" : [ "contactName", "phoneNumber", "pickupDate" ],
  "type" : "object",
  "properties" : {
    "contactName" : {
      "type" : "string"
    },
    "phoneNumber" : {
      "type" : "string"
    },
    "pickupDate" : {
      "type" : "string",
      "format" : "date"
    },
    "pickupTime" : {
      "$ref" : "#/components/schemas/LocalTime"
    },
    "closingTime" : {
      "$ref" : "#/components/schemas/LocalTime"
    },
    "palletPickupTime" : {
      "$ref" : "#/components/schemas/LocalTime"
    },
    "palletClosingTime" : {
      "$ref" : "#/components/schemas/LocalTime"
    },
    "palletDeliveryClosingTime" : {
      "$ref" : "#/components/schemas/LocalTime"
    },
    "location" : {
      "type" : "string",
      "description" : "location of the pickup",
      "enum" : [ "Receiving", "Garage", "Lobby", "Reception", "FrontDesk", "Vault", "Switchboard", "BackDoor", "Desk", "BetweenDoors", "Kiosk", "Office", "OutsideDoor", "Mailbox", "SideDoor", "ServiceCounter", "Security", "Shipping", "FrontDoor", "Basement", "MailRoom", "Lab", "Warehouse", "Pharmacy", "ProShop", "PartsDepartment", "Counter", "LoadingDock", "GateHouse" ]
    },
    "instructions" : {
      "type" : "string",
      "description" : "Instructions if any"
    }
  },
  "description" : "Optional pickup details for the shipment. Please note that requesting pickup does not guarantee actual pick up by the carrier. Specify only if applicable, skip if not required for the current shipment."
}
```

--------------------------------

### GET /api/v2/ship/{orderId}/customs-invoice

Source: https://ww2.eshipper.com/v2/api-docs/REST%20APIs

Fetches the customs invoice for a given shipping order ID. This endpoint is useful for obtaining collateral documents related to a shipment.

```APIDOC
## GET /api/v2/ship/{orderId}/customs-invoice

### Description
Fetches the customs invoice for shipping order if applicable.

### Method
GET

### Endpoint
/api/v2/ship/{orderId}/customs-invoice

### Parameters
#### Path Parameters
- **orderId** (integer) - Required - The unique identifier for the shipping order.

### Response
#### Success Response (200)
- **string** - The customs invoice data.

#### Error Response (401)
- **description**: Authentication failed - either authentication information is missing from the request, is invalid, or has expired. Please make sure to include an 'Authorization' header with the HTTP request, having its value set to 'Bearer [authentication token]' (without quotes), where [authentication token] refers to the token returned by the Sign-in API upon successful authentication. For instance, if the token returned by the Sign-in API is aAbBcCdDeEfFgGhHiIjJkKlLmMnNoOpPqQrRsStTuUvVwWxXyYzZ0123456, send the header as 'Authorization: Bearer aAbBcCdDeEfFgGhHiIjJkKlLmMnNoOpPqQrRsStTuUvVwWxXyYzZ0123456'. Please note that authentication can also fail if the authentication token has expired - do make sure to check the time of expiration included in the response from the Sign-in API. Alternatively, pass the username in request header X-API-KEY and password in request header X-API-SECRET.

#### Error Response (404)
- **description**: If no shipment matching the specified criteria is found.
```

--------------------------------

### GET /api/v2/track/tracking-number/{carrier}/{trackingNumber}

Source: https://ww2.eshipper.com/v2/api-docs/REST%20APIs

Fetches tracking information for a shipment using its master tracking number and a specified carrier. This endpoint is part of the Tracking API.

```APIDOC
## GET /api/v2/track/tracking-number/{carrier}/{trackingNumber}

### Description
Fetch tracking information for a shipment having a specified master tracking number for a specified carrier.

### Method
GET

### Endpoint
/api/v2/track/tracking-number/{carrier}/{trackingNumber}

### Parameters
#### Path Parameters
- **carrier** (string) - Required - The carrier of the shipment.
- **trackingNumber** (string) - Required - The master tracking number of the shipment.

### Request Example
```json
{
  "example": "Not applicable for GET request"
}
```

### Response
#### Success Response (200)
- **TrackingReply** (object) - Contains the tracking details for the shipment.

#### Error Response (404)
- **Response** (object) - Indicates that no shipment with the specified identifier was found or tracking information is unavailable.

#### Error Response (401)
- **Response** (object) - Authentication failed. Ensure an 'Authorization: Bearer [token]' header is included, or use 'X-API-KEY' and 'X-API-SECRET' headers. Check token expiration.

#### Response Example
```json
{
  "example": "{\"trackingNumber\": \"1Z999AA10123456789\", \"carrier\": \"UPS\", \"status\": \"Delivered\", \"history\": [{\"timestamp\": \"2023-10-27T15:30:00Z\", \"location\": \"Destination City\", \"description\": \"Package delivered to recipient\"}]}"
}
```
```
Tokens:
Raw