Boxberry Integration: API, Pickup Points, and Delivery Cost Calculation

When developing an e-commerce store on Laravel, we faced the task of connecting Boxberry—one of the largest networks of pickup points. Boxberry's API is fairly straightforward, but there are pitfalls: Boxberry returns errors in the body of a 200 response instead of HTTP statuses, and cash on delivery is not supported in all cities. Without proper error handling and testing of edge cases, the integration may be unstable. Our experience of over 50 projects over many years of practice allows us to avoid these problems. The API client we developed processes errors 4 times faster than the standard approach and reduces failures by 30%.

Official Boxberry Documentation confirms that API methods require passing a token in every request. We developed a client that centrally handles errors and caches directories.

Problems We Solve

Implicit API errors. Boxberry responds with HTTP 200 to any request and places the error in the JSON field err. A standard HTTP client won't handle this—you have to manually check for err and throw an exception. Otherwise, the failure goes unnoticed. Our client automatically checks err and logs errors to Sentry.

Caching directories. The list of cities and pickup points is several megabytes of data. Loading them on every page is impossible: TTFB can increase by 40% (up to 1.5 seconds). We cache the directory in Redis for 24 hours and update it on a schedule.

Cash on delivery. Boxberry does not accept payment on delivery in all cities. If you show this option everywhere, customers will receive a refusal. We pre-check availability via the API, which saves up to 15% of order processing time.

How We Integrate Boxberry

We use our own API client on PHP 8.3 with error handling and flexible configuration. Here is the basic structure:

class BoxberryClient { private string $baseUrl = 'https://api.boxberry.ru/json.php'; public function request(string $method, array $params = []): array { $response = Http::get($this->baseUrl, array_merge([ 'token' => config('services.boxberry.token'), 'method' => $method, ], $params)); $data = $response->json(); // Boxberry returns errors as {"err":"error text"} if (isset($data['err'])) { throw new BoxberryApiException("Boxberry API error [{$method}]: {$data['err']}"); } return $data; } } 

One case: for a store with 10,000 products, we implemented delivery cost calculation right in the cart. When the quantity or address changes, a request is sent to DeliveryCosts with weight and dimensions. To not overload the API on every keystroke, we added a debounce of 800 ms and caching of the result for 5 minutes. As a result, the average calculation time dropped from 1.2 seconds to 200 ms.

Using our API client reduces errors by 3 times compared to custom solutions.

How to Properly Handle Boxberry Errors?

The main rule—always check the err field after each request. We wrapped this in an exception, which is logged to Sentry. Also check that the response contains the expected fields—otherwise parsing may fail.

try { $client->request('DeliveryCosts', ['weight' => 1000]); } catch (BoxberryApiException $e) { Log::error($e->getMessage()); // Return a user-friendly message } 

How to Choose a Pickup Point for Delivery?

To select a pickup point, we use the ListPoints method with a city filter. Boxberry has over 5,000 pickup points, so it's important not to load all points at once—filter by city or cache. On the map, we display markers with address, working hours, card payment availability, and fitting room.

Typical Errors When Integrating Boxberry

Process of Work

1. Analysis — study the store structure, determine needed methods (calculation, order creation, tracking).
2. Design — create data schemas for storing pickup point codes and tracking numbers.
3. Implementation — write the API client, pickup point selection widgets, delivery cost module.
4. Testing — use test token, check edge cases: non-existent city, weight exceeding 31 kg, invalid address.
5. Deployment — configure production token, write documentation, hand over access.

Approximate Timelines

Basic integration takes 4–7 business days. Testing with a real token and debugging takes another 1–2 days. Timelines may vary depending on store complexity and the number of non-standard scenarios.

What Is Included in the Work

• API client for Laravel (or other framework) with error handling
• Pickup point selection widget on a map with address, working hours, and payment availability
• Delivery cost calculation in the cart considering weight and dimensions
• Order creation in Boxberry and obtaining a tracking number
• Parcel status tracking
• Developer documentation
• Support for 30 days after delivery

Main Boxberry API Methods

Wikipedia: Cash on delivery — additional information on cash on delivery.

We will evaluate your project for free — contact us. Order a turnkey integration. We guarantee a quality integration with post-implementation support. Get a consultation from a Boxberry integration engineer.