Generate a UCC-128 (GS1-128) Label

Overview

Orderful offers a label printing API that generates a ZPL (Zebra Programming Language) file. This file can then be sent to a compatible printer to print a shipping label. The shipping labels Orderful generates include barcodes in GS1-128 (formerly UCC / EAN-128) format, including SSCC-18 barcodes where required.

Generating a shipping label is a three step process:

  1. You POST to the /labels endpoint with the appropriate data for that company.
  2. Orderful will respond with a text payload in ZPL format.
  3. You Send the ZPL content to your printer.

📘

Print Density

Orderful's print templates are built for a print density of 8 dpmm (203 dpi). If you print a label and it appears much too big or small, please confirm your print density setting.

Currently Orderful supports generating shipping labels for the following companies:

To request support for a different company, please contact Orderful Support.

Label Validation

If any required information is missing or otherwise non-compliant with either Orderful or the company's requirements, the API will return an error describing the problem. For example, if the "Ship From Name" is missing, the API will return the following error:

{
    "type": "argumentError",
    "ref": "user",
    "message": "There are errors with your label data.",
    "errors": [
        {
            "type": "argumentError",
            "ref": "shipFrom.name",
            "message": "Field must be provided for this label type."
        }
    ]
}

Shipping Label Examples

In order to use your Shipping Label API you will need to pass the label data to our /labels endpoint along with an API key for your organization.

📘

Authentication

For more information about retrieving and using your API Key please see the Authentication section of our API reference.

H-E-B (Mixed)

For a full description see our H-E-B Mixed UCC-128 Label Requirements.

H-E-B (Mixed) JSON Payload

{
    "type": "HEB_MIXED",
    "shipFrom": {
        "name": "Supplier Name",
        "address1": "123 Example St",
        "city": "Linden",
        "state": "NJ",
        "zip": "07036"
    },
    "shipTo": {
        "name": "H-E-B",
        "address1": "4750 Wendeland Rd",
        "city": "Temple",
        "state": "TX",
        "zip": "76504"
    },
    "shipment": {
        "sscc-18": "(00)00052177513895717",
        "billOfLadingNumber": "1234567890",
        "proNumber": "1234567890"
    },
    "carrier":{
        "name": "Carrier Name"
    }, 
    "purchaseOrder": {
        "number": "12345"
    }
}

H-E-B (Mixed) ZPL Response

Orderful will return a HTTP 201 Created along with the ZPL-format text to send to your label printer:

^XA
^CF0,30

^FO0,0^GB406,250,2^FS
^FO20,15^FDFROM:^FS
^FO20,50^FDSupplier Name^FS

[...]

^XZ

H-E-B (Mixed) Shipping Label Example

H-E-B (Standard)

For a full description see our H-E-B Standard Label Requirements.

H-E-B (Standard) JSON Payload

{
    "type": "HEB_STANDARD",
    "shipFrom": {
        "name": "Supplier Name",
        "address1": "123 Example St",
        "city": "Linden",
        "state": "NJ",
        "zip": "07036"
    },
    "shipTo": {
        "name": "H-E-B",
        "address1": "4750 Wendeland Rd",
        "city": "Temple",
        "state": "TX",
        "zip": "76504"
    },
    "shipment": {
        "sscc-18": "(00)00052177513895717",
        "billOfLadingNumber": "1234567890",
        "proNumber": "1234567890"
    },
    "pallet" : {
        "number": 10
    },
    "carrier":{
        "name": "Carrier Name"
    }, 
    "purchaseOrder": {
        "number": "12345"
    },
    "item": {
        "number": "10",
        "description": "Item description",
        "gtin": "92834",
        "productDate": "07/07/2023"
    }
}

H-E-B (Standard) ZPL Response

Orderful will return a HTTP 201 Created along with the ZPL-format text to send to your label printer:

^XA
^CF0,30
^FO0,0^GB406,250,2^FS
^FO20,15^FDFROM:^FS

[...]

^XZ

H-E-B (Standard) Shipping Label Example

Home Depot

For a full description of our Home Depot JSON label requirements see our Home Depot Label Requirements.

Home Depot JSON Payload

{
    "type": "THE_HOME_DEPOT",
    "shipFrom": {
        "name": "Your Company",
        "address1": "1234 Main St",
        "address2": "Unit 1",
        "city": "Pasadena",
        "state": "CA",
        "zip": "12345"
    },
    "shipTo": {
        "name": "The Home Depot",
        "address1": "2455 Paces Ferry Rd",
        "address2": "Unit 2",
        "city": "Atlanta",
        "state": "GA",
        "zip": "30339"
    },
    "carrier": {
        "name": "USPS"
    },
    "shipment": {
        "billOfLadingNumber": "ABC1234567890",
        "proNumber": "ABC1234567890",
        "sscc-18": "ABC1234567890ABC1234567890"
    },
    "store": {
        "number": "1234"
    },
    "purchaseOrder": {
        "number": "1234567890"
    },
    "pallet": {
        "number": 1,
        "max": 1
    },
    "carton": {
        "number": 1
    }
}

Home Depot ZPL Response

Orderful will return a HTTP 201 Created along with the ZPL-format text to send to your label printer:

^XA
^CF0,25

^FO0,0^GB305,203,2^FS
^FO20,25^FDFrom:^FS
^FO20,50^FDYour Company^FS

[...]

^XZ

Home Depot Shipping Label Example

Macy's

For a full description of our Macy's JSON label requirements see our Macy's Label Requirements.

Macy's JSON Payload

{
    "type": "MACYS",
    "shipFrom": {
        "name": "Your Company",
        "address1": "1234 Main St",
        "address2": "Unit 1",
        "city": "Pasadena",
        "state": "CA",
        "zip": "12345"
    },
    "shipTo": {
        "name": "Macy's",
        "careOf": "Secaucus Macy's Logistics DC",
        "address1": "500 Meadowlands Pkwy.",
        "address2": "Unit 2",
        "city": "Secaucus",
        "state": "NJ",
        "zip": "07094"
    },
    "carrier": {
        "name": "USPS"
    },
    "shipment": {
        "billOfLadingNumber": "ABC1234567890",
        "proNumber": "ABC1234567890",
        "sscc-18": "ABC1234567890ABC1234567890"
    },
    "purchaseOrder": {
        "number": "1234567890",
        "type": "REPLENISHMENT"
    },
    "department": {
        "number": "1234"
    },
    "store": {
        "number": "1234",
        "name": "Rochester"
    }
}

Macy's ZPL Response

Orderful will return a HTTP 201 Created along with the ZPL-format text to send to your label printer:

^XA
^CF0,25

^FO0,0^GB305,203,2^FS
^FO20,20^FDFROM^FS
^FO20,50^FDYour Company^FS

[...]
 
^XZ

Macy's Shipping Label Example

Nordstrom

For a full description of our Nordstrom JSON label requirements see our Nordstrom Label Requirements.

Nordstrom JSON Payload

{
    "type": "NORDSTROM",
    "shipFrom": {
        "name": "Your Company",
        "address1": "1234 Main St",
        "address2": "Unit 1",
        "city": "Pasadena",
        "state": "CA",
        "zip": "12345"
    },
    "shipTo": {
        "name": "Nordstrom",
        "address1": "2345 2nd St",
        "address2": "Unit 2",
        "city": "New York",
        "state": "NY",
        "zip": "23456"
    },
    "carrier": {
        "name": "USPS"
    },
    "shipment": {
        "billOfLadingNumber": "ABC1234567890",
        "proNumber": "ABC1234567890",
        "sscc-18": "ABC1234567890ABC1234567890"
    },
    "purchaseOrder": {
        "number": "1234567890"
    },
    "department": {
        "number": "1234"
    },
    "distributionCenter": {
        "number": "1234"
    },
    "case": {
        "pack": 1
    },
    "carton": {
        "max": 1,
        "number": 1
    },
    "store": {
        "number": "1234"
    }
}

Nordstrom ZPL Response

Orderful will return a HTTP 201 Created along with the ZPL-format text to send to your label printer:

^XA
^CF0,25

^FO0,0^GB305,162,2^FS
^FO15,10^FDFrom^FS
^FO40,30^FDYour Company^FS

[...]
 
^XZ

Nordstrom Shipping Label Example

Sephora

For a full description of our Sephora JSON label requirements see our Sephora UCC-128 Label Requirements.

Sephora JSON Payload

{
    "type": "SEPHORA",
    "shipFrom": {
        "name": "Fragrant Perfumery",
        "address1": "A-scent Drive",
        "city": "Jacksonville",
        "state": "FL",
        "zip": "32218"
    },
    "shipTo": {
        "name": "Sephora U.S.A., L.L.C.",
        "address1": "4522 Mercedes Drive",
        "city": "Belcamp",
        "state": "MD",
        "zip": "21017-0367"
    },
    "carrier": {
        "name": "NEMF"
    },
    "shipment": {
        "billOfLadingNumber": "3333333323232323"
    },
    "purchaseOrder": {
        "number": "12345"
    },
    "department": {
        "number": "10"
    },
    "carton": {
        "number": 4,
        "max": 5
    },
    "store": {
        "number": "0001"
    }
}

Sephora ZPL Response

Orderful will return a HTTP 201 Created along with the ZPL-format text to send to your label printer:

^XA
^CF0,25

^FO0,0^GB355,203,2^FS
^FO20,25^FDFROM^FS

[...]
 
^XZ

Sprouts Shipping Label Example

Sprouts Farmers Market

For a full description of our Sprouts JSON label requirements see our Sprouts UCC-128 Label Requirements.

Sprouts JSON Payload

{
    "type": "SPROUTS_FARMERS_MARKET",
    "shipFrom": {
        "name": "Your Company",
        "address1": "1234 Main St",
        "address2": "Unit 1",
        "city": "Pasadena",
        "state": "CA",
        "zip": "12345",
        "country": "USA"
    },
    "shipTo": {
        "name": "Sprouts DC Fullerton",
        "address1": "1829 E Orangethorpe Ave",
        "address2": "Building 1",
        "city": "Fullerton",
        "state": "CA",
        "zip": "92831",
        "country": "USA"
    },
    "carrier": {
        "name": "USPS"
    },
    "shipment": {
        "billOfLadingNumber": "3333333323232323",
        "proNumber": "1514151627849572635235",
        "sscc-18": "(00)12345678901234567"
    },
    "purchaseOrder": {
        "number": "12345"
    },
    "case": {
        "pack": 4
    },
    "carton": {
        "number": 1,
        "max": 2
    },
    "item": {
        "number": "44555",
        "description": "Item description"
    }
}

Sprouts ZPL Response

Orderful will return a HTTP 201 Created along with the ZPL-format text to send to your label printer:

XA
^CF0,25

^FO0,0^GB406,244,2^FS
^FO20,15^FDShip From:^FS

 [...]
 
 ^XZ

Sprouts Shipping Label Example

Walmart (Case Domestic)

📘

This is the shipping label for a domestic case shipment. Other types of shipping labels are not currently supported.

For a full description of our Walmart JSON label requirements see our Walmart Label Requirements

Walmart JSON Payload

{
    "type": "WALMART_CASE_DOMESTIC",
    "shipFrom": {
        "name": "Your Company",
        "address1": "1234 Main St",
        "address2": "Unit 1",
        "city": "Pasadena",
        "state": "CA",
        "zip": "12345"
    },
    "shipTo": {
        "name": "Walmart DC 1234",
        "address1": "2345 2nd St",
        "address2": "Unit 2",
        "city": "New York",
        "state": "NY",
        "zip": "23456"
    },
    "carrier": {
        "name": "USPS"
    },
    "shipment": {
        "billOfLadingNumber": "ABC1234567890",
        "proNumber": "ABC1234567890",
        "sscc-18": "ABC1234567890ABC1234567890"
    },
    "purchaseOrder": {
        "number": "1234567890",
        "type": "1234"
    },
    "department": {
        "number": "1234"
    },
    "distributionCenter": {
        "number": "1234"
    },
    "item": {
        "number": "1234567890"
    }
}

Walmart ZPL Response

Orderful will return a HTTP 201 Created along with the ZPL-format text to send to your label printer:

^XA
^CF0,25

^FO0,0^GB305,270,2^FS
^FO20,20^FDShip From:^FS
^FO20,60^FDYour Company^FS

[...]

^XZ

Walmart Shipping Label Example

Report an Error

If you experience any problems with your shipping label, please contact Orderful support.