# Shopify Admin Split Shipment Planner

> Splits a multi-line fulfillment order into separate shipments for partial or location-specific shipping.

- **Type:** Skill
- **Install:** `agentstack add skill-40rty-ai-shopify-admin-skills-shopify-admin-split-shipment-planner`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [40RTY-ai](https://agentstack.voostack.com/s/40rty-ai)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [40RTY-ai](https://github.com/40RTY-ai)
- **Source:** https://github.com/40RTY-ai/shopify-admin-skills/tree/main/skills/fulfillment-ops/shopify-admin-split-shipment-planner
- **Website:** http://skills.40rty.ai

## Install

```sh
agentstack add skill-40rty-ai-shopify-admin-skills-shopify-admin-split-shipment-planner
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

## Purpose
Splits a fulfillment order containing multiple line items into two or more separate fulfillment orders, each of which can be shipped independently with its own tracking number. Used when items in an order ship from different locations, on different dates, or require different carriers. Replaces manual split-shipment handling in Shopify Admin.

## Prerequisites
- Authenticated Shopify CLI session: `shopify store auth --store  --scopes read_orders,write_fulfillments`
- API scopes: `read_orders`, `write_fulfillments`
- Target fulfillment order must be in `OPEN` status

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| store | string | yes | — | Store domain (e.g., mystore.myshopify.com) |
| fulfillment_order_id | string | yes | — | GID of the fulfillment order to split |
| split_groups | array | yes | — | List of `{line_item_ids: [], quantities: []}` defining each shipment group |
| dry_run | bool | no | true | Preview split without executing mutation |
| format | string | no | human | Output format: `human` or `json` |

## Safety

> ⚠️ `fulfillmentOrderSplit` is irreversible — a split fulfillment order cannot be merged back. The original fulfillment order is replaced by multiple new ones. Run with `dry_run: true` to confirm the intended groupings before committing. Ensure all `line_item_ids` in `split_groups` belong to the target fulfillment order.

## Workflow Steps

1. **OPERATION:** `fulfillmentOrders` — query
   **Inputs:** Query for the specific fulfillment order by order ID, filter by `status: OPEN`
   **Expected output:** Fulfillment order with all `lineItems { id, remainingQuantity, variant { sku, title } }`

2. Validate `split_groups` — confirm all line item IDs exist in the fulfillment order and quantities are ≤ remaining quantities

3. **OPERATION:** `fulfillmentOrderSplit` — mutation
   **Inputs:** `fulfillmentOrderId`, `fulfillmentOrderLineItems` array per split group
   **Expected output:** Array of new `fulfillmentOrders { id, lineItems }`, `userErrors`

## GraphQL Operations

```graphql
# fulfillmentOrders:query — validated against api_version 2025-01
query FulfillmentOrderLines($orderId: ID!) {
  order(id: $orderId) {
    id
    name
    fulfillmentOrders(first: 10) {
      edges {
        node {
          id
          status
          lineItems(first: 50) {
            edges {
              node {
                id
                remainingQuantity
                totalQuantity
                variant {
                  id
                  sku
                  title
                }
              }
            }
          }
        }
      }
    }
  }
}
```

```graphql
# fulfillmentOrderSplit:mutation — validated against api_version 2025-01
mutation FulfillmentOrderSplit($fulfillmentOrderId: ID!, $fulfillmentOrderLineItems: [FulfillmentOrderLineItemInput!]!) {
  fulfillmentOrderSplit(
    fulfillmentOrderId: $fulfillmentOrderId
    fulfillmentOrderLineItems: $fulfillmentOrderLineItems
  ) {
    fulfillmentOrders {
      id
      status
      lineItems(first: 50) {
        edges {
          node {
            id
            remainingQuantity
            variant {
              sku
              title
            }
          }
        }
      }
    }
    userErrors {
      field
      message
    }
  }
}
```

## Session Tracking

**Claude MUST emit the following output at each stage. This is mandatory.**

**On start**, emit:
```
╔══════════════════════════════════════════════╗
║  SKILL: Split Shipment Planner               ║
║  Store:                        ║
║  Started:              ║
╚══════════════════════════════════════════════╝
```

**After each step**, emit:
```
[N/TOTAL]   
          → Params: 
          → Result: 
```

If `dry_run: true`, prefix every mutation step with `[DRY RUN]` and do not execute it.

**On completion**, emit:

For `format: human` (default):
```
══════════════════════════════════════════════
OUTCOME SUMMARY
  Original fulfillment order: 
  Split into:                  shipments
  Errors:                     

  Shipment 1: 
  Shipment 2: 
══════════════════════════════════════════════
```

For `format: json`, emit:
```json
{
  "skill": "split-shipment-planner",
  "store": "",
  "started_at": "",
  "completed_at": "",
  "dry_run": true,
  "original_fulfillment_order_id": "",
  "resulting_fulfillment_orders": [],
  "errors": 0
}
```

## Output Format
Human-readable split summary. No CSV output — split results are viewable in Shopify Admin under the order's fulfillment tab.

## Error Handling
| Error | Cause | Recovery |
|-------|-------|----------|
| `THROTTLED` | API rate limit exceeded | Wait 2 seconds, retry |
| `userErrors` — invalid line item | Line item ID not in fulfillment order | Abort and report mismatch |
| `userErrors` — quantity exceeds remaining | Split quantity > remaining quantity | Abort and report per line item |
| Fulfillment order not OPEN | Already fulfilled or cancelled | Abort with status report |

## Best Practices
- Use `dry_run: true` to preview the resulting shipment groups before splitting — a split cannot be reversed.
- Ensure `split_groups` covers all line items in the fulfillment order; any unassigned items will remain in the original (residual) fulfillment order.
- For orders with items shipping from different warehouses, use the `fulfillment-location-routing` skill to move the split groups to the correct locations after splitting.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [40RTY-ai](https://github.com/40RTY-ai)
- **Source:** [40RTY-ai/shopify-admin-skills](https://github.com/40RTY-ai/shopify-admin-skills)
- **License:** MIT
- **Homepage:** http://skills.40rty.ai

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-40rty-ai-shopify-admin-skills-shopify-admin-split-shipment-planner
- Seller: https://agentstack.voostack.com/s/40rty-ai
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.