Asynchronous operations

Some requests cannot finish immediately, because OneBasket has to call a provider system to complete them. Adding a product to a basket is an example. OneBasket has to add the product to the basket in the provider's system and wait for the provider to respond.

These requests return straight away with a notificationId:

{ "notificationId": "..." }

You then poll the Notifications API with that id to learn the outcome.

Notification status

GET /notifications/{notificationId} returns a notification:

{
  "status": "complete",
  "payload": { }
}

Which requests are asynchronous

An endpoint is asynchronous when its response schema in the API reference is NotificationResponse or AcceptedNotificationResponse.

In the Baskets API, every request that changes a basket is asynchronous. Only Create a basket, Get a basket and Delete a basket return the basket directly.

Check the status code of each response, because some endpoints have both a synchronous and an asynchronous response.

Polling example

type Notification = {
  status: 'pending' | 'complete' | 'failed';
  payload?: Record<string, unknown>;
};

export async function waitForNotification(
  notificationId: string,
  { intervalMs = 500, timeoutMs = 30_000 } = {},
): Promise<Notification> {
  const deadline = Date.now() + timeoutMs;

  while (Date.now() < deadline) {
    const response = await fetch(
      `${process.env.ONEBASKET_API_URL}/notifications/${notificationId}`,
      { headers: { 'x-api-key': process.env.ONEBASKET_API_KEY! } },
    );
    if (!response.ok) throw new Error(`Notification request failed: ${response.status}`);

    const notification = (await response.json()) as Notification;
    if (notification.status !== 'pending') return notification;

    await new Promise((resolve) => setTimeout(resolve, intervalMs));
  }

  throw new Error(`Notification ${notificationId} was still pending after ${timeoutMs} ms`);
}

Recommendations:

• Poll no more often than twice per second.
• Always set a timeout, and show the customer a retry option when it is reached.
• Disable the control that started the request until the notification is no longer pending. This stops the customer from sending the same change twice.