Custom Carrier Integration Guide

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude

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.

High-level Overview

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:

{
  "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:

curl -i -X GET \
  'https://connect.wallapop.com/transactions/requests/{requestId}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Alternatively, you can query pending requests using:

curl -i -X GET \
  https://connect.wallapop.com/transactions/requests/pending \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

3) Accepting Shipping Requests

curl -i -X POST \
  'https://connect.wallapop.com/transactions/requests/{requestId}/accept/home-pickup' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "transaction_id": "a1b2c3d4-e5f6-1234-5678-90abcdef1234"
  }'

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

{
  "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:

curl -i -X GET \
  'https://connect.wallapop.com/transactions/{transactionId}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Alternatively, you can pull all pending transactions using:

curl -i -X GET \
  https://connect.wallapop.com/transactions/pending \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

4) Update Tracking Information

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

curl -i -X POST \
  'https://connect.wallapop.com/transactions/{transactionId}/delivery/register' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "shipment_to_buyer": {
      "tracking_code": "string",
      "tracking_url": "string"
    },
    "shipment_to_seller": {
      "tracking_code": "string",
      "tracking_url": "string",
      "label_url": "string",
      "label_file_type": "PNG",
      "label_type": "BARCODE"
    }
  }'

5) Status Updates During Delivery

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

curl -i -X PATCH \
  'https://connect.wallapop.com/deliveries/{deliveryId}/status' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "DELIVERED_TO_CARRIER"
  }'

Status Values

• DELIVERED_TO_CARRIER
• IN_TRANSIT
• DELIVERED
• FAILED
• CANCELLED

Handling Disputes

Dispute Notification

Monitor for dispute webhooks:

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

Retrieve Dispute Details

curl -i -X GET \
  'https://connect.wallapop.com/disputes/{disputeId}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

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