Snap Order Creator

Snap Integration REST API

Overview

Programmatic access to order management and shipping label generation through ShipStation.

Base URLs
Development: http://127.0.0.1:5000/api/v1
Production: https://snap.shipnoble.com/api/v1
Data Format
  • Request: JSON
  • Response: JSON
  • Date: ISO 8601 (e.g., 2025-09-03T12:00:00)

Authentication

All endpoints (except user creation and key validation) require an API key via Bearer auth.

Authorization: Bearer sk_your_api_key_here

Rate Limiting

Limits are enforced per API key; headers include remaining quota and reset time.

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1705315200

Error Handling

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message",
    "details": "Additional context",
    "timestamp": "2025-09-03T10:30:00Z",
    "request_id": "req_12345678"
  }
}
GET https://snap.shipnoble.com/api/v1/health
Description

Basic health check.

Status
  • 200 OK
Example Response
{
  "success": true,
  "data": {
    "status": "healthy",
    "timestamp": "...",
    "version": "v1.0.0"
  }
}
POST https://snap.shipnoble.com/api/v1/orders/submit
Description

Create/update an order and immediately generate a shipping label in one call.

Required
  • orderNumber, orderDate, shipTo, weight, dimensions, items (≥1)
Optional
  • orderId, orderKey, shipByDate, orderStatus, customerUsername, customerEmail
  • billTo, customerNotes, requestedShippingService, serviceCode
  • internationalOptions, customsCountryCode
Response
{
  "success": true,
  "data": {
    "shippingLabelBase64": "...",
    "courierService": "shipnoble_...",
    "trackingNumber": "...",
    "trackingLink": "https://...",
    "orderNumber": "...",
    "expectedDeliveryDate": "3-5 business days"
  }
}
Example (detailed)
{
  "orderNumber": "WEB-1725360000",
  "orderKey": "ext-12345",
  "orderDate": "2025-09-03T12:00:00",
  "shipByDate": "2025-09-05T12:00:00",
  "orderStatus": "awaiting_shipment",
  "customerUsername": "acme_user",
  "customerEmail": "customer@example.com",
  "billTo": {
    "name": "John Doe",
    "company": "ACME Billing",
    "street1": "123 Billing Street",
    "city": "Toronto",
    "state": "ON",
    "postalCode": "M5V 3A8",
    "country": "CA"
  },
  "shipTo": {
    "name": "Jane Doe",
    "company": "ACME Receiving",
    "street1": "456 Shipping Ave",
    "city": "Vancouver",
    "state": "BC",
    "postalCode": "V6B 1A1",
    "country": "CA",
    "phone": "+1 604-555-9876",
    "residential": false
  },
  "items": [
    {
      "sku": "WIDGET-PRO",
      "name": "Professional Widget",
      "quantity": 1,
      "unitPrice": 149.99,
      "weight": { "value": 2.0, "units": "pounds" }
    },
    {
      "sku": "MANUAL-001",
      "name": "User Manual",
      "quantity": 1,
      "unitPrice": 9.99,
      "weight": { "value": 0.5, "units": "pounds" }
    }
  ],
  "customerNotes": "Leave at front desk.",
  "requestedShippingService": "ShipNoble Canada Express",
  "serviceCode": "canada_zone_skip_express",
  "weight": { "value": 2.5, "units": "pounds" },
  "dimensions": { "length": 12.0, "width": 10.0, "height": 6.0, "units": "inches" },
  "internationalOptions": {
    "contents": "merchandise",
    "customsItems": null
  },
  "customsCountryCode": "CA"
}
Address Model (billTo, shipTo)
Field Name Data Type Description Required
namestringName of personRequired
companystringName of companyOptional
street1stringFirst line of addressRequired
street2stringSecond line of addressOptional
street3stringThird line of addressOptional
citystringCity nameRequired
statestringState or provinceRequired
postalCodestringPostal/ZIP codeRequired
countrystringTwo-letter ISO country code (e.g., "CA", "US")Required
phonestringTelephone numberOptional
residentialbooleanWhether the address is residentialOptional
addressVerifiedstring (read-only)ShipStation validation statusOptional
Order Item Model (items[])
Field Name Data Type Description Required
orderItemIdnumber (read-only)System-generated identifierOptional
lineItemKeystringIdentifier from originating systemOptional
skustringProduct SKU identifierOptional
namestringProduct nameRequired
imageUrlstringPublic URL to product imageOptional
weightobjectSee Weight model belowOptional
quantitynumberQuantity orderedRequired
unitPricenumberUnit sell priceOptional
taxAmountnumberTax per itemOptional
shippingAmountnumberShipping per itemOptional
warehouseLocationstringWarehouse bin/locationOptional
optionsarrayItem optionsOptional
productIdnumberAssociated product IDOptional
fulfillmentSkustringAlternate fulfillment SKUOptional
adjustmentbooleanNon-physical adjustment (discount, etc.)Optional
upcstringUPC codeOptional
createDatestring (read-only)Created timestamp in ShipStationOptional
modifyDatestring (read-only)Last modified timestampOptional
Weight Model
Field Name Data Type Description Required
valuenumberWeight valueRequired
unitsstringAllowed: "pounds", "ounces", "grams", "kilograms"Required
WeightUnitsnumber (read-only)Numeric unit equivalentOptional
Dimensions Model
Field Name Data Type Description Required
lengthnumberPackage lengthRequired
widthnumberPackage widthRequired
heightnumberPackage heightRequired
unitsstringAllowed: "inches", "centimeters"Required
Carrier & Service Options
Carrier Service Name Service Code
ShipNoble ShipNoble Canada Expedited Postal shipnoble_canada_expedited_postal
ShipNoble Canada Express Postal shipnoble_canada_express_postal
ShipNoble Canada Zone Skip Express shipnoble_canada_zone_skip_express
ShipNoble Express Courier Domestic shipnoble_express_courier_domestic
ShipNoble Ground Courier Domestic shipnoble_ground_courier_domestic
ShipNoble Canada Lettermail shipnoble_canada_lettermail
ShipNoble (International/US) ShipNoble USA Economy Postal (First Class Tracked) shipnoble_usa_economy_postal
ShipNoble USA Midnight Priority Postal shipnoble_usa_midnight_priority_postal
ShipNoble International Fully Tracked Packet (DDU) shipnoble_postnl_packet_tracked
ShipNoble International Fully Tracked Parcel (DDU) shipnoble_postnl_gateway_parcel
ShipNoble International Partially Tracked Postal (DDU) shipnoble_postnl_packet_untracked
Note: Provide both carrierCode and serviceCode when creating labels. If you use the combined /orders/submit endpoint and only send requestedShippingService, we resolve it to an appropriate Shipnoble service code under the hood.
Order Status Values
Status Value Description
awaiting_paymentOrder awaiting payment
awaiting_shipmentOrder awaiting shipment
shippedOrder shipped
on_holdOrder on hold
cancelledOrder cancelled
pending_fulfillmentOrder pending fulfillment
Customs Country Code
Field Name Data Type Description
customsCountryCodestringISO country code (Alpha-2: "CA", Alpha-3: "CAN", or UN M49 numeric)

Note: ISO codes are internationally recognized (e.g., .us, .fr TLDs; CAN for Canada at international events). Use the appropriate code per your customs requirements.

Order Creation Examples
HTTP Request (cURL)
curl -X POST "https://snap.shipnoble.com/api/v1/orders/submit" \
  -H "Authorization: Bearer sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "orderNumber": "WEB-1725360000",
    "orderDate": "2025-09-03T12:00:00",
    "shipTo": {
      "name": "Jane Doe",
      "company": "ACME Receiving",
      "street1": "456 Shipping Ave",
      "city": "Vancouver",
      "state": "BC",
      "postalCode": "V6B 1A1",
      "country": "CA",
      "phone": "+1 604-555-9876",
      "residential": false
    },
    "items": [
      {
        "sku": "WIDGET-PRO",
        "name": "Professional Widget",
        "quantity": 1,
        "unitPrice": 149.99,
        "weight": { "value": 2.0, "units": "pounds" }
      }
    ],
    "weight": { "value": 2.5, "units": "pounds" },
    "dimensions": { "length": 12.0, "width": 10.0, "height": 6.0, "units": "inches" }
  }'
Python Example
import json
import requests

url = "https://snap.shipnoble.com/api/v1/orders/submit"
headers = {
    "Authorization": "Bearer sk_your_api_key_here",
    "Content-Type": "application/json"
}

data = {
    "orderNumber": "WEB-1725360000",
    "orderDate": "2025-09-03T12:00:00",
    "shipTo": {
        "name": "Jane Doe",
        "company": "ACME Receiving",
        "street1": "456 Shipping Ave",
        "city": "Vancouver",
        "state": "BC",
        "postalCode": "V6B 1A1",
        "country": "CA",
        "phone": "+1 604-555-9876",
        "residential": False
    },
    "items": [
        {
            "sku": "WIDGET-PRO",
            "name": "Professional Widget",
            "quantity": 1,
            "unitPrice": 149.99,
            "weight": {"value": 2.0, "units": "pounds"}
        }
    ],
    "weight": {"value": 2.5, "units": "pounds"},
    "dimensions": {"length": 12.0, "width": 10.0, "height": 6.0, "units": "inches"}
}

response = requests.post(url, headers=headers, json=data)
result = response.json()

if result["success"]:
    print(f"Label generated! Tracking: {result['data']['trackingNumber']}")
    # Save the base64 label
    import base64
    with open("shipping_label.pdf", "wb") as f:
        f.write(base64.b64decode(result["data"]["shippingLabelBase64"]))
else:
    print(f"Error: {result['error']['message']}")
JavaScript/Node.js Example
const fetch = require('node-fetch'); // or use fetch in browser

const url = 'https://snap.shipnoble.com/api/v1/orders/submit';
const headers = {
    "Authorization": "Bearer sk_your_api_key_here",
    "Content-Type": "application/json"
};

const data = {
    orderNumber: "WEB-1725360000",
    orderDate: "2025-09-03T12:00:00",
    shipTo: {
        name: "Jane Doe",
        company: "ACME Receiving",
        street1: "456 Shipping Ave",
        city: "Vancouver",
        state: "BC",
        postalCode: "V6B 1A1",
        country: "CA",
        phone: "+1 604-555-9876",
        residential: false
    },
    items: [
        {
            sku: "WIDGET-PRO",
            name: "Professional Widget",
            quantity: 1,
            unitPrice: 149.99,
            weight: { value: 2.0, units: "pounds" }
        }
    ],
    requestedShippingService: "ShipNoble Canada Express",
    serviceCode: "canada_zone_skip_express",
    weight: { value: 2.5, units: "pounds" },
    dimensions: { length: 12.0, width: 10.0, height: 6.0, units: "inches" }
};

fetch(url, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(data)
})
.then(response => response.json())
.then(result => {
    if (result.success) {
        console.log(`Label generated! Tracking: ${result.data.trackingNumber}`);
        // Save the base64 label
        const fs = require('fs');
        const buffer = Buffer.from(result.data.shippingLabelBase64, 'base64');
        fs.writeFileSync('shipping_label.pdf', buffer);
    } else {
        console.log(`Error: ${result.error.message}`);
    }
})
.catch(error => console.error('Request failed:', error));
Important Notes
  • Replace API Key: Use your actual API key from the self-service generation
  • Base URL: Use production URL in live environment
  • Error Handling: Always check the success field in response
  • Label Storage: The shippingLabelBase64 is a PDF that needs to be decoded
  • Required Fields: orderNumber, orderDate, shipTo, weight, dimensions, items
GET https://snap.shipnoble.com/api/v1/status?orderNumber=... or trackingNumber=...
Description

Lookup a shipment by order number or tracking number. The API queries ShipStation and returns the shipmentId, a status (if available), and normalized tracking details (status, estimated delivery, events).

Query Parameters
  • orderNumber (string) — optional
  • trackingNumber (string) — optional
  • Provide at least one of the above.
Status
  • 200 OK, 404 Not Found, 502/500 on upstream error
Example Response
{
  "success": true,
  "data": {
    "success": true,
    "shipmentId": "287201437",
    "status": "in_transit",
    "data": { /* ShipStation shipment object */ },
    "tracking": {
      "trackingNumber": "U900000000555147",
      "carrier": "shipoble",
      "status": "In Transit",
      "estimatedDelivery": "2025-09-07",
      "events": [ /* tracking events */ ]
    }
  }
}
GET Status Examples
HTTP Request (cURL)
curl -X GET "https://snap.shipnoble.com/api/v1/status?trackingNumber=U900000000555147"
Python Example
import requests

url = "https://snap.shipnoble.com/api/v1/status"
params = { "trackingNumber": "U900000000555147" }
res = requests.get(url, params=params)
print(res.json())
JavaScript/Node.js Example
const fetch = require('node-fetch');

const url = 'https://snap.shipnoble.com/api/v1/status?trackingNumber=U900000000555147';
fetch(url)
  .then(r => r.json())
  .then(console.log)
  .catch(console.error);