---
title: "Customizing an EasyPost adapter"
slug: "customizing-an-easypost-adapter"
tags: ["Easypost", "integration", "shipping", "international shipping", "delivery", "platform", "routing", "api"]
updated: 2024-12-17T17:59:50Z
published: 2024-12-17T17:59:50Z
canonical: "docs.newstore.com/customizing-an-easypost-adapter"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.newstore.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Customizing an EasyPost adapter

If you work with multiple providers, NewStore Omnichannel Cloud offers integration capabilities with the [EasyPost](https://www.easypost.com/) adapter.

If EasyPost is set up with an adapter that uses the NewStore [shipping provider webhooks](https://docs.newstore.net/api/webhooks/delivery_hook) to provide shipping options for orders in your business, you can extend the adapter to customize shipment creation requests. This guide walks you through the ways to customize shipments via the EasyPost adapter.

For more information on the EasyPost adapter itself, or how to set up a shipping adapter, see [Integrating a shipping provider](/v1/docs/integrating-a-shipping-provider#integ-shipment).

EasyPost currently provides 2 options to customize a shipment request:

- [Additional static shipment options](/v1/docs/customizing-an-easypost-adapter#additional-static-shipment-options)
- [Shipment customization provider](/v1/docs/customizing-an-easypost-adapter#shipment-customization-provider)

## Additional static shipment options

EasyPost shipments contain an `options` property that you can use to define various parameters within the shipment object. For more information, see the [EasyPost specification for options](https://docs.easypost.com/docs/shipments/options).

You can also define static options for each shipping provider using the `shipment_creation_options` property in the [Create or update EasyPost shipping configuration](https://docs.newstore.net/private-api/delivery/easypost_adapter_hook#operation/create-or-update-easypost-shipping-configuration) method. When NewStore creates the shipment request, it is sent to EasyPost with the [schema](https://docs.newstore.net/private-api/delivery/easypost_adapter_hook#operation/create-or-update-easypost-shipping-configuration) for the shipping carrier configuration.

The EasyPost adapter overwrites the following properties in the configuration when receiving the shipping request from NewStore, during both the shipping estimation and booking phases:

- `print_custom_1`: Used to specify the ID of an external order.
- `print_customer_1_code`: Used to define the value in `print_custom_1` property, which is a static value `PO`, which means `Purchase Order`.

## Shipment customization provider

To customize and manage default shipping estimation and booking workflows, you can create an HTTP shipment customization provider (SCP) service.

This adds a customization layer between the EasyPost adapter and EasyPost itself, and the following data is sent to the customization endpoint:

- `request_type`: Can be one of `shipping_offers` or `shipment`. This property specifies if the request is to estimate shipping offers or to book a shipment via EasyPost.
- `request`: Original data received by the EasyPost adapter.
- `shipment_payload`: JSON payload prepared to create a shipment in EasyPost

The `customized_payload` expected as the response payload from the customization endpoint must match the format specified by the EasyPost API. For more information, see the [EasyPost documentation](https://docs.easypost.com/docs/shipments). To avoid creating a shipment for a specific request, the response payload must contain an empty `customized_payload` object.

### Creating a shipment customization provider

To create a shipment customization provider (SCP) HTTP service, implement the following methods:

- [Create shipping option](https://docs.newstore.net/private-api/delivery/easypost_adapter_hook#operation/create-shipping-option): Used to provide shipping estimates and offers
- [Book shipment](https://docs.newstore.net/private-api/delivery/easypost_adapter_hook#operation/book-shipment): Used to book the shipment

In the [EasyPost adapter configuration](https://docs.newstore.net/private-api/delivery/easypost_adapter_hook) API schema, the following properties impact the SCP web service:

- `base_customization_url` - The URL to call the SCP web service, which can be either:
  - `{base_customization_url}/shipping_options`
  - `{base_customization_url}/shipment`
- `ignore_customization_failure_on_booking` - Defines how the EasyPost adapter behaves if `/shipment` API call fails.

When estimating shipping offers, the `shipping_options` call failure is always ignored.
  - If set to `True`, when the call fails, the adapter considers that there is no customization adapter set up (with a shipment request created by the adapter itself).
  - If set to `False`, the adapter fails the entire delivery booking request with a `customization_error` error code.

#### Payloads

The following request payload format is expected by both methods:

```json
{
  "request":{},
  "shipment_payload": {}
}
```

In this payload, the `shipment_payload` property is the shipment creation JSON object. See the [EasyPost API docs](https://docs.easypost.com/docs/shipments#create-a-shipment). However, for the `request` property, the value changes based on the `base_customization_url`.

- `base_customization_url}/shipping_options`: The `request` property is the original `shipping options` request received by the EasyPost adapter (see the [Create shipping option](https://docs.newstore.net/private-api/delivery/easypost_adapter_hook#operation/create-shipping-option) schema).
- `base_customization_url}/shipment`: The `request` property is the original shipment booking request received by the EasyPost adapter (see the [API schema](https://docs.newstore.net/private-api/delivery/easypost_adapter_hook#operation/book-shipment)).

Both methods should return the following payload via a 2xx response:

```json
{
 "customized_payload": {}
}
```

In this payload, the `customized_payload` property is the EasyPost shipment creation object, see the [EasyPost API docs](https://www.easypost.com/docs/api#create-a-shipment).

#### Example

See this example of a customization adapter for EasyPost.

```python
import logging

from flask import Flask, request

app = Flask(__name__)

logger = logging.getLogger(__name__)

@app.route('/shipping_options', methods=['POST'])
def customize_shipping_options_call():
    original_request = request.json['request']
    payload = request.json['shipment_payload']
    customized_payload = payload.copy()
    price = sum(item['item']['price']['amount'] * item['quantity']
                for item in original_request['deliverables'])
    if price >= 100:
        customized_payload.setdefault('options', {})
        customized_payload['options']['delivery_confirmation'] = 'SIGNATURE'
    return {'customized_payload': customized_payload}, 200

@app.route('/shipment', methods=['POST'])
def customize_shipment_call():
    original_request = request.json['request']
    payload = request.json['shipment_payload']
    customized_payload = payload.copy()
    price = sum(item['price']['amount'] for item in original_request['items'])
    if price >= 100:
        customized_payload.setdefault('options', {})
        customized_payload['options']['delivery_confirmation'] = 'SIGNATURE'
    return {'customized_payload': customized_payload}, 200
```