How to Book with Receiver Pays

This guide walks you through booking a 'Receiver Pays' shipment using the Sendify API. With this method, the freight cost is billed directly to the recipient's carrier account. We assume you have already completed our Getting Started guide and are familiar with the core concepts of the Sendify API.

Prerequisites#

1. Complete the Getting Started guide – you need a valid x-api-key.
2. You have the receiver's carrier account number and the corresponding carrier identifier (referred to as carrier in the API).

1. Understanding Receiver Pays#

"Receiver Pays" means the recipient of the shipment, not the sender, will be invoiced for the shipping costs, using their existing account with a specific carrier. To enable this, you need to provide the receiver's carrier account details when creating or updating the shipment, and then specifically request rates that support this payment method.

2. Specify Receiver's Carrier Account#

When creating a shipment (POST /shipments), you must add the receiver's carrier account information to the to.carrier_accounts array within the request body.

Each object in the carrier_accounts array should contain:

• carrier: The identifier for the carrier (e.g., dhl_freight_sweden, ups). This is referred to as carrier in the API schema.
• account_identifier: The receiver's account number with that carrier.

You can supply multiple account numbers if the receiver has accounts with different carriers, though typically only one will be used per booking.

Fetching Valid Carrier Identifiers: To get a list of all valid carrier values, you can use the GET /carriers endpoint.

Example: GET /carriers

curl --location --request GET 'https://app.dev.sendify.se/external/v1/carriers' \
--header 'x-api-key: $YOUR_API_KEY'

Example Response Snippet for /carriers:

{
  "carriers": [
    {
      "carrier": "dhl_freight_sweden",
      "name": "DHL Freight"
    },
    {
      "carrier": "ups_sweden",
      "name": "UPS"
    }
  ]
}

Including Carrier Account During Shipment Creation: When creating your shipment using POST /shipments, ensure the to.carrier_accounts array is included directly in the request body with the receiver's carrier and account identifier. This information should be part of the initial shipment creation before you request rates.

Example: POST /shipments request including carrier_accounts:

curl --location 'https://app.dev.sendify.se/external/v1/shipments' \
--header 'x-api-key: $YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "enable_bookable_validation": true,
    "from": {
        "name": "Sendify AB",
        "address": {
            "address_line_1": "Östra Larmgatan 16",
            "country_code": "SE",
            "postal_code": "41107",
            "city": "Göteborg"
        },
        "contact": {
            "name": "Support Agent",
            "phone": "0103303091",
            "email": "contact@sendify.se"
        }
    },
    "to": {
        "name": "Sendify GmbH",
        "address": {
            "address_line_1": "Pontus Wiknersgatan 1",
            "country_code": "SE",
            "postal_code": "41132",
            "city": "Göteborg"
        },
        "contact": {
            "name": "Holger",
            "phone": "0707112233",
            "email": "holger@sendify.se"
        },
        "is_private_individual": false,
        "carrier_accounts": [
            {
                "carrier": "dhl_freight_sweden",
                "account_identifier": "123456"
            }
        ]
    },
    "reference_id": "Sendify Shipment",
    "packages": [
        {
            "depth_cm": 20,
            "height_cm": 20,
            "width_cm": 20,
            "weight_kg": 2,
            "quantity": 1,
            "description": "Swedish Fika",
            "type": "PACKAGE",
            "stackable": true
        }
    ],
    "system": "Sendify"
}'

Include this to object structure in your POST /shipments call. Ensure you receive a shipment_id in response.

3. Requesting Receiver Pays Rates#

Once the shipment is created (or updated) with the receiver's carrier account details, you need to specifically ask for rates that support receiver pays.

In your POST /shipments/rates request, include the required_addons object and set receiver_pays: true.

Example: POST /shipments/rates for Receiver Pays

curl --location --request POST 'https://app.dev.sendify.se/external/v1/shipments/rates' \
--header 'x-api-key: $YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "shipment_id": "YOUR_SHIPMENT_ID",
    "requested_pickup_time": "2025-08-15T10:00:00+02:00",
    "required_addons": {
        "receiver_pays": true
    }
}'

The API will then filter the rates and only return those where:

1. The carrier supports receiver pays.
2. The provided receiver's account number (from Step 2) is valid for the carrier of the rate.

Example Rate Response Snippet for Receiver Pays:

{
  "rates": [
    {
      "price_rank": 1,
      "shipment_id": "YOUR_SHIPMENT_ID",
      "booking_token": "BOOKING_TOKEN",
      "carrier_name": "UPS",
      "product_name": "UPS Standard - Receiver Pays",
      "price": "-", // Price will be "-"
      "currency": "SEK",
      "receiver_pays": true // This flag confirms it's a receiver pays rate
    }
  ],
  "warnings": [] // Carriers excluded due to field validation issues, if any
}

Note the receiver_pays: true flag in the response. Save the booking_token for the rate you wish to use.

4. Booking the Shipment#

After selecting a suitable receiver pays rate and obtaining its booking_token, you can book the shipment as usual using the POST /shipments/book endpoint.

Example: POST /shipments/book

curl --location --request POST 'https://app.dev.sendify.se/external/v1/shipments/book' \
--header 'x-api-key: $YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "booking_token": "BOOKING_TOKEN"
}'

Example Booking Response:

{
  "shipment_id": "YOUR_SHIPMENT_ID",
  "main_tracking_id": "CARRIER_TRACKING_ID_EXAMPLE"
}

This confirms the booking. The carrier will invoice the receiver directly using the account number provided.

5. Quick Recap#

1. Gather Information: Obtain the receiver's carrier account number and the corresponding carrier identifier. You can fetch valid carrier identifiers via GET /carriers.
2. Create Shipment: In your POST /shipments request, include the carrier and account_identifier in the to.carrier_accounts array.
3. Request Rates: Call POST /shipments/rates for your shipment_id. In the request body, include required_addons: { "receiver_pays": true }.
   • Identify a rate with receiver_pays: true in the response.
   • Save the booking_token for this rate.
4. Book Shipment: Call POST /shipments/book with the saved booking_token.
5. Done! The shipment is booked, and the receiver will be billed by the carrier.