# OSM Worldwide v2 Guide

OSM Worldwide v2 is a shipping solution that integrates with the EasyPost API, supporting both domestic and international shipments. OSM partners
with USPS for last-mile delivery on all domestic shipments and utilizes additional partners for middle and last-mile transportation.

This guide provides detailed information on utilizing OSM v2 shipping with the EasyPost API, focusing on account setup, rates, label
creation, tracking, and more.

---

## Carrier Account Setup

### Account Registration

Sign up for an EasyPost account to obtain a **Test** and **Production** API
key. See Authentication and Key Management for more information.

> Note: Negotiated rates are only available in Production mode.

Please review the Getting Started Guide for more information.

### OSM v2 Shipper Account Registration

1. Complete registration on the OSM website. Once registered, an OSM representative will be in touch for additional details regarding the account.
2. Inform OSM about using EasyPost's API for label purchases.
3. Obtain the following account credentials from OSM:

   1. `client_id`
   2. `api_key`
   3. `rate_key`
   4. `mailer_id`

4. Input carrier-specific credentials within the
   EasyPost Carrier Account Dashboard for comprehensive rate access.

### OSM v2 Account via API

The API structure specified by EasyPost can also be used to add the OSM v2 carrier account.

```shell
curl -X POST https://api.easypost.com/v2/carrier_accounts \
  -u "$EASYPOST_API_KEY": \
  -H 'Content-Type: application/json' \
  -d '{
  "carrier_account": {
    "type": "OsmWorldwideV2Account",
    "description": "OsmWorldwideV2Account",
    "credentials": {
      "api_key": "VALUE",
      "client_id": "VALUE",
      "mailer_id": "VALUE",
      "rate_key": "VALUE"
    }
  }
}'
```

### Software Requirements

Download an EasyPost Client Library or utilize the REST API with cURL.

### Documentation Review

Examine the EasyPost Objects section to understand the API's structure, which is critical for constructing requests and interpreting responses.

Related:

- [Getting Started Guide](https://docs.easypost.com/guides/getting-started)
- [Manage Carrier Accounts](https://app.easypost.com/account/settings?tab=carriers)

---

## Rates

OSM v2 is a **Live Rating** integration, enabling real-time rate retrieval for shipments created via EasyPost.

- When creating a shipment, EasyPost requests OSM for shipment rates specific to the user's OSM account.
- The rates provided are directly from OSM and tailored to the user's specific account details.
- In cases of discrepancies or incorrect rates, users are advised to contact their OSM account representative.

---

## Billing

Billing is handled directly by OSM and follows a **bill-on-scan** model.

- Charges are applied when the shipment is scanned into the OSM network, not at the time of label creation.
- EasyPost is not involved in the billing process.
- All invoices, adjustments, and billing inquiries are managed through OSM.

---

## Service Levels

OSM delivers six days per week (Mon-Sat). The service levels through EasyPost include:

- `PRIORITY_MAIL`
- `GROUND_ADVANTAGE`
- `PARCEL_SELECT`
- `PARCEL_SELECT_LIGHTWEIGHT`
- `BPM`
- `MARKETING_PARCEL`
- `MEDIA_MAIL`

### Coverage

OSM v2 covers shipments in the United States and United States territories.

Related:

- [OSM Service Levels](https://docs.easypost.com/docs/shipments/rates?carrier=OSMWorldwide#service-levels)

---

## Predefined Packages

OSM has a few predefined packages supported by EasyPost. Predefined packages are an easy way to classify and price a package.

- Types: `softpack`
- Usage: Specify in EasyPost API request for rate retrieval.

Related:

- [Predefined Packages](https://docs.easypost.com/docs/parcels#predefined-packages)

---

## Generating Shipping Labels

With EasyPost, the process for generating shipping labels for OSM v2 is the same as generating them for any other carrier.

Review the Getting Started Guide for help generating a shipping label.

### 1-Call Buys

1-call buys enable streamlined label purchasing through the EasyPost API by consolidating multiple operations into a single API request.
This feature is designed to simplify and accelerate the shipping process by combining the creation of a shipment, retrieval of rates,
and purchasing the shipping label into one efficient step.

See Reducing API Response Times for more information.

### Manifests

Manifesting is not supported or required.

### Voiding Labels

Voiding labels is not supported at this time.

### Supported Options

#### Label Formats

EasPost offers shipping labels in ZPL, PNG, and PDF formats.

#### Label Sizes

OSM supports a 4 x 6 label size.

Related:

- [Shipment Documentation](https://docs.easypost.com/docs/shipments)
- [Reducing API Response Times](https://support.easypost.com/hc/en-us/articles/360048825772-Reducing-API-Response-Times)

---

## Hazardous Materials (HAZMAT)

For safety reasons, most hazardous materials are non-mailable. However, some hazardous materials and otherwise restricted matter, or perishable
matter are permitted to be mailed when the requirements of the USPS are met.

OSM Worldwide follows USPS guidelines for shipping hazardous materials. For a list of items and definitions of other terms that relate to
hazardous materials, refer to the USPS Hazardous Materials Guidelines.

See the EasyPost USPS Guide for detailed information on shipping restrictions, labeling requirements, transportation, and more.

Related:

- [EasyPost USPS Guide](https://docs.easypost.com/carriers/usps-guide)
- [OSM Hazardous Material Shipping](https://www.osmworldwide.com/hazardousmaterial/)

---

## Pickups

OSM Worldwide accommodates pickups based on individual agreements with customers. While regular pickups can be arranged directly
with OSM during the account registration process, they **cannot be scheduled via the EasyPost API**.

---

## Tracking

EasyPost simplifies package tracking by offering two methods:

- Tracking with an existing number and carrier.
- Using a Tracker included with an EasyPost-purchased shipping label.

The service integrates webhooks for timely shipment updates. For detailed information on tracking methods, visit the Tracking Guide.

Related:

- [Trackers Documentation](https://docs.easypost.com/docs/trackers)
- [Trackers Guide](https://docs.easypost.com/guides/tracking-guide)

---

## Additional Resources

### Carrier Metadata

The Carrier Metadata endpoint can programmatically return information about OSM service levels, predefined packages, supported features, and shipment options.

Use this information to quickly integrate with OSM and make educated decisions about the mix of carriers for shipping needs. Additionally, the Carrier Metadata endpoint is available to retrieve comprehensive information about all carriers on the EasyPost platform, enhancing decision-making for carrier services.

### Support and Troubleshooting

In addition to the guidance provided in our Carrier Guides, EasyPost offers support to assist with FAQs, troubleshooting issues, and inquiries related to the EasyPost platform.

Please visit the Help Center for more information.

Related:

- [Carrier Metadata](https://docs.easypost.com/docs/carrier-metadata)
- [Help Center](https://support.easypost.com/hc/en-us)

---

## Talk to a Shipping Expert

For questions about getting started with OSM through the EasyPost API please talk to a Shipping Expert or Contact Support.

Related:

- [Talk to a Shipping Expert](https://www.easypost.com/talk-to-easypost)
- [Contact Support](https://support.easypost.com/hc/requests/new)