# Custom Carrier Integration Guide

This guide walks you through the complete process of handling deliveries using your own carrier service, from purchase to final delivery.

## Overview

When using custom carrier integration, delivery preferences (such as pricing) are pre-configured on our platform (Contact your account manager).
The transaction flow remains similar to standard transactions, with specific differences in the shipping request acceptance and carrier management steps.

For more hands-on implementation guidance on the APIs mentioned in this document, check out the [Transactions APIs Catalog](/apis/delivery).

## High-level Overview


```mermaid
graph TD
    A[Buyer Pays for item] --> |Triggers shipping request| B[Seller Receives Request - Pending]
    B --> |Seller Accepts Request| C[Shipment Process Begins - Pending]
    C --> |Seller Register Shipment with Carrier| D[Transaction is Pending registration at our system]
    D --> |Seller Update Tracking Information at our system| E[Seller Monitor & Update Delivery Status]
    E --> F[Seller Monitor for disputes created]
```

## 1) Buyer Pays for Item

The process begins when a buyer clicks the "Pay" button, settling the cost of the item along with service and delivery fees. This triggers the creation of a shipping request. We then processes a pre-authorization charge to ensure everything is in order.

## 2) Receiving Shipping Requests

You will be notified immediately when any delivery request is created, if you're integerated already the `DELIVERY_REQUEST_STARTED` webhook

### Webhook Notification

You'll receive a `DELIVERY_REQUEST_STARTED` webhook when a new shipping request is created:


```json
{
  "id": "67b39f0e-eed5-42f6-bd9b-8adf406d9338",
  "type": "DELIVERY_REQUEST_STARTED",
  "occurred_on": 1752820579294,
  "data": {
    "request_id": "f18cfc83-7a27-4b99-a878-c891d688e84c"
  }
}
```

You can then retrieve the request details using:

Alternatively, you can query pending requests using:

## 3) Accepting Shipping Requests

Important
When using your own carrier, you can only use the home-pickup endpoint to accept requests.

After accepting the shipping request, the transaction is created. You can be notified immediately if you have integrated the `TRANSACTION_CREATED` webhook:


```json
{
  "id": "0ea14bd3-02a6-47f9-869a-f5ee6e9c4083",
  "type": "TRANSACTION_CREATED",
  "occurred_on": 1752820579294,
  "data": {
    "transaction_id": "f45d62e3-f476-4173-8a03-b4b2dfc7f0b2"
  }
}
```

You can then retrieve the transaction details, including all buyer information needed for registration, using:

Alternatively, you can pull all pending transactions using:

## 4) Update Tracking Information

After registering with your carrier, you must set the tracking information in our system:

Important
You must provide the `shipment_to_buyer` details for outbound shipments. If a dispute occurs and the item needs to be returned, use the same endpoint to provide `shipment_to_seller` details. Both shipment details can be included in a single API call if needed.

## 5) Status Updates During Delivery

You must keep our system synchronized by updating delivery status as the package progresses:

### Status Values

- `DELIVERED_TO_CARRIER`
- `IN_TRANSIT`
- `DELIVERED`
- `FAILED`
- `CANCELLED`


## Handling Disputes

### Dispute Notification

Monitor for dispute webhooks:


```json
{
  "id": "b808d275-24fd-4d64-9085-8bfe15a11b5b",
  "type": "DISPUTE_CREATED",
  "occurred_on": 1752820579294,
  "data": {
    "dispute_id": "6e1a8b78-5d41-4c35-8437-b48a9ae0b167"
  }
}
```

### Retrieve Dispute Details

### Additional Dispute Webhooks

You can stay informed about dispute status changes by integrating the following webhooks:

- `DISPUTE_QUALITY_CHECK_STARTED`
- `DISPUTE_QUALITY_CHECK_EXPIRED`
- `DISPUTE_QUALITY_CHECK_APPROVED_BY_SELLER`
- `DISPUTE_ISSUE_REPORTED_BY_SELLER`
- `DISPUTE_CANCELLED_BY_WALLAPOP`


Dispute Actions
Dispute actions (reporting issues, escalating, accepting) must be handled through our website or mobile app.