> ## Documentation Index
> Fetch the complete documentation index at: https://urbnbox.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Shopify

> Connect Shopify to UrbnBox without copying API tokens or configuring callbacks by hand.

UrbnBox provides a managed Shopify connection for merchants that want UrbnBox
rates at checkout and automatic shipment creation after payment.

You connect the store from the UrbnBox vendor workspace. UrbnBox handles the
Shopify authorization flow and configures the required Shopify resources.

## Before you connect

You need:

* A Shopify store and its permanent `*.myshopify.com` domain.
* An UrbnBox workspace with developer tools enabled.
* Workspace owner or admin access.
* The city that orders dispatch from.

Your Shopify plan must support third-party carrier-calculated shipping for
UrbnBox rates to appear at checkout.

## Connect your store

**1. Open Integrations**

Sign in to UrbnBox and open **Integrations**.

**2. Enter your Shopify store**

In the **Shopify** card, enter your `*.myshopify.com` domain and dispatch city.

**3. Approve UrbnBox**

Click **Connect Shopify**. UrbnBox redirects you to Shopify to approve the
requested permissions.

**4. Return to UrbnBox**

After approval, Shopify redirects you back to UrbnBox. The integration page
shows the store as **Connected**.

You do not need to create a Shopify custom app, copy an Admin API token, or
register callback URLs manually.

## What UrbnBox configures

During installation, UrbnBox automatically:

1. Registers **UrbnBox Locker Delivery** as a Shopify carrier service.
2. Subscribes to Shopify's paid-order event.
3. Subscribes to the app-uninstalled event so credentials are removed when the
   merchant uninstalls UrbnBox.
4. Stores the store domain and dispatch city against the UrbnBox partner workspace.

The Shopify app requests `read_orders` and `write_shipping`.

## Checkout rates

Shopify calls:

```text theme={null}
POST https://portal.urbnbox.io/integrations/shopify/carrier-rates
```

UrbnBox validates the signed carrier callback URL created during installation and returns
`urbnbox_locker` when the destination can be served. Prices are returned in
minor currency units as required by Shopify.

If the route cannot be served, UrbnBox returns an empty `rates` array.

## Paid orders

When an order that selected UrbnBox is paid, Shopify calls:

```text theme={null}
POST https://portal.urbnbox.io/integrations/shopify/orders-paid
```

UrbnBox validates the webhook, resolves the connected store, uses the workspace
dispatch city as the origin, and creates the shipment.

Paid-order processing is idempotent. Shopify retries do not create duplicate
shipments.

## Weight tiers

UrbnBox derives the shipment tier from the total line-item weight.

| Total weight | Tier |
| - | - |
| Less than 5 kg | `light` |
| 5 kg to less than 20 kg | `medium` |
| 20 kg or more | `heavy` |

## Disconnect

In **Integrations → Shopify**, click **Disconnect Shopify**.

UrbnBox removes the connection and attempts to remove its carrier service from
Shopify. Uninstalling the app from Shopify also removes the stored UrbnBox
connection.

## Security

UrbnBox validates Shopify OAuth callbacks and webhook signatures before
processing them. Carrier-rate callbacks use an unguessable, signed URL token
bound to the UrbnBox partner that installed the carrier service. OAuth state is short-lived and bound to the UrbnBox partner
that initiated the connection.

Shopify access and refresh tokens are encrypted at rest and are never displayed
in the UrbnBox dashboard.

> [!NOTE]
>
> If you run a custom storefront, marketplace, mobile backend, or another
> ecommerce platform, you do not need to emulate Shopify. Use the
> [Partner API](https://urbnbox.mintlify.site/guides/pickup-point-shipments.md) or [Vendor API](https://urbnbox.mintlify.site/reference-overview.md) directly.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.