SunFrog Solutions API Documentation

Environment

The SunFrog Solutions API supports both a staging environment for testing and a live environment for production use. Use the staging environment to validate your integration before going live.

Staging Environment

Testing

Test calls can be made on our test environment, using the following URL:

Base URL

https://devapi.sunfrogsolutions.com/auth/?user=myusername&key=myapikey

Live Environment

Production

Live calls should be made on our live API server:

Base URL

https://api.sunfrogsolutions.com/auth/?user=myusername&key=myapikey

Note: LIVE and Staging API logs can be found in the SunFrog Solutions Manager portal as well.

Authentication

All API requests must be made over HTTPS and with authentication in the request URL as a query parameter. You can access your API keys in the SunFrog Solutions Manager or by contacting your account manager.

Note: Keep your API key secure. Do not expose it in client-side code or public repositories. If you need to rotate your API credentials, you can do so in the SunFrog Solutions Manager.

Query Parameter

https://api.sunfrogsolutions.com/auth/?user=myusername&key=myapikey

Example Request

curl -X GET "https://api.sunfrogsolutions.com/auth/?user=myusername&key=myapikey"

const user = 'myusername';
const key  = 'myapikey';

const response = await fetch(
  `https://api.sunfrogsolutions.com/auth/?user=${user}&key=${key}`
);

const data = await response.json();
console.log(data);

import requests

params = {
    'user': 'myusername',
    'key': 'myapikey'
}

response = requests.get(
    'https://api.sunfrogsolutions.com/auth/',
    params=params
)

data = response.json()
print(data)

using var client = new HttpClient();

var user = "myusername";
var key  = "myapikey";

var response = await client.GetAsync(
    $"https://api.sunfrogsolutions.com/auth/?user={user}&key={key}"
);

var json = await response.Content.ReadAsStringAsync();
Console.WriteLine(json);

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of requests. Error responses include a JSON body with details.

Status Code	Meaning	Description
`200`	OK	Request succeeded
`201`	Created	Resource successfully created
`400`	Bad Request	Invalid request parameters or body
`401`	Unauthorized	Missing or invalid API key
`403`	Forbidden	Valid API key but insufficient permissions
`404`	Not Found	The requested resource does not exist
`429`	Too Many Requests	Rate limit exceeded
`500`	Server Error	Something went wrong on our end

Error Response Format

JSON

{
    "TRACE": 999,
    "MESSAGE": "Invalid Authentication String ",
    "RETURNMESSAGE": "Invalid Authentication String ",
    "EXECUTIONTIME": 14,
    "mode": "test",
    "HASERRORS": true,
    "CONTEXT": 132
}

Print Locations

Available print locations for product art placement. Use the productionApplicationLocationId value when creating products via the API.

Clothing

Location ID	Name
`1`	Front
`2`	Back
`3`	Left Sleeve
`4`	Right Sleeve
`5`	Left Pocket
`45`	Locker Tag

Hats | Headwear

Location ID	Name
`1`	Front
`44`	Under Bill

Drinkware

Location ID	Name
`1`	Front

Footwear

Location ID	Name
`23`	Top Right
`24`	Top Left

Stickers & Wall Art

Location ID	Name
`1`	Front

Important: Tank Tops do not have sleeve print locations. Attempting to assign sleeve locations to these garments will produce errors.

Print Types

Available print/production application types. Use the productionApplicationTypeId value when creating products via the API.

Type ID	Name	Abbreviation
`46`	DTF	`DTF`
`49`	DTF [iSlide]	`UVIDTF`
`50`	Sublimation [Socks]	`SUBL`
`54`	Blank Garment	`FFUL`
`56`	PVC Heat Transfer	`LASR`
`59`	Sublimation [General]	`SUBL`
`2`	Embroidery	`EMBR`
`3`	Decal/Sticker	`STIK`
`10`	Sublimation [Drinkware]	`SUBL`
`16`	Heat Transfer	`BRAND`
`33`	DTF [Patch]	`SUBL`
`34`	Sublimation [Flag]	`SUBFLA`
`35`	Leather	`LASR`
`37`	Embroidery 3D	`EMBR`
`45`	DTF [iSlide Tonal]	`UVIDTF`

Order Statuses

Reference of all possible order status values returned by the API when querying orders.

Order Statuses

Status
`Deleted`
`Hold`
`Printed`
`Refund`
`Shipped`
`Waiting`

Order Item Statuses

Status
`Hold`
`On Order`
`Out of Stock`
`Printed`
`In-Progress`
`Refunded`
`Shipped`
`Waiting`
`Cubed`
`Caught`
`Produced`
`Packaging`
`Deleted`
`Expedite`

Shipping Methods

Available shipping methods and their identifiers. Use the methodName value when creating orders via the API. Weight limits are in ounces.

DHL

Method Name	Display Name	Max Weight	International
`BEX`	BPM Expedited	2464.00 oz	No
`BGN`	BPM Ground	2464.00 oz	No
`EXP`	Parcel Expedited	2464.00 oz	No
`EXP`	Parcel Plus Expedited	2464.00 oz	No
`GND`	Parcel Ground	2464.00 oz	No
`GND`	Parcel Plus Ground	2464.00 oz	No
`MAX`	Parcel Expedited Max	2464.00 oz	No
`PID`	Parcel International Direct Standard	2464.00 oz	Yes
`PIY`	Parcel International Direct Priority	2464.00 oz	Yes
`PKY`	Packet International	2464.00 oz	Yes
`PLT`	Parcel International Direct	2464.00 oz	Yes
`PLY`	Parcel International Standard	2464.00 oz	Yes

FedEx

Method Name	Display Name	Max Weight	International
`FedEx_2_Day`	FedEx 2 Day	2400.00 oz	No
`FedEx_2_Day_AM`	FedEx 2 Day AM	2400.00 oz	No
`FedEx_Express_Saver`	FedEx Express Saver	2400.00 oz	No
`FedEx_Ground`	FedEx Ground	2400.00 oz	No
`FedEx_International_Connect_Plus`	FedEx International Connect Plus	1120.00 oz	Yes
`First_Overnight`	First Overnight	2400.00 oz	No
`Ground_Home_Delivery`	Ground Home Delivery	2400.00 oz	No
`International_Economy`	International Economy	2400.00 oz	Yes
`International_First`	International First	2400.00 oz	Yes
`International_Priority`	International Priority	2400.00 oz	Yes
`One Rate`	FedEx One Rate	1200.00 oz	Yes
`Priority_Overnight`	Priority Overnight	2400.00 oz	No
`Smart_Post`	Smart Post	1120.00 oz	No
`Standard_Overnight`	Standard Overnight	2400.00 oz	No

UPS

Method Name	Display Name	Min Weight	Max Weight	International
`2nd Day Air`	2nd Day Air	0.00 oz	99999.00 oz	No
`2nd Day Air AM`	2nd Day Air AM	0.00 oz	99999.00 oz	No
`3 Day Select`	3 Day Select	0.00 oz	99999.00 oz	No
`Economy Mail Innovations`	Economy Mail Innovations	1.00 oz	70.40 oz	No
`Expedited Mail Innovations`	Expedited Mail Innovations	1.00 oz	16.00 oz	Yes
`First Class Mail`	First Class Mail	0.00 oz	99999.00 oz	No
`Flats`	Flats	0.00 oz	70.40 oz	No
`Ground`	Ground	0.00 oz	99999.00 oz	No
`Next Day Air`	Next Day Air	0.00 oz	99999.00 oz	No
`Next Day Air Early`	Next Day Air Early	0.00 oz	99999.00 oz	No
`Next Day Air Saver`	Next Day Air Saver	0.00 oz	99999.00 oz	No
`Priority Mail`	Priority Mail	0.00 oz	99999.00 oz	No
`Priority Mail Innovations`	Priority Mail Innovations	14.40 oz	1120.00 oz	No
`Standard International`	Standard International	0.00 oz	99999.00 oz	Yes
`SurePost Heavy`	SurePost Heavy	0.00 oz	2464.00 oz	No
`SurePost Light`	SurePost Light	0.00 oz	16.00 oz	No
`Worldwide Expedited`	Worldwide Expedited	0.00 oz	99999.00 oz	Yes
`Worldwide Express`	Worldwide Express	0.00 oz	99999.00 oz	Yes
`Worldwide Express Frieght`	Worldwide Express Frieght	0.00 oz	99999.00 oz	Yes
`Worldwide Express Plus`	Worldwide Express Plus	0.00 oz	99999.00 oz	Yes
`Worldwide Saver`	Worldwide Saver	0.00 oz	99999.00 oz	Yes

USPS

Method Name	Display Name	Max Weight	International
`First Class`	First Class	13.00 oz	Yes
`Priority`	Priority	1120.00 oz	Yes
`USPS_GROUND_ADVANTAGE`	Ground Advantage	0.00 oz	No

Get Merchant Profile

Retrieve basic account information for the authenticated merchant, including contact details, return address, and any sub-merchant IDs linked through shared inventory.

GET /merchant/?user={user}&key={key}

Returns the merchant profile associated with the authenticated API credentials. Includes business info, contact details, return address, and any sub-merchants with shared inventory access.

Query Parameters

Parameter	Type	Required	Description
user	string	Required	Your API username
key	string	Required	Your API key

Response Fields

Field	Type	Description
merchantId	integer	Unique merchant identifier
businessName	string	Business display name
firstName	string	Contact first name
lastName	string	Contact last name
email	string	Contact email address
phone	string	Contact phone number
address	string	Street address line 1
address2	string	Street address line 2
city	string	City
state	string	State or province
zip	string	Postal / ZIP code
country	string	Country
createdOn	datetime	Account creation date
returnAddress	object	Return address with `businessName`, `address`, `address2`, `city`, `state`, `zip`, `country`
subMerchants[]	array	Array of sub-merchant objects with shared inventory access

Sub-Merchant Fields

Field	Type	Description
subMerchantId	integer	Sub-merchant identifier — use as `designatedMerchantId` when creating ASN shipments
subBusinessName	string	Sub-merchant business name

Example Request

Request

curl -X GET "https://api.sunfrogsolutions.com/merchant/?user=myusername&key=myapikey"

JSON — 200 OK

{
  "TRACE": 0,
  "LASTENDPOINT": "Merchant",
  "merchant": {
    "merchantId": 123456,
    "businessName": "My Store",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@mystore.com",
    "phone": "555-123-4567",
    "address": "123 Main St",
    "address2": "Suite 100",
    "city": "Holland",
    "state": "MI",
    "zip": "49423",
    "country": "US",
    "createdOn": "2024-01-15T10:30:00.000",
    "returnAddress": {
      "businessName": "My Store Returns",
      "address": "456 Return Ave",
      "address2": "",
      "city": "Holland",
      "state": "MI",
      "zip": "49423",
      "country": "US"
    },
    "subMerchants": [
      {
        "subMerchantId": 789012,
        "subBusinessName": "My Store - West Coast"
      },
      {
        "subMerchantId": 789013,
        "subBusinessName": "My Store - East Coast"
      }
    ]
  },
  "HASERRORS": false
}

Tip: The subMerchantId values returned in the subMerchants array can be used as the designatedMerchantId when creating ASN shipments to designate inventory for a specific sub-merchant.

Get Product (POD)

Retrieve your print-on-demand product listings. Returns all products by default, or a single product when a publicArtId is provided.

GET /product/?user={user}&key={key}

Returns a list of all POD products associated with your account. To retrieve a specific product, include the optional publicArtId query parameter.

Query Parameters

Parameter	Type	Required	Description
user	string	Required	Your API username
key	string	Required	Your API key
publicArtId	integer	Optional	Return a single product by its public art ID instead of the full list

Response Fields

Field	Type	Description
executionTime	integer	Server-side execution time in milliseconds
mode	string	API mode — `live` or `test`
productlist[]	array	Array of product objects
productType	string	The product type — `pod` for print-on-demand
MockupID	integer	Unique identifier for the product mockup
mockupImage	string	URL for the product mockup image
title	string	Product display title
description	string	Product description text
publicArtId	integer	Unique public art identifier — use this to fetch a single product

Example: List All Products

Request

curl -X GET "https://api.sunfrogsolutions.com/product/?user=myusername&key=myapikey"

JSON — 200 OK

{
  "executionTime": 19,
  "mode": "live",
  "productlist": [
    {
      "productType": "pod",
      "MockupID": 123456001,
      "mockupImage": "https://ao.sunfrog.com/123456/100000001/123456-1-100000001-26060201061853.jpg",
      "description": "A sample product description",
      "title": "SunFrog Classic Black Tee",
      "publicArtId": 100000001
    },
    {
      "productType": "pod",
      "MockupID": 123456002,
      "mockupImage": "https://ao.sunfrog.com/123456/100000002/123456-1-100000002-260602110635655.jpg",
      "description": "Another sample product",
      "title": "SunFrog Logo Hoodie",
      "publicArtId": 100000002
    },
    {
      "productType": "pod",
      "MockupID": 123456003,
      "mockupImage": "https://ao.sunfrog.com/123456/100000003/123456-1-100000003-260529020526903.jpg",
      "description": "8 oz.(US) 13.3 oz.(CA), 50/50 preshrunk cotton/polyester...",
      "title": "SunFrog Crewneck Sweatshirt",
      "publicArtId": 100000003
    }
  ]
}

Example: Get Single Product

Request

curl -X GET "https://api.sunfrogsolutions.com/product/?user=myusername&key=myapikey&publicArtId=100000001"

JSON — 200 OK

{
  "executionTime": 61,
  "mode": "live",
  "productlist": [
    {
      "productType": "pod",
      "MockupID": 123456001,
      "mockupImage": "https://ao.sunfrog.com/123456/100000001/123456-1-100000001-26060201061853.jpg",
      "description": "A sample product description",
      "title": "SunFrog Classic Black Tee",
      "publicArtId": 100000001
    }
  ]
}

Tip: When a publicArtId is provided, the response productlist array contains only the single matching product.

Create Product (POD)

Create a new print-on-demand product listing. The response includes pricing details for each available size variant.

POST /product/?user={user}&key={key}

Creates a new POD product. Send a JSON body with product details and art file URLs. The response returns pricing for all available size variants.

Request Body

Parameter	Type	Required	Description
productTitle	string	Required	Product display title
productType	string	Required	Product type — `POD` (print-on-demand) or `PS`
retailPrice	numeric	Required	Retail price in USD
productStyleId	numeric	Required	Product style ID (e.g. `8` for a basic tee)
defaultColor	string / numeric	Required	Default garment color — name (e.g. `Black`) or color ID
art	array	Required	Array of art objects (see Art Fields below)
productDescription	string	Optional	Product description text
designSku	string	Optional	User-defined SKU for the design
GTIN	numeric	Optional	Global Trade Item Number — replaces `productStyleId`, `designSku`, and `defaultColor`
mfgSku	string	Optional	Manufacturer SKU — in place of `productStyleId` (e.g. `5000`, `3001CVC`)

Art Object Fields

Field	Type	Description
artfile	string (URL)	URL to the art/design file
mockupFile	string (URL)	URL to the product mockup image
productionApplicationTypeId	numeric	Production application type identifier
productionApplicationLocationId	numeric	Production application location identifier
colorCount	numeric	Number of colors in the art (use `999` for full color)

Example Request

JSON Body

{
  "productDescription": "A Product description",
  "productType": "POD",
  "defaultColor": "Black",
  "productTitle": "A Basic Black T-Shirt",
  "art": [
    {
      "colorCount": 999,
      "mockupFile": "https://d2yrwu03yq0f9f.cloudfront.net/mp/123456/m_123456-front-200131020141651.jpg",
      "productionApplicationTypeId": 1,
      "productionApplicationLocationId": 1,
      "artfile": "https://d2yrwu03yq0f9f.cloudfront.net/mp/123456/m_123456-front-200131020141651.jpg"
    }
  ],
  "retailPrice": 19,
  "productStyleId": 8,
  "designSku": "MySku1234"
}

Response

The response includes a pricing array with an entry for each available size variant. Below is a truncated example showing 2 of 8 size entries.

Response Fields

Field	Type	Description
hasErrors	boolean	Whether the request encountered errors
errorMsg	string	Error message (empty on success)
publicArtId	integer	The newly created product's public art ID
executionTime	integer	Server-side execution time in milliseconds
mode	string	API mode — `live` or `test`
pricing[]	array	Array of pricing objects per size variant

Pricing Object Fields

Field	Type	Description
altSizeName	string	Size label (e.g. `S`, `M`, `L`, `XL`)
sizeId	integer	Internal size identifier
costGarment	decimal	Garment cost for this size
costProductionTotal	decimal	Total production cost (printing)
costTotal	decimal	Total cost (garment + production)
weight	decimal	Weight of the product in ounces
mockupId	integer	Mockup identifier
mockupGroupId	integer	Mockup group identifier (matches `publicArtId`)
status	string	Current status (e.g. `ArtQueue`)
billingItemAddons	string (JSON)	JSON string of available add-on options and costs

JSON — 200 OK (truncated)

{
  "hasError": "false",
  "trace": "4",
  "pricing": [
    {
      "proofImageDir": "mp/123456/",
      "mockupId": 123456001,
      "billingItemAddons": "[...]",
      "shipGround": 0,
      "mockupGroupId": 100000010,
      "sizeId": 2,
      "costGarment": 3.46,
      "free": 0,
      "costTotal": 10.96,
      "status": "ArtQueue",
      "invoiceNotes": "[]",
      "proofImage": "123456-1-100000010-260609110635441.jpg",
      "altSizeName": "S",
      "costPrintBack": 0,
      "costPrintFront": 0,
      "colorId": 20,
      "costProductionTotal": 7.5,
      "mockupTypeId": 8,
      "weight": 5.6,
      "byoaTemplateId": 0
    },
    {
      "proofImageDir": "mp/123456/",
      "mockupId": 123456001,
      "billingItemAddons": "[...]",
      "shipGround": 0,
      "mockupGroupId": 100000010,
      "sizeId": 3,
      "costGarment": 2.53,
      "free": 0,
      "costTotal": 10.03,
      "status": "ArtQueue",
      "invoiceNotes": "[]",
      "proofImage": "123456-1-100000010-260609110635441.jpg",
      "altSizeName": "M",
      "costPrintBack": 0,
      "costPrintFront": 0,
      "colorId": 20,
      "costProductionTotal": 7.5,
      "mockupTypeId": 8,
      "weight": 6.6,
      "byoaTemplateId": 0
    }
  ],
  "errorMsg": "",
  "executionTime": 2093,
  "mode": "live",
  "publicArtId": 100000010,
  "hasErrors": false
}

Note: The pricing array contains one entry per available size (S through XXXXXL). The example above is truncated — a full response typically includes 8 size variants.

Get Product (3PL)

Retrieve your third-party logistics product listings. Returns a paginated list of all 3PL products by default, or detailed information for a single product when a publicTypeId is provided.

GET /3pl/?user={user}&key={key}

Returns 3PL product data. Without a publicTypeId, returns a paginated summary list. With a publicTypeId, returns full product details including colors, sizes, pricing, and inventory.

Query Parameters

Parameter	Type	Required	Description
user	string	Required	Your API username
key	string	Required	Your API key
publicTypeId	integer	Optional	Return a single product with full details (colors, sizes, pricing, inventory)

Example: List All 3PL Products

Request

curl -X GET "https://api.sunfrogsolutions.com/3pl/?user=myusername&key=myapikey"

List Response Fields

Field	Type	Description
PRODUCTS[]	array	Array of product summary objects
publicTypeId	integer	Unique 3PL product identifier
productTitle	string	Product display title
productSKU	string	Product SKU
manufacturer	string	Manufacturer name
productType	integer	Product type identifier
imageUrl	string	Image URL for the featured image
PAGINATION	object	Contains `perPage`, `totalPages`, `totalProducts`, `currentPage`

JSON — 200 OK (truncated)

{
  "TRACE": 0,
  "LASTENDPOINT": "3PL",
  "PRODUCTS": [
    {
      "productDescription": "",
      "productType": 1,
      "publicTypeId": 123456,
      "productTitle": "SunFrog Premium Tee",
      "productSKU": "SF-TEE-001",
      "manufacturer": "SunFrog",
      "imageUrl": "https://assets.sunfrog.com/mockupTypes/123456/123456.jpg"
    },
    {
      "productDescription": "",
      "productType": 1,
      "publicTypeId": 123457,
      "productTitle": "SunFrog Logo Cap",
      "productSKU": "SF-CAP-001",
      "manufacturer": "SunFrog",
      "imageUrl": ""
    }
  ],
  "EXECUTIONTIME": 89,
  "mode": "test",
  "PAGINATION": {
    "perPage": 50,
    "totalPages": 1,
    "totalProducts": 8,
    "currentPage": 1
  },
  "HASERRORS": false
}

Example: Get Single 3PL Product

Request

curl -X GET "https://api.sunfrogsolutions.com/3pl/?user=myusername&key=myapikey&publicTypeId=123457"

Single Product Response Fields

Field	Type	Description
PRODUCT	object	Full product detail object
PRODUCTTITLE	string	Product display title
PRODUCTSKU	string	Product SKU
PRODUCTDESCRIPTION	string	Product description text
PUBLICTYPEID	integer	Unique 3PL product identifier
MANUFACTURER	string	Manufacturer name
COSTRETAIL	numeric	Retail cost
COSTWHOLESALE	numeric	Wholesale cost
TAGS[]	array	Array of tag objects with `value` field
COLORS[]	array	Array of color variants (see Color/Size fields below)

Color & Size Fields

Field	Type	Description
colorName	string	Color display name
colorId	integer	Internal color identifier
hexCode	string	CSS hex color code (e.g. `#000000`)
sizes[]	array	Array of size objects for this color
sizeName	string	Size label (e.g. `XS`, `S`, `M`, `L`)
sizeId	integer	Internal size identifier
cost	numeric	Cost for this color/size variant
msrp	numeric	Manufacturer's suggested retail price
stockQty	integer	Current stock quantity on hand
orderedQty	integer	Quantity currently on order
gtin	string	Global Trade Item Number for this variant
upc	string	Universal Product Code for this variant

JSON — 200 OK (truncated to 1 color)

{
  "TRACE": 0,
  "LASTENDPOINT": "3PL",
  "PRODUCT": {
    "PRODUCTDESCRIPTION": "",
    "PRODUCTTYPE": 1,
    "COSTWHOLESALE": 25,
    "COLORS": [
      {
        "sizes": [
          {
            "msrp": 60,
            "sizeName": "XS",
            "cost": 50,
            "gtin": "0001",
            "orderedQty": 0,
            "upc": "1001",
            "sizeId": 1,
            "stockQty": 0
          },
          {
            "msrp": 60,
            "sizeName": "S",
            "cost": 50,
            "gtin": "0002",
            "orderedQty": 0,
            "upc": "1002",
            "sizeId": 2,
            "stockQty": 0
          },
          {
            "msrp": 60,
            "sizeName": "M",
            "cost": 50,
            "gtin": "0003",
            "orderedQty": 0,
            "upc": "1003",
            "sizeId": 3,
            "stockQty": 0
          },
          {
            "msrp": 60,
            "sizeName": "L",
            "cost": 50,
            "gtin": "0004",
            "orderedQty": 0,
            "upc": "1004",
            "sizeId": 4,
            "stockQty": 0
          }
        ],
        "colorName": "Black",
        "colorId": 20,
        "hexCode": "#000000"
      }
    ],
    "PUBLICTYPEID": 123457,
    "PRODUCTTITLE": "SunFrog Logo Cap",
    "COSTRETAIL": 50,
    "PRODUCTSKU": "SF-CAP-001",
    "MANUFACTURER": "SunFrog",
    "TAGS": [
      { "value": "Apparel" },
      { "value": "Headwear" }
    ]
  },
  "EXECUTIONTIME": 178,
  "mode": "test",
  "HASERRORS": false
}

Tip: The single product response includes full COLORS with nested sizes arrays, giving you inventory levels (stockQty), pricing (cost, msrp), and identifiers (gtin, upc) for every color/size combination.

Create Product (3PL)

Create a new third-party logistics product with color variants, size options, and pricing.

POST /3pl/?user={user}&key={key}

Creates a new 3PL product with color/size variants. Send a JSON body with product details, a colors array containing nested sizes, and optional tags.

Request Body

Parameter	Type	Required	Description
productTitle	string	Required	Product display title (max 255 characters)
productSKU	string	Required	Product SKU (max 50 characters)
imageUrl	string	Required	Image URL for the featured image (max 3MB)
productType	integer	Required	Product type identifier
sizeGroupId	integer	Required	Size group identifier — must reference a valid size group
colors	array	Required	Array of color objects with nested sizes (see below)
costRetail	numeric	Optional	Retail cost applied to all inventory records. Default: `0`
costWholesale	numeric	Optional	Wholesale cost applied to all inventory records. Default: `0`
productDescription	string	Optional	Product description text
tags	array	Optional	Array of tag objects, each with a `value` field

Color Object Fields

Field	Type	Required	Description
colorId	integer	Required	Color identifier — must reference a valid color
colorName	string	Required	Color display name (cannot be empty)
sizes	array	Required	Array of size objects — must contain at least one entry
hexCode	string	Optional	CSS hex color code (e.g. `#000000`)

Size Object Fields

Field	Type	Required	Description
sizeId	integer	Required	Size identifier — must reference a valid size
upc	string	Optional	Universal Product Code for this variant
gtin	string	Optional	Global Trade Item Number for this variant
cost	numeric	Optional	Cost for this variant. Default: `0`
msrp	numeric	Optional	Manufacturer's suggested retail price. Default: `0`

Example Request

JSON Body

{
  "productTitle": "Title 30",
  "productSKU": "SKU94",
  "productDescription": "",
  "imageUrl": "https://assets.sunfrog.com/mockupTypes/123456/123456.jpg",
  "costRetail": 50,
  "costWholesale": 25,
  "productType": 1,
  "sizeGroupId": 1,
  "colors": [
    {
      "colorId": 20,
      "colorName": "Black",
      "hexCode": "#000000",
      "sizes": [
        { "sizeId": 1, "upc": "1001", "gtin": "0001", "cost": 50, "msrp": 60 },
        { "sizeId": 2, "upc": "1002", "gtin": "0002", "cost": 50, "msrp": 60 },
        { "sizeId": 3, "upc": "1003", "gtin": "0003", "cost": 50, "msrp": 60 },
        { "sizeId": 4, "upc": "1004", "gtin": "0004", "cost": 50, "msrp": 60 }
      ]
    },
    {
      "colorId": 5,
      "colorName": "Antique Irish Green",
      "hexCode": "#00843d",
      "sizes": [
        { "sizeId": 1, "upc": "2001", "gtin": "0011", "cost": 60, "msrp": 70 },
        { "sizeId": 2, "upc": "2002", "gtin": "0012", "cost": 60, "msrp": 70 },
        { "sizeId": 3, "upc": "2003", "gtin": "0013", "cost": 60, "msrp": 70 },
        { "sizeId": 4, "upc": "2004", "gtin": "0014", "cost": 60, "msrp": 70 }
      ]
    }
  ],
  "tags": [
    { "value": "Tag" },
    { "value": "TEST2" }
  ]
}

Validation Rules

Requirements:

productTitle — cannot be empty, max 255 characters
productSKU — cannot be empty, max 50 characters
productType — cannot be empty
sizeGroupId — must reference a valid size group
colorId — must reference a valid color ID (validated against system records)
colorName — cannot be empty
sizes — each color must have at least one size entry
sizeId — must reference a valid size ID (validated against system records)

Response

JSON — 200 OK

{
  "TRACE": 0,
  "MESSAGE": "Product created successfully.",
  "PUBLICTYPEID": 123458,
  "LASTENDPOINT": "3PL",
  "EXECUTIONTIME": 1084,
  "mode": "test",
  "HASERRORS": false
}

Response Fields

Field	Type	Description
HASERRORS	boolean	Whether the request encountered errors
MESSAGE	string	Success or error message
PUBLICTYPEID	integer	The newly created product's public type ID
EXECUTIONTIME	integer	Server-side execution time in milliseconds
mode	string	API mode — `live` or `test`

Tip: After creating a product, use the returned PUBLICTYPEID with the Get Product (3PL) endpoint to retrieve the full product details including all color/size variants.

Get ASN Shipment

Retrieve Advanced Shipment Notification (ASN) records. Returns a paginated list of shipments by default, or detailed information for a single shipment when a merchantShipmentId is provided. ASN shipments are linked to existing 3PL products.

GET /asn/?user={user}&key={key}

Returns ASN shipment data. Without a merchantShipmentId, returns a paginated list of shipment summaries. With a merchantShipmentId, returns the full shipment details including all line items.

Query Parameters

Parameter	Type	Required	Description
user	string	Required	Your API username
key	string	Required	Your API key
merchantShipmentId	integer	Optional	Return a single shipment with full details including line items
page	integer	Optional	Page number for paginated listing. Default: `1`
statusId	integer	Optional	Filter by status ID. Default: returns non-completed shipments (status < 10)

ASN Status Reference

Status ID	Status Name	Description
`1`	Pending	Shipment created, awaiting shipment. All fields are editable.
`2`	Shipped	Shipment in transit. Only `note`, `containerNumber`, `trackingNumber`, `expectedDate`, and `shippingDate` are editable.
`10`	Completed	Shipment received and processed. No further edits allowed.

Example: List All ASN Shipments

Request

curl -X GET "https://api.sunfrogsolutions.com/asn/?user=myusername&key=myapikey"

List Response Fields

Field	Type	Description
shipments[]	array	Array of shipment summary objects
merchantShipmentId	integer	Unique shipment identifier
asnName	string	Shipment display name
statusId	integer	Current status identifier
statusName	string	Human-readable status name
createdOn	datetime	When the shipment was created
arrivalDate	date	Expected arrival date
shippingDate	date	Date the shipment was shipped
lastUpdatedOn	datetime	Last modification timestamp
trackingNumber	string	Carrier tracking number
carrier	string	Shipping carrier name
poNumber	string	Purchase order number
containerNumber	string	Shipping container number
publicTypeId	integer	3PL product identifier for this shipment
productTitle	string	Product display title
productSKU	string	Product SKU
totalExpected	integer	Total quantity expected across all items
totalReceived	integer	Total quantity received across all items
totalVariants	integer	Number of unique color/size variants in the shipment
imageUrl	string	Product image URL
pagination	object	Contains `currentPage`, `perPage`, `totalShipments`, `totalPages`

JSON — 200 OK

{
  "TRACE": 0,
  "LASTENDPOINT": "ASN",
  "shipments": [
    {
      "merchantShipmentId": 456,
      "asnName": "ASN-2026-0001",
      "statusId": 1,
      "statusName": "Pending",
      "createdOn": "2026-06-15T14:30:00.000",
      "arrivalDate": "2026-07-01",
      "shippingDate": null,
      "lastUpdatedOn": "2026-06-15T14:30:00.000",
      "trackingNumber": "",
      "carrier": "FedEx",
      "poNumber": "PO-12345",
      "containerNumber": "",
      "publicTypeId": 123456,
      "productTitle": "SunFrog Premium Tee",
      "productSKU": "SF-TEE-001",
      "totalExpected": 500,
      "totalReceived": 0,
      "totalVariants": 8,
      "imageUrl": "https://assets.sunfrog.com/mockupTypes/123456/123456.jpg"
    },
    {
      "merchantShipmentId": 457,
      "asnName": "ASN-2026-0002",
      "statusId": 2,
      "statusName": "Shipped",
      "createdOn": "2026-06-10T09:15:00.000",
      "arrivalDate": "2026-06-25",
      "shippingDate": "2026-06-12",
      "lastUpdatedOn": "2026-06-12T11:00:00.000",
      "trackingNumber": "794644790132",
      "carrier": "FedEx",
      "poNumber": "PO-12340",
      "containerNumber": "CONT-9876",
      "publicTypeId": 123457,
      "productTitle": "SunFrog Logo Cap",
      "productSKU": "SF-CAP-001",
      "totalExpected": 200,
      "totalReceived": 0,
      "totalVariants": 4,
      "imageUrl": ""
    }
  ],
  "pagination": {
    "currentPage": 1,
    "perPage": 50,
    "totalShipments": 2,
    "totalPages": 1
  },
  "HASERRORS": false
}

Example: Get Single ASN Shipment

Request

curl -X GET "https://api.sunfrogsolutions.com/asn/?user=myusername&key=myapikey&merchantShipmentId=456"

Single Shipment Response Fields

Field	Type	Description
shipment	object	Full shipment detail object
items[]	array	Array of line item objects (see Item Fields below)
totalExpected	integer	Sum of all `qtyExpected` across items
totalReceived	integer	Sum of all `qtyReceived` across items

Item Fields

Field	Type	Description
merchantShipmentItemId	integer	Unique item identifier
inventoryId	integer	Inventory record identifier
colorId	integer	Color identifier
colorName	string	Color display name
hexCode	string	CSS hex color code
sizeId	integer	Size identifier
sizeName	string	Size display name
qtyExpected	integer	Quantity expected to receive
qtyReceived	integer	Quantity actually received

JSON — 200 OK

{
  "TRACE": 0,
  "LASTENDPOINT": "ASN",
  "shipment": {
    "merchantShipmentId": 456,
    "asnName": "ASN-2026-0001",
    "statusId": 1,
    "statusName": "Pending",
    "createdOn": "2026-06-15T14:30:00.000",
    "arrivalDate": "2026-07-01",
    "shippingDate": null,
    "lastUpdatedOn": "2026-06-15T14:30:00.000",
    "trackingNumber": "",
    "carrier": "FedEx",
    "poNumber": "PO-12345",
    "containerNumber": "",
    "vendor": "Vendor Inc.",
    "vendorStyle": "VS-100",
    "note": "",
    "isSample": false,
    "requiresBackTagging": false,
    "importFreightCost": null,
    "designatedMerchantId": 789012,
    "publicTypeId": 123456,
    "productTitle": "SunFrog Premium Tee",
    "productSKU": "SF-TEE-001",
    "productType": 1,
    "imageUrl": "https://assets.sunfrog.com/mockupTypes/123456/123456.jpg",
    "items": [
      {
        "merchantShipmentItemId": 1001,
        "inventoryId": 50001,
        "colorId": 20,
        "colorName": "Black",
        "hexCode": "#000000",
        "sizeId": 2,
        "sizeName": "S",
        "qtyExpected": 100,
        "qtyReceived": 0
      },
      {
        "merchantShipmentItemId": 1002,
        "inventoryId": 50002,
        "colorId": 20,
        "colorName": "Black",
        "hexCode": "#000000",
        "sizeId": 3,
        "sizeName": "M",
        "qtyExpected": 150,
        "qtyReceived": 0
      },
      {
        "merchantShipmentItemId": 1003,
        "inventoryId": 50003,
        "colorId": 20,
        "colorName": "Black",
        "hexCode": "#000000",
        "sizeId": 4,
        "sizeName": "L",
        "qtyExpected": 250,
        "qtyReceived": 0
      }
    ],
    "totalExpected": 500,
    "totalReceived": 0
  },
  "HASERRORS": false
}

Tip: The single shipment response includes the full items array with qtyExpected and qtyReceived for each color/size variant, giving you a complete view of the shipment's fulfillment progress. The colorId and sizeId values correspond to the same identifiers used in your 3PL product inventory.

Create ASN Shipment

Create a new Advanced Shipment Notification for an existing 3PL product. Each ASN specifies the product, expected arrival date, and a list of color/size/quantity items you plan to ship.

POST /asn/?user={user}&key={key}

Creates a new ASN shipment for a 3PL product. Send a JSON body with the product identifier, expected arrival date, and an items array specifying the color/size combinations and quantities being shipped.

Request Body

Parameter	Type	Required	Description
publicTypeId	integer	Required	3PL product identifier — must reference a product owned by your account
expectedDate	date	Required	Expected arrival date (e.g. `2026-07-15`)
items	array	Required	Array of item objects — must contain at least one entry (see Item Fields below)
designatedMerchantId	integer	Optional	Sub-merchant to receive inventory. Must be a valid shared-inventory sub-merchant (see Merchant endpoint)
carrier	string	Optional	Shipping carrier name (e.g. `FedEx`, `UPS`)
trackingNumber	string	Optional	Carrier tracking number
poNumber	string	Optional	Purchase order number
containerNumber	string	Optional	Shipping container number
shippingDate	date	Optional	Date the shipment was or will be shipped
vendor	string	Optional	Vendor or supplier name
vendorStyle	string	Optional	Vendor style or reference number
note	string	Optional	Free-text note for the shipment
isSample	boolean	Optional	Whether this is a sample shipment. Default: `false`
requiresBackTagging	boolean	Optional	Whether items require back-tagging. Default: `false`
importFreightCost	decimal	Optional	Import freight cost in USD

Item Object Fields

Field	Type	Required	Description
colorId	integer	Required	Color identifier — must exist in the product's inventory
sizeId	integer	Required	Size identifier — must exist in the product's inventory
qtyExpected	integer	Required	Quantity expected to receive — must be greater than `0`

Example Request

JSON Body

{
  "publicTypeId": 123456,
  "expectedDate": "2026-07-15",
  "carrier": "FedEx",
  "trackingNumber": "794644790132",
  "poNumber": "PO-12345",
  "vendor": "Vendor Inc.",
  "vendorStyle": "VS-100",
  "note": "Summer restock",
  "isSample": false,
  "requiresBackTagging": false,
  "designatedMerchantId": 789012,
  "items": [
    { "colorId": 20, "sizeId": 2, "qtyExpected": 100 },
    { "colorId": 20, "sizeId": 3, "qtyExpected": 150 },
    { "colorId": 20, "sizeId": 4, "qtyExpected": 250 },
    { "colorId": 5, "sizeId": 2, "qtyExpected": 50 },
    { "colorId": 5, "sizeId": 3, "qtyExpected": 75 }
  ]
}

Response

JSON — 200 OK

{
  "TRACE": 0,
  "LASTENDPOINT": "ASN",
  "merchantShipmentId": 456,
  "message": "ASN shipment created successfully.",
  "HASERRORS": false
}

Response Fields

Field	Type	Description
HASERRORS	boolean	Whether the request encountered errors
message	string	Success or error message
merchantShipmentId	integer	The newly created shipment's identifier

Validation Rules:

publicTypeId — must reference a valid 3PL product owned by your account
expectedDate — required, must be a valid date
items — must be a non-empty array
Each item's colorId + sizeId must resolve to valid inventory for the specified product
Each item's qtyExpected must be greater than 0
designatedMerchantId — if provided, must be a valid shared-inventory sub-merchant for your account

Tip: Use the Merchant endpoint to retrieve your subMerchantId values if you need to set a designatedMerchantId. Use the Get Product (3PL) endpoint to find valid colorId and sizeId combinations for your product.

Update ASN Shipment

Update an existing ASN shipment's details. Which fields are editable depends on the shipment's current status. Completed shipments (status ≥ 10) cannot be edited.

PUT /asn/?user={user}&key={key}

Updates an existing ASN shipment. Send a JSON body with the merchantShipmentId and any fields you wish to update. At least one updatable field must be provided.

Request Body

Parameter	Type	Required	Description
merchantShipmentId	integer	Required	The shipment identifier to update

Always Editable Fields (status < 10)

Parameter	Type	Description
note	string	Free-text note for the shipment
containerNumber	string	Shipping container number
trackingNumber	string	Carrier tracking number
expectedDate	date	Expected arrival date
shippingDate	date	Date the shipment was shipped

Pending Only Fields (status = 1)

Parameter	Type	Description
carrier	string	Shipping carrier name
poNumber	string	Purchase order number
vendor	string	Vendor or supplier name
vendorStyle	string	Vendor style or reference number
isSample	boolean	Whether this is a sample shipment
requiresBackTagging	boolean	Whether items require back-tagging
importFreightCost	decimal	Import freight cost in USD
designatedMerchantId	integer	Sub-merchant for shared inventory
statusId	integer	Advance status — only `1` → `2` (Pending → Shipped) is allowed
items	array	Update quantities for existing items only — cannot add new items (see Item Fields below)

Item Object Fields (for updates)

Field	Type	Required	Description
colorId	integer	Required	Color identifier — must match an existing item on this shipment
sizeId	integer	Required	Size identifier — must match an existing item on this shipment
qtyExpected	integer	Required	Updated expected quantity

Example Request

JSON Body

{
  "merchantShipmentId": 456,
  "carrier": "UPS",
  "trackingNumber": "1Z999AA10123456784",
  "statusId": 2,
  "items": [
    { "colorId": 20, "sizeId": 2, "qtyExpected": 120 },
    { "colorId": 20, "sizeId": 3, "qtyExpected": 175 }
  ]
}

Response

JSON — 200 OK

{
  "TRACE": 0,
  "LASTENDPOINT": "ASN",
  "merchantShipmentId": 456,
  "message": "Shipment updated successfully.",
  "HASERRORS": false
}

Important:

Completed shipments (status ≥ 10) cannot be edited
Status can only be advanced from 1 (Pending) to 2 (Shipped)
Item quantities can only be updated when the shipment is in Pending status
You can only update existing items on a shipment — new items cannot be added via PUT
designatedMerchantId must be a valid shared-inventory sub-merchant if provided

Get Order via publicOrderId

Retrieve the status of an order using SunFrog's public order ID (returned when the order was created). This endpoint can also be configured as a webhook callback to signal when an order has shipped. To enable this feature, contact your account manager.

GET /orders/?user={user}&key={key}&publicOrderId={publicOrderId}

Returns order status, tracking information, and item-level details by SunFrog’s internal publicOrderId.

Query Parameters

Parameter	Type	Required	Description
user	string	Required	Your API username
key	string	Required	Your API key
publicOrderId	numeric	Required	SunFrog’s internal order ID (returned from Create Order)

Example Request

Request

curl -X GET "https://api.sunfrogsolutions.com/orders/?user=myusername&key=myapikey&publicOrderId=30"

JSON — 200 OK

{
  "orders": [
    {
      "receivedDate": "2020-04-02T13:56:31.150",
      "orderComplete": 1,
      "orderId": 123456789,
      "publicOrderId": 30,
      "orderItems": [
        {
          "receivedDate": "2020-04-02T13:56:31.150",
          "publicOrderItemId": 30,
          "itemStatus": "Complete",
          "shipMethod": "Priority",
          "trackingNumber": 123456
        }
      ]
    }
  ],
  "mode": "test",
  "hasErrors": false
}

Get Order via OrderId

Retrieve the status of an order using your client-supplied order ID.

GET /orders/?user={user}&key={key}&OrderId={OrderId}

Searches for an order based on the client-supplied orderid you provided when creating the order.

Query Parameters

Parameter	Type	Required	Description
user	string	Required	Your API username
key	string	Required	Your API key
OrderId	numeric	Required	Your client-supplied order ID (the `orderid` you sent when creating the order)

Example Request

Request

curl -X GET "https://api.sunfrogsolutions.com/orders/?user=myusername&key=myapikey&OrderId=12345"

JSON — 200 OK

{
  "orders": [
    {
      "receivedDate": "2020-04-02T13:56:31.150",
      "orderComplete": 1,
      "orderId": 123456789,
      "publicOrderId": 30,
      "orderItems": [
        {
          "receivedDate": "2020-04-02T13:56:31.150",
          "publicOrderItemId": 30,
          "itemStatus": "Complete",
          "shipMethod": "Priority",
          "trackingNumber": 123456
        }
      ]
    }
  ],
  "mode": "test",
  "hasErrors": false
}

Get Order via OrderItemId

Retrieve the status of an order using your client-supplied order item ID.

GET /orders/?user={user}&key={key}&OrderItemId={OrderItemId}

Searches for an order based on the client-supplied orderItemId you provided within an item when creating the order.

Query Parameters

Parameter	Type	Required	Description
user	string	Required	Your API username
key	string	Required	Your API key
OrderItemId	numeric	Required	Your client-supplied order item ID (the `orderItemId` you sent within an item)

Example Request

Request

curl -X GET "https://api.sunfrogsolutions.com/orders/?user=myusername&key=myapikey&OrderItemId=30"

JSON — 200 OK

{
  "orders": [
    {
      "receivedDate": "2020-04-02T13:56:31.150",
      "orderComplete": 1,
      "orderId": 123456789,
      "publicOrderId": 30,
      "orderItems": [
        {
          "receivedDate": "2020-04-02T13:56:31.150",
          "publicOrderItemId": 30,
          "itemStatus": "Complete",
          "shipMethod": "Priority",
          "trackingNumber": 123456
        }
      ]
    }
  ],
  "mode": "test",
  "hasErrors": false
}

Response Fields

Field	Type	Description
hasErrors	boolean	Whether the request encountered errors
orders[]	array	Array of matching order objects
orderId	numeric	Internal order identifier
publicOrderId	integer	SunFrog public order ID
receivedDate	string	ISO 8601 timestamp when the order was received
orderComplete	integer	Completion flag — `1` = complete, `0` = in progress
mode	string	API mode — `live` or `test`

Order Item Fields

Field	Type	Description
publicOrderItemId	integer	Public order item identifier
itemStatus	string	Current status (e.g. `Complete`, `Waiting`, `In Production`)
shipMethod	string	Shipping method used (e.g. `Priority`, `First Class`)
trackingNumber	numeric	Shipment tracking number (populated when shipped)
receivedDate	string	ISO 8601 timestamp when the item was received

Webhook Support: These endpoints can also be configured as a webhook callback to automatically notify your system when an order has shipped. To enable webhook callbacks, contact our development / sales team.

Create Order

Submit one or more orders with existing products or create new products inline. Supports batch ordering and optional quote mode for price checks.

POST /orders/?user={user}&key={key}

Creates one or more orders. Send a JSON body with an orders array. Each order must include a shipping address and an items array. Items can reference existing products or include a product object to create a new POD product inline.

Order Object Fields

Parameter	Type	Required	Description
name	string	Required	Recipient full name
address1	string	Required	Primary shipping address line
city	string	Required	Shipping city
state	string	Required	Shipping state/province
postalcode	string / numeric	Required	Shipping postal/zip code
country	string	Required	Country code (e.g. `US`, `CA`)
email	string	Required	Customer email address
items	array	Required	Array of line item objects (see Items below)
orderid	string	Optional	Your external order ID for reference
quoteOrder	boolean	Optional	Set to `true` to get pricing without committing the order
address2	string	Optional	Secondary address line (apt, suite, etc.)
phone	string	Optional	Customer phone number
shipCarrier	string	Optional	Carrier for passthru shipping (e.g. `UPS`, `USPS`, `FEDEX`)
shipMethod	string	Optional	Shipping method for passthru (e.g. `Economy Mail Innovations`, `2nd Day Air`)

Items — Existing Product

Use these fields to order an existing product by referencing its identifiers.

Field	Type	Required	Description
qty	numeric	Required	Quantity to order
publicArtId	numeric	Required	Public art ID of the existing product
productStyleId	numeric	Required	Product style identifier
colorId	numeric / string	Required*	Color identifier — can use `colorName` alternatively
colorName	string	Optional*	Color name — can be used in place of `colorId`
sizeId	numeric	Required*	Size identifier — can use `sizeName` alternatively
sizeName	string	Optional*	Size name — can be used in place of `sizeId`
orderItemId	string	Optional	Your external order item ID
styleCode	string	Optional	Concatenation of `productStyleId-colorId-sizeId` — replaces individual params
GTIN	numeric	Optional	Replaces `productStyleId`, `sizeId`, `colorId`, and `styleCode`
UPC	string	Optional	Can be used in place of `colorId`, `productStyleId`, `sizeId`, `publicArtId`
mfgSku	string	Optional	Manufacturer SKU — replaces `productStyleId` (e.g. `3001`, `8000`)

Items — New Product (Inline Creation)

Include a product object within an item to create a new POD product and order it simultaneously.

Field	Type	Required	Description
product	object	Required	Product definition object (see nested fields below)
product.productTitle	string	Required	Product display title
product.productType	string	Required	Product type — `POD` or `PS`
product.retailPrice	numeric	Required	Retail price in USD
product.art	array	Required	Array of art objects with `artfile`, `mockupFile`, `productionApplicationTypeId`, `productionApplicationLocationId`
product.productDescription	string	Optional	Product description text
product.designSku	string	Optional	User-defined design SKU
product.styleCode	string	Optional	Concatenation of `productStyleId-colorId-sizeId`

Example 1: Order with Existing Product

JSON Body

{
  "orders": [
    {
      "orderid": 12345,
      "postalcode": 10001,
      "city": "New York",
      "country": "US",
      "phone": "1234567897",
      "state": "NY",
      "address1": "101 Main St.",
      "email": "help@sunfrog.com",
      "name": "Bob Customer",
      "address2": "",
      "items": [
        {
          "qty": 1,
          "productStyleId": 8,
          "colorId": 20,
          "publicArtId": 100000001,
          "sizeId": 3
        }
      ]
    }
  ]
}

JSON — 200 OK

{
  "errors": [],
  "orders": [
    {
      "customerOrderId": 123,
      "orderid": 123,
      "publicOrderId": 20,
      "batchId": 2,
      "name": "Joe Customer",
      "address1": "101 Main St.",
      "address2": "",
      "city": "New York",
      "state": "MI",
      "postalcode": 10001,
      "country": "US",
      "iso2": "US",
      "email": "",
      "phone": 0000000000,
      "totalItems": 1,
      "costTotal": 9.35,
      "shipTotal": 3.27,
      "shipWhere": "USPS 2-5 Days",
      "mailClass": "First Class",
      "mailPiece": "Thick Envelopes",
      "weight": 14.6,
      "items": [
        {
          "publicArtId": 100000001,
          "productStyleId": 8,
          "colorId": 20,
          "sizeId": 4,
          "altSizeName": "L",
          "qty": 1,
          "serviceType": "POD",
          "status": "Waiting",
          "costGarment": 2.35,
          "costProductionTotal": 7,
          "costTotal": 9.35,
          "shippingTotal": 3.27,
          "weight": 7.3,
          "mockupId": 123456001,
          "proofImage": "123456-front-200317050305118.jpg",
          "proofImageDir": "mp/123456/",
          "billingItemAddOns": [
            {
              "addonTitle": "DTG - [GT3]",
              "productionApplicationTypeId": 1,
              "productionApplicationLocationId": 1,
              "addonCost": 7
            }
          ]
        }
      ]
    }
  ],
  "mode": "test",
  "hasErrors": false
}

Example 2: Order with New Product (Inline)

JSON Body

{
  "orders": [
    {
      "address1": "1234 Main St.",
      "email": "some@email.com",
      "name": "Joe Customer",
      "address2": "",
      "postalcode": 10001,
      "orderid": 456,
      "city": "New York",
      "country": "US",
      "phone": "1234567890",
      "state": "NY",
      "items": [
        {
          "productStyleId": 204,
          "sizeName": "L",
          "qty": 1,
          "colorId": 20,
          "product": {
            "productDescription": "Amazing Sweatshirt!",
            "productTitle": "Sweatshirt",
            "retailPrice": 29.99,
            "designSku": "",
            "art": [
              {
                "mockupFile": "https://s3.amazonaws.com/artfiles.sunfrog.com/.../front.png",
                "productionApplicationTypeId": 1,
                "productionApplicationLocationId": 1,
                "artfile": "https://s3.amazonaws.com/artfiles.sunfrog.com/.../front.png"
              }
            ]
          }
        }
      ]
    }
  ]
}

JSON — 200 OK

{
  "errors": [],
  "orders": [
    {
      "customerOrderId": 123,
      "orderid": 123,
      "publicOrderId": 19,
      "batchId": 2,
      "name": "Joe Customer",
      "address1": "101 Main St.",
      "city": "New York",
      "state": "MI",
      "postalcode": 10001,
      "country": "US",
      "totalItems": 1,
      "costTotal": 10.08,
      "shipTotal": 6.19,
      "shipWhere": "USPS 2-3 Days",
      "mailClass": "Priority",
      "weight": 44,
      "items": [
        {
          "publicArtId": 43,
          "productStyleId": 204,
          "colorId": 20,
          "sizeId": 4,
          "altSizeName": "L",
          "qty": 1,
          "serviceType": "POD",
          "status": "Waiting",
          "costGarment": 10.08,
          "costTotal": 10.08,
          "shippingTotal": 6.19,
          "weight": 22,
          "product": {
            "productDescription": "Amazing Sweatshirt!",
            "productType": "POD",
            "defaultColor": 20,
            "productStyleId": 204,
            "productTitle": "Sweatshirt that amazes",
            "art": [
              {
                "colorCount": 999,
                "mockupFile": "https://s3.amazonaws.com/artfiles.sunfrog.com/.../front.png",
                "productionApplicationTypeId": 1,
                "productionApplicationLocationId": 1,
                "artfile": "https://s3.amazonaws.com/artfiles.sunfrog.com/.../front.png"
              }
            ],
            "retailPrice": 29.99,
            "designSku": ""
          }
        }
      ]
    }
  ],
  "mode": "test",
  "hasErrors": false
}

Response Fields

Field	Type	Description
hasErrors	boolean	Whether the request encountered errors
errors[]	array	Array of error messages (empty on success)
orders[]	array	Array of created order objects
publicOrderId	integer	SunFrog's internal order ID
customerOrderId	integer	Customer-facing order identifier
costTotal	decimal	Total product cost for the order
shipTotal	decimal	Total shipping cost
shipWhere	string	Shipping carrier and estimated delivery
mailClass	string	Mail class used (e.g. `First Class`, `Priority`)
mode	string	API mode — `live` or `test`

Tip: Set quoteOrder to true in the order object to receive full pricing (including shipping estimates) without actually placing the order.

Get Catalog

Retrieve top-level product information from the SunFrog catalog. Use the unfiltered call to list all available products, or pass a productStyleId to get variant details and costs.

GET /catalog/?user={user}&key={key}

Returns a list of products available through the API. Without a productStyleId, returns top-level product information. With a productStyleId, returns full variant detail including colors, sizes, pricing, and stock levels.

Query Parameters

Parameter	Type	Required	Description
user	string	Required	Your API username
key	string	Required	Your API key
productStyleId	numeric	Optional	Filter by product style to get variant-level detail and costs

Product Fields

Field	Type	Description
productStyleId	integer	Product style identifier
typeName	string	Product display name (e.g. `Ollie Cap - AD527`)
core	integer	Whether this is a core product (`1` = yes)
coreQty	integer	Number of core color options
colorOptions	string	Color option codes available
lowCost	decimal	Lowest variant cost
highCost	decimal	Highest variant cost
productOptions[]	array	Array of variant objects (populated when filtering by `productStyleId`)

Product Option Fields

Field	Type	Description
colorid	integer	Color identifier
colorname	string	Color display name
hexcode	string	CSS hex color code
sizeId	integer	Size identifier
sizeName	string	Size display name (e.g. `OS`, `S`, `M`)
altName	string	Alternate size label (e.g. `One Size`)
cost	decimal	Garment cost for this variant
productionCost	decimal	Production/printing cost
productionApplicationTypeId	integer / null	Production application type (null if not applicable)
inventoryid	integer	Inventory record identifier
stockQty	integer	Current stock quantity
inStock	integer	Whether the variant is in stock (`1` = yes, `0` = no)
inventoryAlert	string / null	Inventory alert message (null if no alerts)
restock_estimate	string / null	Estimated restock date (null if not applicable)
sortOrder	integer	Display sort order

Example: Filtered by productStyleId

Request

curl -X GET "https://api.sunfrogsolutions.com/catalog/?user=myusername&key=myapikey&productStyleId=1306"

JSON — 200 OK (truncated to 1 variant)

{
  "products": [
    {
      "core": 1,
      "productStyleId": 1306,
      "coreQty": 2,
      "lowCost": 3.9293,
      "colorOptions": "OL102",
      "typeName": "Ollie Cap - AD527",
      "highCost": 5.5556,
      "productOptions": [
        {
          "sizeName": "OS",
          "productionCost": 4.00,
          "inventoryAlert": null,
          "inStock": 0,
          "restock_estimate": null,
          "productionApplicationTypeId": null,
          "sizeId": 23,
          "stockQty": 0,
          "sortOrder": 1,
          "cost": 3.92,
          "inventoryid": 25799,
          "colorname": "Black",
          "colorid": 20,
          "altName": "One Size",
          "hexcode": "#000000"
        }
      ]
    }
  ]
}

Tip: Use the unfiltered call (without productStyleId) to discover available products, then pass a specific productStyleId to get full variant details including color/size combinations, costs, and inventory levels.

Get Catalog Item

Retrieve detailed variant information for a specific product style, including colors, sizes, costs, GTIN codes, and manufacturer details.

GET /catalog/?user={user}&key={key}&productStyleId={productStyleId}

Returns option, size, and cost information for a specified product. The sizeId, colorId, and productStyleId returned here are the parameters used when creating products and placing orders.

Query Parameters

Parameter	Type	Required	Description
user	string	Required	Your API username
key	string	Required	Your API key
productStyleId	numeric	Required	The product style ID to retrieve variant details for

Product Fields

Field	Type	Description
productStyleId	integer	Product style identifier
typeName	string	Product display name
manufacturer	string	Product manufacturer (e.g. `Gildan`)
styleDescription	string	Full product description with material, weight, and construction details
artOwnerId	integer	Art owner identifier
core	integer	Whether this is a core product (`1` = yes)
coreQty	integer	Number of core color options
colorOptions	string / numeric	Color option code or count
lowCost	decimal	Lowest variant cost
highCost	decimal	Highest variant cost
productOptions[]	array	Array of color/size variant objects

Variant Fields (productOptions)

Field	Type	Description
colorid	integer	Color identifier — used when creating products and orders
colorname	string	Color display name
hexcode	string	CSS hex color code
sizeId	integer	Size identifier — used when creating products and orders
sizeName	string	Size display name (e.g. `S`, `M`, `L`)
altName	string	Alternate size label (e.g. `XXL`, `XXXL`)
cost	decimal	Garment cost for this variant
gtin	numeric	Global Trade Item Number for this variant
sortOrder	integer	Display sort order

Example Request

Request

curl -X GET "https://api.sunfrogsolutions.com/catalog/?user=myusername&key=myapikey&productStyleId=8"

JSON — 200 OK (truncated to 3 variants)

{
  "products": [
    {
      "core": 1,
      "coreQty": 28,
      "lowCost": 2.35,
      "colorOptions": 5000,
      "typeName": "Heavy Cotton T-Shirt",
      "highCost": 5.23,
      "productOptions": [
        {
          "sizeName": "S",
          "sortOrder": 2,
          "cost": 2.35,
          "colorname": "Antique Cherry Red",
          "colorid": 3,
          "sizeId": 2,
          "altName": "S",
          "hexcode": "#971b2f",
          "gtin": 1234567989
        },
        {
          "sizeName": "M",
          "sortOrder": 3,
          "cost": 2.35,
          "colorname": "Antique Cherry Red",
          "colorid": 3,
          "sizeId": 3,
          "altName": "M",
          "hexcode": "#971b2f",
          "gtin": 1234567988
        },
        {
          "sizeName": "2XL",
          "sortOrder": 6,
          "cost": 4.15,
          "colorname": "Antique Cherry Red",
          "colorid": 3,
          "sizeId": 6,
          "altName": "XXL",
          "hexcode": "#971b2f",
          "gtin": 1234567985
        }
      ],
      "productStyleId": 8,
      "artOwnerId": 0,
      "manufacturer": "Gildan",
      "styleDescription": "This heavy cotton t-shirt is made of durable, 5.3 oz, pre-shrunk, 100% cotton material..."
    }
  ]
}

Tip: The sizeId, colorid, and productStyleId values returned from this endpoint are the exact parameters needed when creating POD products and placing orders.

Get ASN Shipment

Retrieve a paginated list of your ASN (Advanced Shipment Notification) shipments, or a single shipment with its items by specifying a merchantShipmentId.

GET /asn/?user={user}&key={key}

Returns a paginated list of shipments or a single shipment with its items. Use query parameters to filter and paginate results.

Query Parameters

Parameter	Type	Required	Description
user	string	Required	Your API username
key	string	Required	Your API key
merchantShipmentId	integer	Optional	If provided, returns a single shipment with its items. Otherwise returns a paginated list.
page	integer	Optional	Page number for paginated results. Defaults to `1`.
statusId	integer	Optional	Filter by shipment status. See status table below.

Shipment Statuses

Status ID	Name
`1`	Pending
`2`	Shipped
`10`	Complete

Example Request — List

Request

curl -X GET "https://api.sunfrogsolutions.com/asn/?user=myusername&key=myapikey&page=1&statusId=1"

JSON — 200 OK (paginated list)

{
  "shipments": [
    {
      "merchantShipmentId": 12345,
      "merchantShipmentStatusId": 1,
      "statusName": "Pending",
      "mockupTypeId": 1001,
      "productTitle": "Classic T-Shirt",
      "productSKU": "TSH-001",
      "productType": "3PL",
      "carrier": "UPS",
      "trackingNumber": "1Z999AA10123456784",
      "poNumber": "PO-2026-001",
      "containerNumber": "CNTR-001",
      "expectedDate": "2026-07-15",
      "vendor": "Acme Apparel",
      "creationDateTime": "2026-06-29T12:00:00Z",
      "totalExpected": 500,
      "totalReceived": 0
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 3,
    "totalRecords": 125,
    "perPage": 50
  },
  "hasErrors": false
}

Example Request — Single Shipment

Request

curl -X GET "https://api.sunfrogsolutions.com/asn/?user=myusername&key=myapikey&merchantShipmentId=12345"

JSON — 200 OK (single shipment)

{
  "merchantShipmentId": 12345,
  "merchantShipmentStatusId": 1,
  "statusName": "Pending",
  "mockupTypeId": 1001,
  "productTitle": "Classic T-Shirt",
  "carrier": "UPS",
  "trackingNumber": "1Z999AA10123456784",
  "poNumber": "PO-2026-001",
  "containerNumber": "CNTR-001",
  "expectedDate": "2026-07-15",
  "shippingDate": null,
  "vendor": "Acme Apparel",
  "vendorStyle": "ACM-100",
  "note": "First batch of summer collection",
  "isSample": false,
  "requiresBackTagging": true,
  "importFreightCost": 150.00,
  "priority": false,
  "shipmentType": 0,
  "departureDate": "2026-07-01",
  "launchDate": "2026-07-20",
  "creationDateTime": "2026-06-29T12:00:00Z",
  "items": [
    {
      "merchantShipmentItemId": 50001,
      "inventoryId": 99001,
      "colorId": 20,
      "colorName": "Black",
      "sizeId": 4,
      "sizeName": "L",
      "qtyExpected": 100,
      "qtyReceived": 0,
      "merchantShipmentItemStatusId": 1,
      "itemStatusName": "Pending"
    }
  ],
  "hasErrors": false
}

Create ASN Shipment

Create a new ASN shipment with one or more items. Items are specified using colorId and sizeId pairs (available from the Catalog endpoint). Inventory orderedQty is automatically incremented for each item.

POST /asn/?user={user}&key={key}

Creates a new ASN shipment in Pending status. Requires a valid publicTypeId (your product/mockup type), an expectedDate, and at least one item.

Request Body (JSON)

Parameter	Type	Required	Description
publicTypeId	integer	Required	The mockup type / product ID for this shipment
expectedDate	date	Required	Expected arrival date (format: `YYYY-MM-DD`)
items	array	Required	Array of item objects. At least one item is required. See item fields below.
carrier	string	Optional	Shipping carrier (e.g. `UPS`, `FedEx`)
trackingNumber	string	Optional	Shipment tracking number
poNumber	string	Optional	Purchase order number
containerNumber	string	Optional	Shipping container number
shippingDate	date	Optional	Date the shipment was sent (format: `YYYY-MM-DD`)
departureDate	date	Optional	Departure date (format: `YYYY-MM-DD`)
launchDate	date	Optional	Product launch date (format: `YYYY-MM-DD`)
vendor	string	Optional	Vendor / supplier name
vendorStyle	string	Optional	Vendor's style number or SKU
note	string	Optional	Internal note for this shipment
isSample	boolean	Optional	Whether this is a sample shipment. Defaults to `false`.
requiresBackTagging	boolean	Optional	Whether items need back tagging. Defaults to `false`.
importFreightCost	decimal	Optional	Import freight cost for the shipment
shipmentType	integer	Optional	Shipment type identifier. Defaults to `0`.
priority	boolean	Optional	Whether this is a priority shipment. Defaults to `false`.
designatedMerchantId	integer	Optional	Sub-merchant ID for shared inventory accounts

Item Fields

Field	Type	Required	Description
colorId	integer	Required	Color identifier (from the Catalog)
sizeId	integer	Required	Size identifier (from the Catalog)
qtyExpected	integer	Required	Quantity expected for this color/size combination. Must be greater than 0.

Example Request

JSON Body

{
  "publicTypeId": 1001,
  "expectedDate": "2026-07-15",
  "carrier": "UPS",
  "trackingNumber": "1Z999AA10123456784",
  "poNumber": "PO-2026-001",
  "vendor": "Acme Apparel",
  "vendorStyle": "ACM-100",
  "note": "First batch of summer collection",
  "requiresBackTagging": true,
  "shipmentType": 0,
  "departureDate": "2026-07-01",
  "launchDate": "2026-07-20",
  "priority": false,
  "items": [
    { "colorId": 20, "sizeId": 3, "qtyExpected": 100 },
    { "colorId": 20, "sizeId": 4, "qtyExpected": 150 },
    { "colorId": 20, "sizeId": 5, "qtyExpected": 120 },
    { "colorId": 45, "sizeId": 3, "qtyExpected": 80 },
    { "colorId": 45, "sizeId": 4, "qtyExpected": 50 }
  ]
}

JSON — 200 OK

{
  "merchantShipmentId": 12345,
  "message": "ASN shipment created successfully.",
  "hasErrors": false
}

Note: Inventory orderedQty is automatically incremented for each item when the shipment is created. The colorId and sizeId values can be obtained from the Get Catalog Item endpoint.

Update ASN Shipment

Update an existing ASN shipment's header fields and/or item quantities. Field editability depends on the current shipment status. Completed shipments (status ≥ 10) cannot be edited.

PUT /asn/?user={user}&key={key}

Updates a shipment. Only send the fields you want to change — all fields are optional except merchantShipmentId. The API enforces which fields can be edited based on the shipment's current status.

Request Body (JSON)

Parameter	Type	Required	Description
merchantShipmentId	integer	Required	The ID of the shipment to update

Always Editable (status < 10)

These fields can be updated on any non-completed shipment.

Parameter	Type	Description
note	string	Internal note
containerNumber	string	Shipping container number
trackingNumber	string	Shipment tracking number
expectedDate	date	Expected arrival date (`YYYY-MM-DD`)
shippingDate	date	Date shipment was sent (`YYYY-MM-DD`). Pass empty string to clear.
isSample	boolean	Whether this is a sample shipment
requiresBackTagging	boolean	Whether items need back tagging
priority	boolean	Whether this is a priority shipment
shipmentType	integer	Shipment type identifier
departureDate	date	Departure date (`YYYY-MM-DD`). Pass empty string to clear.

Pending Only (status = 1)

These fields can only be updated when the shipment is in Pending status.

Parameter	Type	Description
carrier	string	Shipping carrier
poNumber	string	Purchase order number
vendor	string	Vendor / supplier name
vendorStyle	string	Vendor style number
importFreightCost	decimal	Import freight cost
designatedMerchantId	integer	Sub-merchant ID (shared inventory)
launchDate	date	Product launch date (`YYYY-MM-DD`). Pass empty string to clear.
statusId	integer	Advance status from `1` (Pending) to `2` (Shipped). Only this transition is allowed.
items	array	Array of item objects to update quantities. Uses the same `colorId`/`sizeId`/`qtyExpected` format as create. Inventory `orderedQty` is adjusted by the delta.

Example Request

JSON Body

{
  "merchantShipmentId": 12345,
  "note": "Updated delivery window",
  "expectedDate": "2026-07-20",
  "trackingNumber": "1Z999AA10123456999",
  "priority": true,
  "items": [
    { "colorId": 20, "sizeId": 3, "qtyExpected": 120 },
    { "colorId": 20, "sizeId": 4, "qtyExpected": 200 }
  ]
}

JSON — 200 OK

{
  "merchantShipmentId": 12345,
  "message": "ASN shipment updated successfully.",
  "hasErrors": false
}

Example: Mark as Shipped

JSON Body

{
  "merchantShipmentId": 12345,
  "statusId": 2
}

Important: When updating item quantities, inventory orderedQty is adjusted by the delta (new quantity − old quantity). You can only update items on Pending shipments. Completed shipments (status ≥ 10) cannot be edited.