NitroMule

Labels embed

Updated 2026-09-22

On this page

The Labels embed puts NitroMule Get Label — rates, buy, print, tracking, refunds, address book, and bulk — inside your product. Mint a 12-hour JWT from an Integrations API key, load embeddable-client.js, then call nitromule.init and nitromule.purchaseLabels.

Features

Capability Support
Create / buy labels Yes — Get Label + checkout in iframe
Package dims / weight Yes
Multi-carrier rates Yes
Tracking Yes — in widget + LABEL_PURCHASED_SUCCESS
Label refund / void Yes — in-widget refund with acknowledgment
Address book Yes — merchant saved addresses
Label + packing slip print/download Yes
Bulk print-all labels Yes — after purchase when ≥2 labels
Billing / invoices + printing settings Yes (hidden when white-label)
Bulk (≤50) Yes — array or varargs (purchaseLabels(sel, a, b))
Theme Yes — colors, buttons, cards, inputs, menu, header/footer
Locales Yes — en, en-GB, en-au, ru, de, fr, tr, it, es, pl, uk, nl
White-label hide branding Yes — theme.hideBranding or style: "white-label"
Reopen via order_id Yes — incomplete continues; purchased shows detail panel
JWT auth (12h) + updateToken Yes — Authorization: Bearer
Scope embedded:labels Yes
Insurance / signature / ship date prefills Yes
COUNTRY_NOT_SUPPORTED / LOCALE_NOT_SUPPORTED Yes (US addresses today)

When to use

  • Marketplace / OMS / WMS that needs in-product label buy for a NitroMule merchant
  • Prefill destination + line items from your order object
  • Receive tracking and label URLs via LABEL_PURCHASED_SUCCESS

When not to use

  • Public marketing rate quotes → quote embed
  • Server-only automation → Integrations API
  • Putting nm_live_ / nm_test_ secrets in the browser (never)

Auth

curl -sS -X POST 'https://nitromule.com/api/integrations/v1/embedded/authz' \
  -H 'Authorization: Bearer nm_test_….SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"scope":"embedded:labels"}'

Response: { "token": "<jwt>", "expires_in": <unix>, "scope": "embedded:labels" }. Refresh before expiry with nitromule.updateToken(newJwt). Requires shipments:write or full on the API key.

Install SDK

<script src="https://nitromule.com/js/embeddable-client.js"></script>
<div id="nitromuleWidget"></div>
<script>
  nitromule.init({
    token: jwtFromYourServer,
    org: "your-org",
    locale: "en-US",
    theme: {
      width: "100%",
      primaryColor: "#0066cc",
      hideBranding: false,
      button: { primary: { borderRadius: "8px" } }
    }
  });
  nitromule.on("LABEL_PURCHASED_SUCCESS", (txns) => {
    // persist tracking_number, label_url, packing_slip_url, order_id
  });
  nitromule.on("ERROR", (err) => {
    // UNAUTHORIZED | LABEL_PURCHASE_ERROR | LOCALE_NOT_SUPPORTED | COUNTRY_NOT_SUPPORTED | UNKNOWN
  });
  nitromule.purchaseLabels("#nitromuleWidget", {
    address_to: {
      name: "Ada Lovelace",
      street1: "123 Main St",
      city: "Denver",
      state: "CO",
      zip: "80202",
      country: "US",
      phone: "3035550100",
      email: "ada@example.com"
    },
    line_items: [
      {
        title: "Book",
        quantity: 1,
        currency: "USD",
        unit_amount: "20",
        unit_weight: "1",
        weight_unit: "lb",
        country_of_origin: "US"
      }
    ],
    order_number: "1001"
  });
</script>

SDK methods

Method Purpose
init({ token, org, locale?, theme?, baseUrl? }) Configure once per page
purchaseLabels(selector, order|orders[]|…orders) Open widget (bulk ≤50; array or varargs)
updateToken(jwt) Refresh before 12h expiry
setTheme(theme) / setLocale(locale) Live updates
on / off / onAny Events
close() Tear down iframe

Order payload

Required: address_to, line_items. Optional: address_from, address_return, order_id (NitroMule order id to reopen), order_number, notes, shipment_date, extras.insurance, extras.signature_confirmation. Address fields include street1–street3, street_no, and country (US supported today; other ISO codes emit COUNTRY_NOT_SUPPORTED).

Pass an array (max 50) or varargs for bulk: purchaseLabels('#w', orderA, orderB).

Events

Event Meaning
APP_READY Widget ready (features list in payload)
ORDER_CREATED Draft / existing order id available
ORDERS_CREATED Bulk order list acknowledged
ORDERS_CREATED_ERROR Bulk open failed
LABEL_PURCHASED_SUCCESS Array of transaction objects
CLOSE_BUTTON_CLICKED User closed the widget
ERROR See codes below

ERROR codes

UNAUTHORIZED · LABEL_PURCHASE_ERROR · COUNTRY_NOT_SUPPORTED · LOCALE_NOT_SUPPORTED · UNKNOWN

Theme

width, height, primaryColor, title, style, hideBranding, container, header, footer, button.primary|secondary, cards, inputs, menu.

Persist sessions

  1. On ORDER_CREATED / purchase, save NitroMule order_id on your order.
  2. Next open: pass order_id in the order payload.
  3. Incomplete orders resume Get Label; purchased orders open tracking / download / refund.

Related articles