Shipping Events

These events handle shipping method changes, selection, and label customization. All shipping events are checkout only.

shipping:update

Checkout only. Dispatched by checkout when the shipping method changes.

Example

import type { NubeSDK } from "@tiendanube/nube-sdk-types";

export function App(nube: NubeSDK) {
  nube.on("shipping:update", ({ shipping }) => {
    if (shipping?.selected) {
      console.log(
        "Shipping method selected has changed to:",
        shipping.selected,
      );
    }
  });
}

shipping:select

Checkout only. Dispatched by app to change checkout shipping option.

Example

import type { NubeSDK } from "@tiendanube/nube-sdk-types";

export function App(nube: NubeSDK) {
  nube.send("shipping:select", () => ({
    shipping: {
      selected: "OPTION_ID",
    },
  }));

  nube.on("shipping:select:success", ({ shipping }) => {
    console.log("Selected option", shipping?.selected);
  });

  nube.on("shipping:select:fail", (state) => {
    console.log("Failed to select shipping option", state.shipping?.selected);
  });
}

shipping:select:success

Dispatched by checkout when a shipping option is selected successfully. The listener receives the updated state; state.shipping.selected contains the selected option id.

shipping:select:fail

Dispatched by checkout when selecting a shipping option fails. The listener receives the current state.

shipping:update:label

Checkout only. Dispatched by app to change checkout shipping method label.

The custom_labels property accepts a Record<string, CustomLabel> where each value can be either:

• A simple string for a basic label
• An object with optional title and description properties for more detailed labeling

nota

When using the object format, setting description to null will hide the description information in the Checkout.

Example with string labels

import type { NubeSDK } from "@tiendanube/nube-sdk-types";

export function App(nube: NubeSDK) {
  nube.send("shipping:update:label", () => ({
    shipping: {
      selected: null,
      custom_labels: {
        "ne-correios-sedex": "My custom label",
      },
      options: [],
    },
  }));
}

Example with object labels

import type { NubeSDK } from "@tiendanube/nube-sdk-types";

export function App(nube: NubeSDK) {
  nube.send("shipping:update:label", () => ({
    shipping: {
      selected: null,
      custom_labels: {
        "ne-correios-sedex": {
          title: "Express Delivery",
          description: "Arrives in 2-3 business days",
        },
        "ne-correios-pac": "Standard Shipping",
      },
      options: [],
    },
  }));
}