Single-Package Order Workflow (Monocolis)

This guide demonstrates the complete workflow for creating and managing a single-package order through the Wing API v3.

Overview

A single-package order workflow involves three main steps:

1. Authentication - Obtain an access token
2. Create Order - Create an order with one fulfillment order
3. Create Parcel - Generate shipping label and tracking

Step 1: Authentication

First, obtain an access token using your credentials:

mutation {
  createAccessToken(
    input: { email: "your_email@example.com", password: "your_password" }
  ) {
    accessToken
    refreshToken
    expiresAt
  }
}

Response:

{
  "data": {
    "createAccessToken": {
      "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "refreshToken": "refresh_token_here...",
      "expiresAt": "2024-03-10T15:30:00Z"
    }
  }
}

Store the accessToken - it will be used in all subsequent requests with the Authorization: Bearer <accessToken> header.

Step 2: Create Order

Create a new order with a single fulfillment order containing your products:

mutation {
  createOrder(
    input: {
      ref: "ORDER-2024-001"
      recipient: {
        firstName: "Marie"
        lastName: "Dupont"
        email: "marie.dupont@example.com"
        phone: "+33612345678"
        line1: "45 Rue de la République"
        line2: "Appartement 3B"
        city: "Lyon"
        zip: "69002"
        countryCode: "FR"
        company: "Tech Corp"
      }
      fulfillmentOrders: [
        {
          service: STANDARD
          products: [
            {
              designation: "Wireless Keyboard"
              sku: "KB-WIRELESS-001"
              ean: "1234567890123"
              quantity: 2
              price: 49.99
              weight: 0.6
              length: 45.0
              width: 15.0
              height: 3.0
            }
            {
              designation: "USB Mouse"
              sku: "MOUSE-USB-002"
              quantity: 2
              price: 19.99
              weight: 0.15
              length: 12.0
              width: 7.0
              height: 4.0
            }
          ]
          isInsuranceEnabled: true
          isSignatureEnabled: false
        }
      ]
    }
  ) {
    id
    ref
    status
    createdAt
    recipient {
      id
      firstName
      lastName
      email
      line1
      city
      zip
      countryCode
    }
    fulfillmentOrders {
      id
      status
      service
      products {
        id
        designation
        sku
        quantity
      }
    }
  }
}

Response:

{
  "data": {
    "createOrder": {
      "id": "ord_abc123xyz",
      "ref": "ORDER-2024-001",
      "status": "PENDING",
      "createdAt": "2024-03-10T10:00:00Z",
      "recipient": {
        "id": "rec_xyz789",
        "firstName": "Marie",
        "lastName": "Dupont",
        "email": "marie.dupont@example.com",
        "line1": "45 Rue de la République",
        "city": "Lyon",
        "zip": "69002",
        "countryCode": "FR"
      },
      "fulfillmentOrders": [
        {
          "id": "fo_def456",
          "status": "PENDING",
          "service": "STANDARD",
          "products": [
            {
              "id": "fop_111",
              "designation": "Wireless Keyboard",
              "sku": "KB-WIRELESS-001",
              "quantity": 2
            },
            {
              "id": "fop_222",
              "designation": "USB Mouse",
              "sku": "MOUSE-USB-002",
              "quantity": 2
            }
          ]
        }
      ]
    }
  }
}

Important: Save the fulfillmentOrders[0].id value (fo_def456 in this example) - you'll need it for the next step.

Step 3: Create Fulfillment Parcel

Once the order is created, generate a shipping label by creating a fulfillment parcel:

mutation {
  createFulfillmentParcel(
    input: {
      fulfillmentOrderId: "fo_def456"
      organizationPickupId: "pickup_location_123"
    }
  ) {
    id
    trackingNumber
    trackingUrl
    carrierLabel
    status
    createdAt
    fulfillmentOrder {
      id
      status
      order {
        id
        ref
      }
    }
  }
}

Response:

{
  "data": {
    "createFulfillmentParcel": {
      "id": "parcel_xyz123",
      "trackingNumber": "1Z999AA10123456784",
      "trackingUrl": "https://track.wing.eu/1Z999AA10123456784",
      "carrierLabel": "https://labels.wing.eu/parcel_xyz123.pdf",
      "status": "CREATED",
      "createdAt": "2024-03-10T10:05:00Z",
      "fulfillmentOrder": {
        "id": "fo_def456",
        "status": "LABEL_CREATED",
        "order": {
          "id": "ord_abc123xyz",
          "ref": "ORDER-2024-001"
        }
      }
    }
  }
}

Complete JavaScript Example

Here's a complete working example in JavaScript:

const WING_API_URL = 'https://api-developer.wing.eu/v3'

async function singlePackageOrderWorkflow() {
  // Step 1: Authenticate
  const authResponse = await fetch(WING_API_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      query: `
        mutation {
          createAccessToken(input: {
            email: "${process.env.WING_EMAIL}"
            password: "${process.env.WING_PASSWORD}"
          }) {
            accessToken
          }
        }
      `,
    }),
  })

  const { data: authData } = await authResponse.json()
  const accessToken = authData.createAccessToken.accessToken

  console.log('✓ Authenticated successfully')

  // Step 2: Create Order
  const orderResponse = await fetch(WING_API_URL, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      query: `
        mutation CreateOrder($input: OrderToCreateInput!) {
          createOrder(input: $input) {
            id
            ref
            fulfillmentOrders {
              id
              status
            }
          }
        }
      `,
      variables: {
        input: {
          ref: `ORDER-${Date.now()}`,
          recipient: {
            firstName: 'Marie',
            lastName: 'Dupont',
            email: 'marie.dupont@example.com',
            phone: '+33612345678',
            line1: '45 Rue de la République',
            city: 'Lyon',
            zip: '69002',
            countryCode: 'FR',
          },
          fulfillmentOrders: [
            {
              service: 'STANDARD',
              products: [
                {
                  designation: 'Wireless Keyboard',
                  sku: 'KB-WIRELESS-001',
                  quantity: 2,
                  price: 49.99,
                  weight: 0.6,
                },
              ],
            },
          ],
        },
      },
    }),
  })

  const { data: orderData } = await orderResponse.json()
  const fulfillmentOrderId = orderData.createOrder.fulfillmentOrders[0].id

  console.log(`✓ Order created: ${orderData.createOrder.ref}`)
  console.log(`  Fulfillment Order ID: ${fulfillmentOrderId}`)

  // Step 3: Create Parcel
  const parcelResponse = await fetch(WING_API_URL, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      query: `
        mutation CreateParcel($input: CreateFulfillmentParcelInput!) {
          createFulfillmentParcel(input: $input) {
            id
            trackingNumber
            trackingUrl
            carrierLabel
          }
        }
      `,
      variables: {
        input: {
          fulfillmentOrderId: fulfillmentOrderId,
          organizationPickupId: process.env.WING_PICKUP_LOCATION_ID,
        },
      },
    }),
  })

  const { data: parcelData } = await parcelResponse.json()

  console.log(`✓ Shipping label created`)
  console.log(
    `  Tracking Number: ${parcelData.createFulfillmentParcel.trackingNumber}`,
  )
  console.log(
    `  Tracking URL: ${parcelData.createFulfillmentParcel.trackingUrl}`,
  )
  console.log(`  Label PDF: ${parcelData.createFulfillmentParcel.carrierLabel}`)

  return {
    order: orderData.createOrder,
    parcel: parcelData.createFulfillmentParcel,
  }
}

// Run the workflow
singlePackageOrderWorkflow()
  .then(result => {
    console.log('\n✓ Workflow completed successfully!')
    console.log(JSON.stringify(result, null, 2))
  })
  .catch(error => {
    console.error('✗ Workflow failed:', error)
  })

Status Flow

Understanding the status transitions throughout the workflow:

Step	Order Status	Fulfillment Order Status	Parcel Status
After createOrder	PENDING	PENDING	-
After createFulfillmentParcel	PROCESSING	LABEL_CREATED	CREATED
After carrier pickup	IN_TRANSIT	IN_TRANSIT	IN_TRANSIT
After delivery	DELIVERED	DELIVERED	DELIVERED

Common Use Cases

Order with Pickup Point Delivery

For delivery to a carrier pickup point (relay point):

fulfillmentOrders: [
  {
    service: RELAY
    carrierPickupId: "CHRP-12345"
    carrierPickupName: "Relay Point Lyon Centre"
    products: [...]
  }
]

Order with Signature Required

For deliveries requiring recipient signature:

fulfillmentOrders: [
  {
    service: STANDARD
    isSignatureEnabled: true
    products: [...]
  }
]

Order with Insurance

For high-value shipments:

fulfillmentOrders: [
  {
    service: STANDARD
    isInsuranceEnabled: true
    products: [
      {
        designation: "Laptop Computer"
        price: 1499.99
        ...
      }
    ]
  }
]

Error Handling

Common errors and solutions:

Error	Cause	Solution
UNAUTHORIZED	Invalid or expired token	Refresh your access token using createAccessToken
INVALID_RECIPIENT	Missing required recipient fields	Ensure firstName, lastName, email, phone, line1, city, zip, and countryCode are provided
INVALID_PRODUCT	Missing required product fields	Ensure designation, price, quantity, and weight are provided for each product
INVALID_SERVICE	Invalid shipping service	Use valid WingService enum values (STANDARD, EXPRESS, RELAY, etc.)
FULFILLMENT_ORDER_NOT_FOUND	Invalid fulfillmentOrderId	Verify the fulfillmentOrderId from createOrder response
PICKUP_LOCATION_NOT_FOUND	Invalid organizationPickupId	Verify your pickup location ID in Wing dashboard

Next Steps

• Learn about Multi-Package Order Workflows for orders with multiple packages
• Explore Order Management to query and update orders
• Check Parcel Tracking for tracking information

Related API Operations

• createAccessToken - Authenticate and obtain access token
• createOrder - Create a new order
• createFulfillmentParcel - Generate shipping label
• order - Query order details
• fulfillmentOrder - Query fulfillment order details